FastMock

FastMockDecorator stores a MockData instance as an attribute on the decorated route function. FastMockMiddleware.dispatch matches the incoming request to a FastAPI APIRoute (middleware runs before Starlette’s router has resolved anything), merges MockData from four sources in precedence order, and hands the result to get_response, which looks up the declared model for whichever status code applies and generates it via polyfactory.

setup.py + requirements*.txt gave way to a hatchling pyproject.toml and uv.lock with test/lint/docs/dev dependency groups, fastmock/py.typed was added for PEP 561, and CI now runs the test matrix across Python 3.10-3.13. The OpenAPI test was rewritten to assert only the paths, status codes, and component schemas the middleware is responsible for, rather than snapshotting the entire /openapi.json body; the old version broke on any FastAPI patch release that reformatted schema output.

delay and fail_rate/fail_status_code on MockData simulate a slow or unreliable upstream without writing any extra code. get_response became async to support delay via asyncio.sleep; fail_status_code must be one of the route’s declared responses. Both fields were reachable via decorator, middleware default, and the X-FASTMOCK-* header the moment they were added to MockData, since that path is generic over whatever fields the model has.

validate_request (default True) checks a request’s path, query, header, cookie, and body parameters against the endpoint’s declared types before generating a response. It reuses FastAPI’s own request_params_to_args/request_body_to_args rather than reimplementing type coercion, but deliberately never calls solve_dependencies. A mocked route has no real implementation to protect, so running its Depends(...) just to validate a request nobody will actually serve would defeat the point.

fastmock/seeding.py derives a seed from the configured base MockData.seed, the request method, path, sorted query string, and a canonicalised body (JSON re-serialised with sorted keys, only the first 64KB hashed), then reseeds polyfactory immediately before generation with no await in between, since the seeded state is shared process-wide. Canonicalising rather than hashing raw bytes means two clients sending the same logical payload with different key ordering get the same response. seed=1 is the default, a deliberate breaking change made on the grounds that most callers want stable demos more than request-to-request variety, and variety is still one field away.

Factory selection moved out of scanning BaseFactory.__subclasses__() into an explicit, ordered DEFAULT_BASE_FACTORIES registry. A new DEFAULT_PROVIDER_MAP then teaches those factories to look at a field’s name, not just its type, via a NameAwareFactoryMixin. Deliberately absent from the default map: a bare name, too ambiguous to guess, since a product, a bank, and a person are all equally plausible, so it is left to polyfactory itself.

Schema-driven generation produces fields that are individually plausible but unrelated: an order total that doesn’t match its line_items, a shipped order with no tracking_number. Those invariants live in the caller’s domain, so fastmock doesn’t guess at them. MockData.factory accepts a caller-supplied polyfactory factory that builds the response instead, applied per element for list responses.

documentation/docs/roadmap.md states fastmock’s positioning as a realistic fake backend for QA, staging, demos, and integration tests, plus three permanent scope boundaries. examples/storefront.py and its walkthrough exercise every feature together against one realistic API: name- and type-inferred customer data, seed-stable pagination, an OrderFactory encoding the total/tracking-number invariants, a custom sku provider, and the full header-override table. tests/test_example_storefront.py asserts the exact figures the walkthrough quotes, so the documentation cannot silently drift from the library.