🔍 Pytest JsonSchema SnapShot (JSSS)

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

⭐ Star us on GitHub | 📚 Read the Docs | 🐛 Report Bug

✨ Features

• 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.

Installation

pip install pytest-jsonschema-snapshot

Usage

1. Use the schemashot fixture in your tests

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

   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

   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.

• 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!

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

# 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