Scope & Design Decisions
TL;DR
- TestSeed is deterministic CI/CD test data infrastructure, not a general data generator.
- Seed versions are immutable; same version + mode + params yields the same data.
- Business logic stays in code; TestSeed focuses on stable, structured inputs.
TestSeed is built as CI/CD test data infrastructure, not as a general-purpose data generator. It focuses on one core problem: reliable, reproducible test data for automated tests in modern systems.
What TestSeed is designed for
- API-first architectures and schema-driven services
- CI/CD pipelines and automated test suites
- Microservices and distributed systems
- Unit, integration, contract, and E2E tests
The central design principle is determinism: the same seed always produces the same data, making test results predictable, debuggable, and repeatable across environments.
What is a Seed?
A Seed is a deterministic blueprint for one service or bounded context. It defines schema, relations, and quality modes so every CI/CD run reproduces the same dataset.
{
"seedId": "orders-api",
"entities": ["customer", "order", "payment"],
"quality": "Mixed",
"version": "v3"
}- CI pipelines that need deterministic data every run
- Local dev parity with Preview and staging environments
- Contract and E2E tests that depend on stable APIs
Schema Sources
TestSeed is schema-first, but not schema-heavy. Use the source that already exists in your stack.
OpenAPI / Swagger
Use when: Your API spec is the source of truth.
Output: Full entity schema with types, formats, and constraints.
GraphQL SDL
Use when: GraphQL types define your contracts.
Output: Type-aligned entities with deterministic fields.
Entity Pool
Use when: You need fast, curated blueprints.
Output: Prebuilt entities you can extend or combine.
Custom Schema
Use when: You want full control over fields.
Output: Tailored schemas with explicit rules.
What TestSeed is intentionally not
- a full business-rule simulation engine
- a replacement for testing frameworks
- a UI demo or sample data generator
- a database seeding or migration tool
Determinism over realism
Many tools prioritize realism by introducing randomness. While useful for exploratory testing, this often causes instability in automated pipelines. TestSeed replaces randomness with deterministic variation driven by seeds and explicit rules — so failures can be reproduced exactly.
Seed A → output A (always) Seed B → output B (always) Same seed version + same mode + same params = same data
Versioning and reproducibility
Seed versions are immutable references — the same version always produces the same data given the same mode and parameters. CI failures are reproducible without managing database snapshots or dumps.
Define → Save → Generate → Reuse
Summary
TestSeed eliminates flaky tests caused by data drift, supports stateless API-driven CI/CD pipelines, and provides deterministic test data across services and environments. It deliberately avoids problems that belong to application logic or enterprise data simulation.
FAQ
- What is TestSeed?
- TestSeed is deterministic test data infrastructure for CI/CD and API-first systems. The same seed always produces the same data.
- Does TestSeed support OpenAPI and GraphQL?
- Yes. You can import OpenAPI/Swagger or GraphQL SDL and generate schema-aligned, deterministic data.
- Is TestSeed a general data generator?
- No. TestSeed focuses on reproducible, schema-driven inputs for automated tests — not UI demos or database seeding.
- How does determinism work?
- The same seed ID, version, quality mode, and parameters always produce the exact same output. This makes CI failures reproducible without database snapshots.
See it in action (30s)
Jump to the Quickstart to see the full API flow.
Introduction to TestSeed
Welcome to TestSeed — deterministic, schema-driven test data generation for modern pipelines. Stop managing brittle fixtures. One Seed typically represents the test data contract of a single service.
Quickstart: Your First Seed in 2 Minutes
TestSeed is API-first (curl-ready). SDKs and CLI wrap these same endpoints.
TESTSEED_URL="https://testseed.com"
TESTSEED_SEED_ID="your_seed_id"
TESTSEED_API_KEY="your_api_key"
curl -sS --fail-with-body "$TESTSEED_URL/api/seeds/$TESTSEED_SEED_ID/generate?count=50&mode=Valid&format=json" \
-H "x-api-key: $TESTSEED_API_KEY" | tee data.json$env:TESTSEED_URL="https://testseed.com"
$env:TESTSEED_SEED_ID="your_seed_id"
$env:TESTSEED_API_KEY="your_api_key"
curl.exe -sS --fail-with-body "$env:TESTSEED_URL/api/seeds/$env:TESTSEED_SEED_ID/generate?count=50&mode=Valid&format=json" -H "x-api-key: $env:TESTSEED_API_KEY" | Tee-Object -FilePath data.jsonDefine Your Schema
Model your entities — fields, constraints, relations. One Seed typically represents one service.
Grab Your API Key
Create an API key under Settings → API Keys and set it as a secret in your CI/CD provider.
Run Your First Seed
Call the REST endpoint to generate a deterministic dataset. Same params → same data, every run.
Core Concepts
TestSeed is built around a few simple yet powerful concepts designed for modern development workflows.
Seeds
A Seed is a reusable blueprint for generating deterministic test data for a specific service or bounded context. It defines the entities, their relationships, and generation rules.
Schema-Driven
The entire system is driven by your canonical entity schema, ensuring consistency and a single source of truth for all data shapes and constraints.
Deterministic Engine
Given the same Seed configuration (and version), the engine produces the same dataset — perfect for reproducible CI runs.
Integration Guides
Integrate TestSeed directly into your CI/CD pipelines. Each service build is tested against its own fresh, deterministic dataset.
Data Quality Modes
Every Seed is saved with a quality mode. The mode is deterministic — same Seed → same quality profile across local, preview, and CI runs.
Fully schema-compliant data for happy-path tests.
One or two fields per entity are pushed to exact min/max limits. Always valid, no markers.
One or two fields per entity use explicit markers like __invalid:format__. IDs and relations stay intact.
Valid-first. Only the first record per entity contains invalid markers (1–2 fields). All other records remain fully valid.
Secure Your API Keys
Configure these secrets in your CI/CD provider — never commit them to Git. CI providers mask secrets in logs automatically.
TESTSEED_API_KEYTESTSEED_SEED_IDTESTSEED_URLOn 429 / 503 responses, respect Retry-After to avoid hammering the API.
Platform Examples
Call the TestSeed API to generate a data file before running your tests. Each Seed can be used independently, aligned with the service you are testing.
Create the workflow file and store secrets in repository settings.
name: Integration Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm install --workspaces
- name: Generate Test Data for Authentication Service
env:
TESTSEED_URL: ${{ secrets.TESTSEED_URL }}
TESTSEED_SEED_ID: ${{ secrets.AUTH_SERVICE_SEED_ID }}
TESTSEED_API_KEY: ${{ secrets.TESTSEED_API_KEY }}
run: |
curl -sS --fail-with-body --retry 3 --retry-all-errors --retry-delay 2 --max-time 60 \
"${TESTSEED_URL}/api/seeds/${TESTSEED_SEED_ID}/generate?count=100&format=json" \
-H "x-api-key: ${TESTSEED_API_KEY}" | tee test-data.json
- name: Verify & Run Tests
run: |
test -s test-data.json
npm test -- --seedFile=test-data.jsonSDKs & CLI
The REST API is the primary interface today. SDKs and the CLI will be thin wrappers around these HTTP endpoints.
Node.js / TypeScript
import fs from "node:fs";
const baseUrl = process.env.TESTSEED_URL || "https://testseed.com";
const apiKey = process.env.TESTSEED_API_KEY;
const seedId = process.env.TESTSEED_SEED_ID || "your_seed_id";
if (!apiKey) throw new Error("Missing TESTSEED_API_KEY");
const url = new URL(`${baseUrl}/api/seeds/${seedId}/generate`);
url.searchParams.set("count", "100");
url.searchParams.set("format", "json");
const res = await fetch(url, { headers: { "x-api-key": apiKey } });
if (!res.ok) throw new Error(`Request failed: ${res.status} ${await res.text()}`);
fs.writeFileSync("data.json", await res.text(), "utf8");
console.log("Saved data.json");Python
import os, sys, requests
base_url = os.getenv("TESTSEED_URL", "https://testseed.com")
api_key = os.getenv("TESTSEED_API_KEY")
seed_id = os.getenv("TESTSEED_SEED_ID", "your_seed_id")
if not api_key:
print("Missing TESTSEED_API_KEY"); sys.exit(1)
resp = requests.get(
f"{base_url}/api/seeds/{seed_id}/generate",
params={"count": 100, "format": "json"},
headers={"x-api-key": api_key},
timeout=30,
)
if resp.status_code >= 400:
raise RuntimeError(f"Request failed: {resp.status_code} {resp.text}")
with open("data.json", "w", encoding="utf-8") as f:
f.write(resp.text)
print("Saved data.json")Error Reference
Common API errors and what they mean in CI/CD pipelines. All errors return a JSON body with an error field.
ERR_RECORD_LIMIT
400Requested batch exceeds your plan limit.
Fix: Lower count or upgrade plan limits.
ERR_CREDITS
429Monthly credits depleted for the current cycle.
Fix: Wait for reset or upgrade plan.
ERR_AUTH
401Missing or invalid API key or auth token.
Fix: Verify x-api-key or ID token.
Examples
Explore ready-to-use examples from our open-source org. Each repo demonstrates a single deterministic testing scenario.
GitHub org: TestSeedHQ
Featured repo: deterministic-data-examples
examples/react-jestDeterministic Jest tests with seeded user data.examples/e2e-playwrightReproducible E2E failure using mixed-mode data.examples/microservice-contractContract tests against a schema-defined seed.