Pytest Socket

Warnings

• breaking Python 3.5 support was dropped in version 0.3.5. Subsequent versions gradually increased the minimum Python requirement. As of version 0.7.0, `pytest-socket` requires Python >=3.8 and <4.0. Users on older Python versions will need to upgrade Python or pin `pytest-socket` to an earlier compatible version (e.g., `~=0.3.5` for Python 3.5, or `<0.6.0` for Python 3.6/3.7).
  Fix: Upgrade Python to >=3.8 or pin `pytest-socket` to a compatible version for your Python environment (e.g., `pip install 'pytest-socket<0.6.0'`).
• breaking Version 0.6.0 updated its dependency to `pytest v7`. Projects using older versions of `pytest` (e.g., `pytest <7`) should pin `pytest-socket` to `<0.6.0` to avoid conflicts.
  Fix: Ensure your `pytest` version is 7.0.0 or newer, or pin `pytest-socket` to a version compatible with your `pytest` installation (e.g., `pip install 'pytest-socket<0.6.0'`).
• gotcha By default, if `pytest-socket` is installed, it will disable all socket connections for tests unless explicitly re-enabled. This can cause tests to fail unexpectedly if they rely on network access and are not marked appropriately. Always remember its default blocking behavior.
  Fix: Use `--allow-socket`, `--allow-hosts=host1,host2`, `pytest.mark.enable_socket`, or the `socket_enabled` fixture to explicitly permit network activity for specific tests or the entire test suite.
• gotcha Version 0.5.1 fixed an issue where `pytest-socket` could cause `IndexError` or similar issues when running doctests. If you are using doctests and encountering such errors, ensure you are on `pytest-socket >=0.5.1`.
  Fix: Upgrade to `pytest-socket >=0.5.1` to resolve doctest compatibility issues.
• gotcha Version 0.5.0 fixed an issue where `pytest-socket` could raise an `IndexError` when used in conjunction with the `httpx` library. Users experiencing this specific interaction should upgrade to `pytest-socket >=0.5.0`.
  Fix: Upgrade to `pytest-socket >=0.5.0` to ensure proper compatibility with `httpx`.
• gotcha As of version 0.7.0, a new `--force-enable-socket` CLI flag was introduced. This flag *overrides* any explicit disabling via `pytest.mark.disable_socket` or `socket-disable` CLI options, ensuring sockets are enabled even if otherwise restricted. Use with caution as it bypasses specific test protections.
  Fix: Be aware that `--force-enable-socket` takes precedence. If you intend to rigorously test network blocking, avoid using this flag or understand its implications.

Install

• pip install pytest-socket Install latest version

Quickstart

This quickstart demonstrates the default behavior of `pytest-socket` blocking network connections and how to selectively re-enable them using `pytest.mark.enable_socket` or the `socket_enabled` fixture. It also shows how CLI flags like `--disable-socket` and `--allow-socket` influence test execution.

import pytest
import socket
import os

# By default, if pytest-socket is installed, socket calls are blocked.
# This test will fail if run without explicitly allowing sockets.
def test_blocked_socket_connection():
    with pytest.raises(socket.error): # pytest-socket raises socket.error for blocked connections
        socket.create_connection(("example.com", 80), timeout=0.1)

# Use the @pytest.mark.enable_socket marker to allow sockets for a specific test.
@pytest.mark.enable_socket
def test_allowed_socket_with_marker():
    try:
        sock = socket.create_connection(("google.com", 80), timeout=0.1)
        sock.close()
        assert True
    except Exception as e:
        pytest.fail(f"Socket connection failed unexpectedly: {e}")

# Use the socket_enabled fixture to allow sockets for a specific test.
def test_allowed_socket_with_fixture(socket_enabled):
    try:
        sock = socket.create_connection(("github.com", 80), timeout=0.1)
        sock.close()
        assert True
    except Exception as e:
        pytest.fail(f"Socket connection failed unexpectedly: {e}")

# To run these tests and observe behavior:
# 1. Install: pip install pytest pytest-socket
# 2. Run normally: pytest -v your_test_file.py
#    (test_blocked_socket_connection should fail, others should pass)
# 3. Run with --disable-socket explicitly: pytest -v your_test_file.py --disable-socket
#    (test_blocked_socket_connection should fail with pytest-socket's error, others should pass)
# 4. Run with --allow-socket: pytest -v your_test_file.py --allow-socket
#    (All tests should attempt to connect, and pass if network is available)