Test Data Workbench

Point it at a database. Get realistic, relationally intact test data back.

Test Data Workbench reflects an unknown schema, classifies what each table represents, and emits working Python generators for it: dependency-ordered, referentially consistent, and readable. The output is not a black box; it is plain generator code you can read, edit, and commit.

Note

This documentation covers installation and usage, the design principles behind the system, the technology stack it is built on, and the reasoning that shaped its architecture. It describes the system as it actually behaves. Where a capability is deliberately out of scope, the docs say so.

What it is

Most test-data tools ask you to describe your data first: write a config, a schema definition, a set of rules. Test Data Workbench inverts that. It reads the schema you already have, infers what each table and column means, and writes the generators for you. When it guesses wrong, you correct one line of ordinary Python rather than wrestle a configuration language.

Three ideas define it, covered in Design Principles:

• Generated code is the product. The tool emits generator source, not rows behind an API. You can diff it, extend it, and check it into your repo.

• Degrade, never fail. Every generation path has a four-level fallback ladder. An unrecognized table gets a plainer generator, not a stack trace.

• Determinism on demand. A seed makes any run reproducible byte for byte, so CI fixtures stay stable across machines.

Quickstart

pipx install test-data-workbench

# Zero-setup: build a small SQLite shop database and run the full flow
tdw demo --seed 42

# Or against your own database
tdw analyze "sqlite:///shop.db"
tdw deploy  "sqlite:///shop.db" --output ./generated --seed 42

Contents

Getting Started

• Installation
  • Requirements
  • Install
  • Optional extras
  • Verify
• Quickstart
  • The zero-setup path
  • Against your own database
  • Generate the generators
  • Run a generated generator
  • Next steps

Concepts

• Design Principles
  • Generated code is the product
  • Degrade, never fail
  • Determinism on demand
  • What these principles rule out
• Architecture
  • The pipeline
  • Stages
  • Interfaces
  • Package layout
• Schema Adaptation
  • Reflection first
  • Entity classification
  • Relationship and rule detection
  • Known fidelity gaps
• The Fallback Ladder
  • The four levels
  • Why a ladder and not a switch
  • Failure isolation
  • The observability lesson
• Privacy and Data Access
  • What the analyzer reads
  • Metadata-only mode
  • PII flagging
  • What this is not

Foundations

• Test Data Principles
  • Referential integrity is the hard part
  • Dependency ordering needs cycle handling
  • Determinism is a feature, not a default
  • Uniqueness under generation
  • Realism versus simplicity
  • Partial and present beats perfect and absent
• Lineage and Evolution
  • Three generations
  • The reversal
  • What was gained and what it cost
  • Where the earlier work still lives

Technology Stack

• Technology Stack
  • Python
  • SQLAlchemy
  • Faker
  • Jinja2
  • Pydantic
  • FastAPI
  • Rich
  • A note on what is not here

Reference

• CLI Reference
  • tdw analyze
  • tdw deploy
  • tdw demo
  • tdw validate
  • tdw team
  • tdw --version
• API Reference
  • Core data models
  • Schema analyzer
  • Generator factory
  • Constraint check
  • Defensive generator manager
• Testing and Quality
  • Scope
  • Execution-level testing of generated code
  • Regressions are encoded, not just fixed
  • Determinism as a tested property
  • Running the suite

About the documentation

• How these docs are built

Project information

Version:

1.0.0

License:

Apache-2.0

Repository:

https://github.com/VolanticSystems/test-data-workbench