Features

• Schema-first — define expected data structures as reusable Python classes, not scattered assertions

• Contracts — bind schemas to communication semantics (API endpoints, database tables, events)

• Data generation — auto-generate realistic test data using Faker with 80+ providers

• Transport-agnostic — the same schema validates API responses, database records, and UI state

• Structured diffs — precise mismatch reporting with custom comparison rules (via surety-diff)

• API testing — HTTP contracts, schema-based mocking, and request verification (via surety-api)

• UI testing — Selenium-based browser automation with page objects (via surety-ui)

• Database testing — PostgreSQL, MySQL, SQLite, and Cassandra support (via surety-db)

• Field types — Bool, Int, Float, Decimal, String, Uuid, DateTime, Enum, Array, and more

• Extensible — create custom field types, comparison rules, and execution adapters

• Python 3.7+ compatible

Install

pip install surety

Optional extensions:

pip install surety-diff      # Structured comparison engine
pip install surety-api       # HTTP API interaction and mocking
pip install surety-ui        # Browser-based UI testing with Selenium
pip install surety-db        # Database interaction layer
pip install surety-config    # YAML-based configuration

Quick Example

Define a schema, generate data, and validate:

from surety import Dictionary, String, Int, Array
from surety.diff import compare

# Define schemas
class Address(Dictionary):
    City = String(name='city')
    ZipCode = String(name='zip_code', fake_as='zipcode')

class Order(Dictionary):
    Id = Int(name='order_id')
    Status = String(name='status', default='pending')
    ShippingAddress = Address(name='shipping_address')

# Generate test data
order = Order()
print(order.value)
# {'order_id': 7312, 'status': 'pending', 'shipping_address': {'city': 'Portland', 'zip_code': '97201'}}

# Validate against actual response
compare(actual=api_response, expected=order.value)

Override specific values while keeping the rest auto-generated:

order = Order().with_values({
    Order.Id.name: 1,
    Order.ShippingAddress.name: {Address.City.name: 'Seattle'}
})

Use comparison rules for dynamic fields:

from surety.diff import compare
from surety.diff.rules import has_some_value, timestamp_equal_with_delta_3s

compare(
    actual=response,
    expected=order.value,
    rules={
        Order.Id.name: has_some_value,
        Order.CreatedAt.name: timestamp_equal_with_delta_3s
    }
)

Architecture

Surety separates three concerns:

Documentation

Full documentation: https://surety.readthedocs.io/

Issues

Report bugs and feature requests at the issue tracker.

License

MIT License. See LICENSE for details.

Copyright (c) 2026 Elena Kulgavaya.