pytest-socket

A plugin to use with Pytest to disable or restrict socket calls during tests to ensure network calls are prevented.

---

Features

• Disables all network calls flowing through Python's socket interface, including DNS resolution.
• Restricts connections to an allow-list of hosts, IP addresses, or CIDR network ranges.
• Allows Unix domain sockets selectively, for example when testing async code.
• Applies globally via CLI flags, or per-test via fixtures and markers.

Requirements

• Pytest 7.0 or greater
• Python 3.10 or greater

Installation

You can install pytest-socket via pip from PyPI:

pip install pytest-socket

or add to your pyproject.toml for uv:

[project.optional-dependencies]
dev = [
    "pytest-socket",
]

Usage

Run pytest --disable-socket, tests should fail on any access to socket or libraries using socket with a SocketBlockedError.

To add this flag as the default behavior, add this section to your pytest.ini:

[pytest]
addopts = --disable-socket

or add this to your setup.cfg:

[tool:pytest]
addopts = --disable-socket

or update your conftest.py to include:

from pytest_socket import disable_socket

def pytest_runtest_setup():
    disable_socket()

Each blocked call also emits a SocketBlockedWarning (a UserWarning), so it stays visible even when code catches the error. To silence it, add a warning filter to your pytest.ini:

[pytest]
filterwarnings = ignore::pytest_socket.SocketBlockedWarning

or, in pyproject.toml, filterwarnings = ["ignore::pytest_socket.SocketBlockedWarning"].

If you exceptionally want to enable socket for one particular execution pass --force-enable-socket. It takes precedence over --disable-socket.

To enable Unix sockets during the test run (e.g. for async), add this option:

[pytest]
addopts = --disable-socket --allow-unix-socket

To enable specific tests use of socket, pass in the fixture to the test or use a marker:

def test_explicitly_enable_socket(socket_enabled):
    assert socket.socket(socket.AF_INET, socket.SOCK_STREAM)


@pytest.mark.enable_socket
def test_explicitly_enable_socket_with_mark():
    assert socket.socket(socket.AF_INET, socket.SOCK_STREAM)

To allow only specific hosts per-test:

@pytest.mark.allow_hosts(['127.0.0.1'])
def test_explicitly_enable_socket_with_mark():
    assert socket.socket.connect(('127.0.0.1', 80))

or for whole test run

[pytest]
addopts = --allow-hosts=127.0.0.1,127.0.1.1

Entries may be hostnames, IP addresses, or CIDR network ranges such as 192.168.0.0/24.

Frequently Asked Questions

Q: Why is network access disabled in some of my tests but not others?

A: pytest's default fixture scope is "function", which socket_enabled uses. If you create another fixture that creates a socket usage that has a "higher" instantiation order, such as at the module/class/session, then the higher order fixture will be resolved first, and won't be disabled during the tests. Read more in this excellent example and more about pytest fixture order here.

This behavior may change in the future, as we learn more about pytest fixture order, and what users expect to happen.

Q: Which restrictions apply when a fixture tears down?

A: The ones that were in place when that fixture was set up. A session fixture first requested by a test marked enable_socket tears down with network access, even if the last test in the session was blocked. Calls to disable_socket() or socket_allow_hosts() made inside a test don't reach the teardown of fixtures that were set up before the call. Callbacks registered with request.addfinalizer while the test runs, whether on the test's own request or from inside a fixture's factory, run after the test's restrictions are lifted.

The reverse also holds: a fixture first set up by a blocked test tears down blocked, even if a later test that uses it allows the network. If its teardown needs the network, call pytest_socket.enable_socket() at the start of the teardown code.

Contributing

Contributions are very welcome. Tests can be run with pytest, please ensure the coverage at least stays the same before you submit a pull request.

License

Distributed under the terms of the MIT license, "pytest-socket" is free and open source software

Issues

If you encounter any problems, please file an issue along with a detailed description.

References

This Pytest plugin was generated with Cookiecutter along with @hackebrot's Cookiecutter-pytest-plugin template.

This plugin came about due to the efforts by @hangtwenty solving a StackOverflow question, then converted into a pytest plugin by @miketheman.

Star History