VenomQA - State-Based API Testing Framework
Description: Find bugs that traditional API testing misses. VenomQA explores all paths through your application using state graph traversal.

v0.2.0 Now with circuit breakers & rate limiting

# Find bugs that
traditional testing misses

VenomQA models your API as a state graph and automatically explores all possible paths. Catch consistency bugs, race conditions, and edge cases before your users do.

Star on GitHub Read the Docs
$ `pip install venomqa && venomqa demo`

### Watch VenomQA explore your API

## State Graph Traversal in Action

#### Empty Cart

Initial state ✓
add_item()

#### Has Items

1+ products ✓
checkout()

#### Paid

Order complete ✓
0
Paths Explored
0
States Visited
0
Invariants Checked
The Problem

## Traditional API testing has blind spots

Endpoint tests pass individually but break in production. Sound familiar?

Traditional Testing

### Tests endpoints in isolation

- Each test starts from unknown state
- Misses bugs from state combinations
- Flaky tests from test interdependence
- Manual setup for every scenario
- Can't test "what if" paths

VenomQA

### Tests your entire application

- Checkpoints save exact database state
- Explores ALL state transitions
- Branch from checkpoints - no flakiness
- Invariants catch consistency bugs
- Auto-discovers edge cases

How It Works

## Three steps to comprehensive testing

Model your app as states and actions. VenomQA does the rest.

1

### Define Your States

Model your application as a graph of states and transitions.

Python

    from venomqa import StateGraph, Client

    graph = StateGraph("shopping_cart")

    # Define application states
    graph.add_node("empty", initial=True)
    graph.add_node("has_items")
    graph.add_node("checked_out")

2

### Add Transitions & Invariants

Define how users move between states and rules that must always hold.

Python

    # Define state transitions
    graph.add_edge("empty", "has_items", action=add_to_cart)
    graph.add_edge("has_items", "empty", action=clear_cart)
    graph.add_edge("has_items", "checked_out", action=checkout)

    # Invariants are checked after EVERY action
    graph.add_invariant(
        "cart_total_matches",
        check=lambda client, db, ctx:
            api_total(client) == db_total(db),
        description="Cart total must match database"
    )

3

### Explore All Paths Automatically

VenomQA traverses every reachable path and reports any issues.

Python

    client = Client(base_url="http://localhost:8000")

    # Explore ALL paths through your state graph
    result = graph.explore(client, max_depth=10)

    print(result.summary())
    # Paths explored: 24
    # States visited: 5
    # Invariant checks: 120
    # Violations: 0
    # ✓ ALL PATHS PASSED

Features

## Everything you need for API testing

Built for real-world applications with enterprise-grade features.

🔀

### State Graph Testing

Model your app as nodes and edges. VenomQA explores all reachable paths and finds bugs humans miss.

✅

### Invariant Checking

Define rules that must always hold. Checked after every action to catch consistency bugs early.

💾

### Database Checkpoints

Save and restore database state. Test multiple paths from the same starting point without flakiness.

🛡️

### Circuit Breakers

Built-in resilience with circuit breakers, retry with backoff, and rate limiting protection.

📊

### Rich Reporting

HTML, JSON, JUnit XML reports. Slack and Discord notifications for CI/CD pipelines.

🔌

### Ports & Adapters

Swap backends (Postgres, MySQL, Redis) without changing tests. Mock external services easily.

## Ready to find bugs others miss?

Start exploring your API in under 5 minutes.

View on GitHub Get Started Free