Metadata-Version: 2.4
Name: pytest-jsonschema-snapshot
Version: 0.2.9
Summary: Pytest plugin for automatic JSON Schema generation and validation from examples
Project-URL: Homepage, https://miskler.github.io/pytest-jsonschema-snapshot/basic/quick_start.html
Project-URL: Repository, https://github.com/Miskler/pytest-jsonschema-snapshot
Project-URL: Documentation, https://miskler.github.io/pytest-jsonschema-snapshot/basic/quick_start.html
Project-URL: Issues, https://github.com/Miskler/pytest-jsonschema-snapshot/issues
Author: Miskler
License: MIT
License-File: LICENSE
Keywords: genschema,json,pytest,rich,schema,validation
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: genschema>=0.2.0
Requires-Dist: jsonschema
Requires-Dist: jsonschema-diff
Requires-Dist: pathvalidate
Requires-Dist: pytest
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: docutils; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: furo; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-xdist; extra == 'dev'
Requires-Dist: sphinx; extra == 'dev'
Requires-Dist: sphinx-autoapi; extra == 'dev'
Requires-Dist: types-docutils; extra == 'dev'
Requires-Dist: types-jsonschema; extra == 'dev'
Description-Content-Type: text/markdown


<div align="center">

# 🔍 Pytest JsonSchema SnapShot (JSSS)

<img src="https://raw.githubusercontent.com/Miskler/pytest-jsonschema-snapshot/refs/heads/main/assets/logo.png" width="70%" alt="logo.png" />

***Plugin for pytest that automatically / manually generates JSON Schemas tests with validates data.***

[![Tests](https://miskler.github.io/pytest-jsonschema-snapshot/tests-badge.svg)](https://miskler.github.io/pytest-jsonschema-snapshot/tests/tests-report.html)
[![Coverage](https://miskler.github.io/pytest-jsonschema-snapshot/coverage.svg)](https://miskler.github.io/pytest-jsonschema-snapshot/coverage/)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
[![PyPI - Package Version](https://img.shields.io/pypi/v/pytest-jsonschema-snapshot?color=blue)](https://pypi.org/project/pytest-jsonschema-snapshot/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![BlackCode](https://img.shields.io/badge/code%20style-black-black)](https://github.com/psf/black)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
[![mypy](https://img.shields.io/badge/type--checked-mypy-blue?logo=python)](https://mypy.readthedocs.io/en/stable/index.html)
[![Discord](https://img.shields.io/discord/792572437292253224?label=Discord&labelColor=%232c2f33&color=%237289da)](https://discord.gg/UnJnGHNbBp)
[![Telegram](https://img.shields.io/badge/Telegram-24A1DE)](https://t.me/miskler_dev)


**[⭐ Star us on GitHub](https://github.com/Miskler/pytest-jsonschema-snapshot)** | **[📚 Read the Docs](https://miskler.github.io/pytest-jsonschema-snapshot/basic/quick_start.html)** | **[🐛 Report Bug](https://github.com/Miskler/pytest-jsonschema-snapshot/issues)**

## ✨ Features

</div>

![image](https://github.com/user-attachments/assets/2faa2548-5af2-4dc9-8d8d-b32db1d87be8)

* Automatic JSON Schema generation from data examples (using the `genschema` library).
* **Format detection**: Automatic detection and validation of string formats (email, UUID, date, date-time, URI, IPv4).
* **Enum inference**: Short low-cardinality string fields are narrowed to `enum` automatically.
* **Schema post-processing**: Repeated structures are extracted into `$defs`/`$ref` to keep generated schemas smaller and easier to review.
* Schema storage and management.
* Validation of data against saved schemas.
* Schema update via `--schema-update` (create new schemas, remove unused ones, update existing).
* Support for both `async` and synchronous functions.
* Support for `Union` types and optional fields.
* Built-in diff comparison of changes via [jsonschema-diff](https://github.com/Miskler/jsonschema-diff).

<div align="center">

## 🚀 Quick Start

</div>

### Installation

```bash
pip install pytest-jsonschema-snapshot
```

### Usage

1. Use the `schemashot` fixture in your tests
  ```python
  import pytest

  from you_lib import API
  from pytest_jsonschema_snapshot import SchemaShot

  @pytest.mark.asyncio
  async def test_something(schemashot: SchemaShot):
      data = await API.get_data()
      # There are data - need to validate through the schema
      schemashot.assert_json_match(
          data, # data for validation / convert to schema
          "test_name"       # name of the schema
      )

      schema = await API.get_schema()
      # There is a schema (data is optional) - validate by what is
      schemashot.assert_schema_match(
          schema,
          (API.get_schema, "test_name", 1), # == `API.get_schema.test_name.1` filename
          data=data # data for validation (optional)
      )
  ```

2. On first run, generate schemas with the `--schema-update` or `--schema-reset` (what is the difference? see the documentation) flag
   ```bash
   pytest --schema-update --save-original
   ```

   **--save-original**: save the original data on which the validation was performed. Saving occurs when `--schema-update` or `--schema-reset`, if you run the schema update without this attribute, the old original data will be deleted without saving new ones.
   **--jsss-ci-cd**: CI mode is intended for automatic PR generation; it saves updates (like `--schema-update`) to `__snapshots__/ci.cd/` (`--save-original` is compatible).

3. On subsequent runs, tests will validate data against saved schemas
   ```bash
   pytest
   ```

Generated schemas are refined by `genschema` before they are written:
format detection, enum inference for short low-cardinality strings, and post-processing that extracts repeated fragments into `$defs`/`$ref`.

<div align="center">

## 👀 Key Capabilities

</div>

* **Union Types**: support multiple possible types for fields
* **Optional Fields**: automatic detection of required and optional fields
* **Enum Narrowing**: generated schemas can automatically emit `enum` for short string fields with a small set of observed values
* **Reference Extraction**: repeated object/array shapes can be factored into `$defs` and reused via `$ref`
* **Format Detection**: automatic detection of string formats including:

  | Format | Example | JSON Schema |
  | --- | --- | --- |
  | Email | `user@example.com` | `{"format": "email"}` |
  | UUID | `550e8400-e29b-41d4-a716-446655440000` | `{"format": "uuid"}` |
  | Date | `2023-01-15` | `{"format": "date"}` |
  | Date-Time | `2023-01-01T12:00:00Z` | `{"format": "date-time"}` |
  | URI | `https://example.com` | `{"format": "uri"}` |
  | IPv4 | `192.168.1.1` | `{"format": "ipv4"}` |
* **Cleanup**: automatic removal of unused schemas when running in update mode
* **Schema Summary**: colored terminal output showing created, updated, deleted and unused schemas

## Advanced Usage? Check the [docs](https://miskler.github.io/pytest-jsonschema-snapshot/basic/quick_start.html#then-you-need-to-configure-the-library)!

### Best Practices

1. **Commit schemas to version control**: Schemas should be part of your repository
2. **Review schema changes**: When schemas change, review the diffs carefully without `--schema-update` resets.
3. **Clean up regularly**: Use `--schema-update` periodically to remove unused schemas
4. **Descriptive names**: Use clear, descriptive names for your schemas


<div align="center">

## 🤝 Contributing

### ***We welcome contributions!***

### Quick Contribution Setup

</div>

```bash
# Fork the repo, then:
git clone https://github.com/Miskler/pytest-jsonschema-snapshot.git
cd jsonschema-diff
# Install
make reinstall
# Ensure everything works
make test
make lint
make type-check
# After code editing
make format
```

<div align="center">

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

*Made with ❤️ for developers working with evolving JSON schemas*

</div>
