{"id":1671,"library":"pytest-socket","title":"Pytest Socket","description":"pytest-socket is a pytest plugin that allows you to disable real socket connections during test runs. This helps ensure your tests are truly isolated, do not make unintended network calls, and are faster by avoiding I/O. It is currently at version 0.7.0 and has a moderate release cadence, with updates addressing compatibility and new features.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/miketheman/pytest-socket","tags":["pytest","testing","network","socket","plugin"],"install":[{"cmd":"pip install pytest-socket","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency as it's a pytest plugin.","package":"pytest","optional":false}],"imports":[],"quickstart":{"code":"import pytest\nimport socket\nimport os\n\n# By default, if pytest-socket is installed, socket calls are blocked.\n# This test will fail if run without explicitly allowing sockets.\ndef test_blocked_socket_connection():\n    with pytest.raises(socket.error): # pytest-socket raises socket.error for blocked connections\n        socket.create_connection((\"example.com\", 80), timeout=0.1)\n\n# Use the @pytest.mark.enable_socket marker to allow sockets for a specific test.\n@pytest.mark.enable_socket\ndef test_allowed_socket_with_marker():\n    try:\n        sock = socket.create_connection((\"google.com\", 80), timeout=0.1)\n        sock.close()\n        assert True\n    except Exception as e:\n        pytest.fail(f\"Socket connection failed unexpectedly: {e}\")\n\n# Use the socket_enabled fixture to allow sockets for a specific test.\ndef test_allowed_socket_with_fixture(socket_enabled):\n    try:\n        sock = socket.create_connection((\"github.com\", 80), timeout=0.1)\n        sock.close()\n        assert True\n    except Exception as e:\n        pytest.fail(f\"Socket connection failed unexpectedly: {e}\")\n\n# To run these tests and observe behavior:\n# 1. Install: pip install pytest pytest-socket\n# 2. Run normally: pytest -v your_test_file.py\n#    (test_blocked_socket_connection should fail, others should pass)\n# 3. Run with --disable-socket explicitly: pytest -v your_test_file.py --disable-socket\n#    (test_blocked_socket_connection should fail with pytest-socket's error, others should pass)\n# 4. Run with --allow-socket: pytest -v your_test_file.py --allow-socket\n#    (All tests should attempt to connect, and pass if network is available)","lang":"python","description":"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."},"warnings":[{"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'`).","message":"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).","severity":"breaking","affected_versions":"0.3.5 - 0.7.0"},{"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'`).","message":"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.","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `pytest-socket >=0.5.1` to resolve doctest compatibility issues.","message":"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`.","severity":"gotcha","affected_versions":"<0.5.1"},{"fix":"Upgrade to `pytest-socket >=0.5.0` to ensure proper compatibility with `httpx`.","message":"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`.","severity":"gotcha","affected_versions":"<0.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.7.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}