Metadata-Version: 2.4
Name: nimax
Version: 1.0.0
Summary: Record and replay niquests HTTP and WebSocket interactions in pytest
Project-URL: Homepage, https://github.com/adamlogan73/nimax
Project-URL: Repository, https://github.com/adamlogan73/nimax
Project-URL: Bug Tracker, https://github.com/adamlogan73/nimax/issues
Author-email: Adam Logan <adamlogan73@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Adam Logan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cassette,http,niquests,pytest,testing,vcr,websocket
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: niquests>=3
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: niquests[ws]>=3; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=9; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: ty>=0; extra == 'dev'
Requires-Dist: websockets>=13; extra == 'dev'
Description-Content-Type: text/markdown

# nimax

[![CI](https://github.com/adamlogan73/nimax/actions/workflows/ci.yml/badge.svg)](https://github.com/adamlogan73/nimax/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/adamlogan73/nimax/graph/badge.svg)](https://codecov.io/gh/adamlogan73/nimax)
[![PyPI](https://img.shields.io/pypi/v/nimax)](https://pypi.org/project/nimax/)

Record and replay [niquests](https://github.com/jawah/niquests) HTTP and WebSocket interactions in pytest.

nimax is a VCR-style cassette library built natively for niquests — supporting lazy responses, multiplexed connections, `AsyncSession`, and WebSockets. It is to niquests what [betamax](https://github.com/betamax/betamax) is to requests.

## Installation

```bash
pip install nimax
```

## Quick start

### Automatic fixture

nimax registers a `nimax_session` pytest fixture automatically. Use it instead of `niquests.Session()` in your tests:

```python
def test_my_api(nimax_session):
    resp = nimax_session.get("https://api.example.com/users")
    assert resp.status_code == 200
```

On the first run nimax records the real HTTP response to a cassette file under `cassettes/<test_module>/<test_name>.json`. Subsequent runs replay from the cassette — no network required.

### Async sessions

```python
import pytest
import niquests

async def test_async(nimax_session):
    async with niquests.AsyncSession() as session:
        with NimaxRecorder(session).use_cassette("my_cassette.json"):
            resp = await session.get("https://api.example.com/data")
            assert resp.status_code == 200
```

### Programmatic API

```python
import niquests
from nimax import NimaxRecorder, RecordMode

def test_programmatic(tmp_path):
    session = niquests.Session()
    cassette_path = tmp_path / "my_cassette.json"
    with NimaxRecorder(session).use_cassette(cassette_path, record_mode=RecordMode.ONCE):
        resp = session.get("https://api.example.com/users")
        assert resp.status_code == 200
```

## Record modes

| Mode | Behaviour |
|---|---|
| `once` | Record on first run, replay on subsequent runs (default) |
| `none` | Never record — raise an error if no matching interaction exists |
| `new_episodes` | Replay existing interactions; record any unmatched requests |
| `all` | Always record, overwriting the cassette each run |

## Placeholders

Scrub sensitive values (tokens, API keys) from cassettes before they are written:

```python
from nimax import Placeholder

recorder = NimaxRecorder(session, placeholders=[
    Placeholder(placeholder="<AUTH_TOKEN>", replace="Bearer secret123"),
])
```

## Custom matchers and serializers

```python
from nimax import BaseMatcher, NimaxRecorder

class BodyMatcher(BaseMatcher):
    name = "body"

    def match(self, recorded: dict, live: object) -> bool:
        return recorded.get("body") == live.body  # type: ignore[union-attr]

NimaxRecorder.register_matcher(BodyMatcher)
```

YAML cassettes are supported out of the box — use a `.yaml` extension for the cassette path.

## Requirements

- Python ≥ 3.11
- niquests ≥ 3
- pytest ≥ 8
- PyYAML ≥ 6

## License

MIT
