Surety — Contract-Driven Testing Framework for Python

Surety makes contract-based testing simple and readable.

The surety framework replaces scattered assertions with explicit schemas and contracts — Python classes that define expected data structures, generate realistic test data, and validate real responses deterministically.

A schema is a Dictionary subclass that defines the shape of data — fields, types, and constraints. A contract adds communication semantics on top of a schema — such as an API method and path, an event name, or a database table reference.

from surety import Dictionary, String, Int, Bool

class Customer(Dictionary):
    Id = Int(name='customer_id', min_val=1000, max_val=99999)
    Email = String(name='email')
    FirstName = String(name='first_name')
    Active = Bool(name='active')

customer = Customer()
print(customer.value)
# {'customer_id': 48271, 'email': 'jane.doe@example.com', 'first_name': 'Margaret', 'active': True}

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:

Schemas	surety	Define data structures and generate test data
Contracts & Execution	surety-api, surety-db, surety-ui	Bind schemas to endpoints, tables, and pages; perform interactions
Validation	surety-diff	Compare actual data against schemas

Documentation

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

Issues

Report bugs and feature requests at the issue tracker.

License

MIT License. See LICENSE for details.

Release files for surety 0.0.25

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for surety 0.0.25
File	Size	Uploaded
surety-0.0.25.tar.gz	294.3 kB	Sep 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for surety 0.0.25
File	Interpreter	ABI	Platform	Reset
surety-0.0.25-py3-none-any.whl 19.9 kB Sep 17, 2026	Python 3	none	any	Details

Total release size: 314.2 kB

Release files / surety-0.0.25.tar.gz

Download URL	surety-0.0.25.tar.gz
Size	294.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`d8172575c94f94e0bb9e819df6a167ceb1cac00ce605c90f83bfc645d64f3ac5`
BLAKE2b-256 checksum How to use checksums	`d94192281bf2a1d345c959c24305ebcc9245c9836cbbd0f0d7cdcffda0a332bc`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / surety-0.0.25-py3-none-any.whl

Download URL	surety-0.0.25-py3-none-any.whl
Size	19.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`da7c1a867b45b760f2a50954922cc028a39b16606795a3edcfb150974ca178c8`
BLAKE2b-256 checksum How to use checksums	`4f33b9081eaae43bbb4f3ba12158ecc8f58c89aab4d6475424ac85d3e3bca065`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`