{"id":2727,"library":"pytest-recording","title":"pytest-recording","description":"pytest-recording is a pytest plugin that integrates VCR.py to record and replay HTTP traffic during tests. It aims to make testing code that interacts with external services faster and more reliable by preventing unnecessary network requests. The library uses VCR.py's 'none' recording mode by default to avoid unintentional live network calls. The current version is 0.13.4, and it maintains an active release cadence.","status":"active","version":"0.13.4","language":"en","source_language":"en","source_url":"https://github.com/kiwicom/pytest-recording","tags":["pytest","testing","http","vcr","network","integration","mocking"],"install":[{"cmd":"pip install pytest-recording","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for recording and replaying HTTP interactions.","package":"VCR.py","optional":false},{"reason":"This is a pytest plugin and requires pytest to function.","package":"pytest","optional":false}],"imports":[{"note":"pytest-recording integrates directly with pytest markers and fixtures, rather than providing direct class imports from its own namespace.","symbol":"pytest.mark.vcr","correct":"import pytest\n# Use as decorator: @pytest.mark.vcr"},{"note":"The `vcr_config` fixture is a common way to configure VCR.py behavior globally or per scope for pytest-recording.","symbol":"vcr_config fixture","correct":"import pytest\n@pytest.fixture(scope='module')\ndef vcr_config():\n    return {'filter_headers': ['Authorization']}"}],"quickstart":{"code":"import pytest\nimport requests\nimport os\n\n# Define a vcr_config fixture in conftest.py or test file scope\n@pytest.fixture(scope=\"module\")\ndef vcr_config():\n    \"\"\"\n    Global VCR.py configuration for all tests in this module/session.\n    Filters out sensitive Authorization headers to prevent them from being written to cassettes.\n    \"\"\"\n    return {\"filter_headers\": [\"Authorization\"], \"ignore_localhost\": True}\n\n@pytest.mark.vcr\ndef test_http_get_request():\n    \"\"\"\n    Records a simple HTTP GET request to httpbin.org.\n    The cassette will be saved in a default location, e.g., cassettes/{module_name}/test_http_get_request.yaml.\n    \"\"\"\n    response = requests.get(\"http://httpbin.org/get\")\n    assert response.status_code == 200\n    assert response.json()[\"url\"] == \"http://httpbin.org/get\"\n\n@pytest.mark.vcr\ndef test_authenticated_api_call():\n    \"\"\"\n    Demonstrates recording an API call with an Authorization header.\n    The header is filtered by the vcr_config fixture defined above.\n    \"\"\"\n    # Simulate retrieving an API key from environment variables\n    api_key = os.environ.get('PYTEST_TEST_API_KEY', 'fake_api_key_123')\n    headers = {\"Authorization\": f\"Bearer {api_key}\"}\n    response = requests.get(\"http://httpbin.org/headers\", headers=headers)\n    assert response.status_code == 200\n    # Verify that the Authorization header is not in the recorded response (due to filtering)\n    assert \"Authorization\" not in response.json().get(\"headers\", {})\n    assert \"fake_api_key_123\" not in str(response.json()) # Ensure actual key content not present\n","lang":"python","description":"This quickstart demonstrates setting up `pytest-recording` to record and replay HTTP requests using the `@pytest.mark.vcr` decorator. It includes a `vcr_config` fixture, typically placed in a `conftest.py` file or at the top of a test module, to apply global VCR.py configurations like filtering sensitive headers. To run these tests and record the network interactions, use `pytest --record-mode=once your_test_file.py`. The `--record-mode=once` argument is crucial for the initial recording, as `pytest-recording` defaults to `none` mode to prevent accidental network requests. Subsequent runs without this flag will replay from the cassette."},"warnings":[{"fix":"Uninstall `pytest-vcr` using `pip uninstall pytest-vcr` before installing or using `pytest-recording`.","message":"`pytest-recording` is incompatible with `pytest-vcr`. If you have `pytest-vcr` installed, you must uninstall it before using `pytest-recording` to avoid conflicts.","severity":"breaking","affected_versions":"All versions"},{"fix":"When running tests that require recording or updating cassettes, use `pytest --record-mode=once` (or another appropriate mode like `all`) in your command line.","message":"By default, `pytest-recording` uses VCR.py's `none` recording mode, which blocks all network requests and will cause tests to fail if a cassette doesn't exist. To allow network requests for initial recording or updates, you must explicitly set a recording mode (e.g., `once`, `all`, `new_episodes`) via the `--record-mode` CLI option.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use the `vcr_config` fixture or `pytest.mark.vcr` parameters to `filter_headers` and `filter_query_parameters`. For API keys, pass them via environment variables and ensure they are filtered out of the cassette. For example:\n`@pytest.fixture(scope='module') def vcr_config(): return {'filter_headers': ['Authorization']}`","message":"Sensitive information like API keys, authorization tokens, or personally identifiable information can easily be recorded into VCR.py cassettes. This poses a security risk if cassettes are committed to version control.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of the configuration priority: `vcr_config` fixture (lowest priority) < `pytest.mark.vcr` (broad scope) < `pytest.mark.vcr` (narrow scope, highest priority). Explicitly define parameters where you need specific overrides.","message":"Configuration parameters for VCR.py can be provided via the `vcr_config` fixture (at session, package, module, or function scope) and via individual `pytest.mark.vcr` decorators. These configurations are merged, with more narrowly scoped settings (e.g., function-level mark) taking precedence over broader ones (e.g., session-level fixture).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}