Metadata-Version: 2.4
Name: snaptestv2
Version: 1.0.0
Summary: Snapshot testing for Python — auto-create, diff on mismatch, pytest plugin, and CLI
Author: prabhay759
License: MIT
Project-URL: Homepage, https://github.com/prabhay759/snaptest
Project-URL: Repository, https://github.com/prabhay759/snaptest
Project-URL: Issues, https://github.com/prabhay759/snaptest/issues
Keywords: snapshot,testing,pytest,diff,regression
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Pytest
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# snaptest

> Snapshot testing for Python — automatically creates snapshots on first run, shows clear diffs on mismatch, pytest plugin included, and a CLI to manage snapshots. Zero dependencies.

[![PyPI version](https://img.shields.io/pypi/v/snaptest.svg)](https://pypi.org/project/snaptest/)
[![Python](https://img.shields.io/pypi/pyversions/snaptest.svg)](https://pypi.org/project/snaptest/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Installation

```bash
pip install snaptest
```

---

## Quick Start

```python
# pytest style
def test_api_response(snap):
    result = get_users()
    snap(result)   # creates snapshot on first run, asserts on next runs
```

```bash
# Update snapshots when output intentionally changes
pytest --snapshot-update
# or
SNAPTEST_UPDATE=1 pytest
```

---

## Usage

### pytest Fixture

```python
def test_user_list(snap):
    users = api.get_users()
    snap(users)

def test_multiple_snapshots(snap):
    snap(api.get_users(),   key="users_list")
    snap(api.get_profile(), key="user_profile")
```

### Standalone (without pytest)

```python
from snaptest import snapshot

def test_output():
    result = transform_data(raw_input)
    snapshot(result)              # auto-named from function + line number
    snapshot(result, key="data")  # named snapshot
```

### Updating Snapshots

```bash
# Via pytest flag
pytest --snapshot-update

# Via environment variable
SNAPTEST_UPDATE=1 pytest

# Programmatically
from snaptest import update_snapshot
update_snapshot(new_value, key="my_snapshot")
```

---

## Snapshot Files

Snapshots are stored as human-readable text files next to your test files:

```
tests/
├── test_api.py
├── test_transform.py
└── __snapshots__/
    ├── test_api.snap
    └── test_transform.snap
```

Commit `__snapshots__/` to version control so diffs are visible in PRs.

### Snapshot file format

```
# snaptest snapshot file
# Do not edit manually

[test_user_list_1]
{
  "id": 1,
  "name": "Alice"
}
[/test_user_list_1]
```

---

## Diff Output on Mismatch

When a snapshot doesn't match, you get a clear diff:

```
SnapshotMismatch: 'test_user_list_1'
Snapshot file: tests/__snapshots__/test_api.snap

─── Diff (- expected, + actual) ───────────────────────
--- expected (stored)
+++ actual (current)
@@ -1,5 +1,5 @@
 {
   "id": 1,
-  "name": "Alice",
+  "name": "Alice Smith",
   "active": true
 }
────────────────────────────────────────────────────────

To update: SNAPTEST_UPDATE=1 pytest
```

---

## Supported Types

| Type | How it's stored |
|---|---|
| `dict` | JSON with sorted keys |
| `list`, `tuple` | JSON array |
| `set`, `frozenset` | Sorted JSON array |
| `str`, `int`, `float`, `bool`, `None` | JSON scalar |
| `dataclass` | JSON via `dataclasses.asdict` |
| Any object with `__dict__` | JSON via `vars()` |
| Anything else | `repr()` |

---

## CLI

```bash
# List all snapshot files and keys
snaptest list

# Show a stored snapshot value
snaptest show my_snapshot_key

# Instructions to update
snaptest update

# Delete all snapshot files (with confirmation)
snaptest clean
snaptest clean --yes   # skip confirmation
```

---

## API Reference

### `snapshot(value, key=None, update=False)`

Assert value matches stored snapshot. Creates on first run.

### `update_snapshot(value, key=None)`

Force-update a snapshot.

### `snap` fixture (pytest)

```python
def test_something(snap):
    snap(value)              # auto-named
    snap(value, key="name")  # named
```

---

## Running Tests

```bash
pip install pytest
pytest tests/ -v
```

---

## License

MIT © prabhay759
