🔍 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 genson library).
• Format detection: Automatic detection and validation of string formats (email, UUID, date, date-time, URI, IPv4).
• 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.

🚀 Quick Start

Installation

pip install pytest-jsonschema-snapshot

Usage

1. Use the schemashot fixture in your tests

from you_lib import API
from typed_schema_shot 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.

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

   pytest

👀 Key Capabilities

• Union Types: support multiple possible types for fields

• Optional Fields: automatic detection of required and optional fields

• 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

🤝 Contributing

We welcome contributions!

Quick Contribution Setup

# 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

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ for developers working with evolving JSON schemas