QUICKSTART GUIDE

Getting Started with VEXFOX

Learn how to install VEXFOX, record your first HTTP interaction with HTTPX, store cassettes safely, and replay them offline in automated test suites.

1. System Prerequisites

VEXFOX is built for modern Python applications and leverages typed features introduced in Python 3.11:

Python Version

>= 3.11

Standard CPython 3.11, 3.12, or 3.13.

HTTPX Client

>= 0.25.0

Deep transport integration with sync and async clients.

2. Installation

VEXFOX v0.1.0 is officially published on PyPI. Install it into your environment using pip:

Terminal

1 lines

pip install vexfox

Package index:pypi.org/project/vexfox/ ↗

If you are developing locally inside the cloned repository:

Local Development

1 lines

pip install -e .

3. Your First Recording

Wrap your HTTPX client call inside the `vexfox.use_cassette()` context manager. By default, VEXFOX operates in `RecordMode.ONCE`: if the cassette does not exist, it makes the live network call, records the response, scrubs credentials, and saves the file.

tests/test_weather.py

17 lines

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import httpx
import vexfox

# 1. On first run:
#    - Vexfox detects that 'fixtures/weather.json' does not exist.
#    - Makes the live HTTP request to the external API.
#    - Redacts any sensitive headers/tokens in-memory.
#    - Atomically writes the cassette to disk.
#
# 2. On subsequent runs:
#    - Replays the recorded response strictly offline.
#    - Zero network sockets are opened.
with vexfox.use_cassette("fixtures/weather.json"):
    response = httpx.get("https://api.example.com/v1/weather?city=SanFrancisco")
    assert response.status_code == 200
    data = response.json()
    assert "temperature" in data

4. Asynchronous Client Support

`vexfox.use_cassette` also acts as an async context manager for `httpx.AsyncClient` calls:

tests/test_async.py

15 lines

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import httpx
import vexfox
import pytest


@pytest.mark.asyncio
async def test_async_github_client():
    """Asynchronous test with httpx.AsyncClient."""
    async with vexfox.use_cassette("fixtures/github_repos.json"):
        async with httpx.AsyncClient() as client:
            response = await client.get(
                "https://api.github.com/orgs/vexfox/repos",
                headers={"Authorization": "Bearer fake_token_123"},
            )
            assert response.status_code == 200

5. Cassette Storage & Format

Cassettes are saved as standard JSON files conforming to VEXFOX Schema v1. Recommended practice is to store them in a `fixtures/` or `tests/cassettes/` directory and commit them to Git alongside your tests.

Cassette Atomic Writes

VEXFOX writes cassette data to a temporary file before atomically renaming it to the target path. Interrupted test runs will never leave corrupted, half-written fixture files on disk.

6. Pytest Integration

When installed, VEXFOX automatically registers a pytest plugin that exposes the `vexfox` fixture. Use it directly in test functions:

tests/test_pytest_fixture.py

14 lines

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import httpx


def test_payment_endpoint(vexfox):
    """
    Vexfox automatically provides a 'vexfox' fixture in pytest.
    It manages cassette context and ensures cleanup on test exit.
    """
    with vexfox("fixtures/payment_success.json"):
        response = httpx.post(
            "https://api.example.com/charges",
            json={"amount": 1000, "currency": "usd"},
        )
        assert response.status_code == 201

7. Common First-Run Considerations

Do I need to mock sockets or monkey-patch?

No. VEXFOX wraps HTTPX transport classes cleanly. It does not touch global sockets or affect other networking libraries like `urllib3` or `requests`.

What if my cassette is missing in CI?

In `RecordMode.REPLAY`, VEXFOX raises `CassetteNotFoundError` if the cassette does not exist. Ensure your cassettes are committed to version control before running CI test suites.

Documentation Overview

Configuration & Modes