Skip to content

Latest commit

 

History

History
152 lines (109 loc) · 5.9 KB

README.md

File metadata and controls

152 lines (109 loc) · 5.9 KB

🔍 Pytest JsonSchema SnapShot (JSSS)

logo.png

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

Tests Coverage Python PyPI - Package Version License BlackCode Imports: isort mypy Discord Telegram

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

✨ Features

image

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

  1. 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).

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