Scope & Design Decisions

This page explains what TestSeed is designed for, which problems it intentionally focuses on, and where its scope ends. TestSeed is built as CI/CD test data infrastructure, not as a general-purpose data generator.

What TestSeed is designed for

TestSeed focuses on one core problem: reliable, reproducible test data for automated tests in modern systems. It is designed to support:

• 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. This makes 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 can reproduce 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.

What TestSeed is intentionally not

TestSeed does not try to solve every test data problem. It 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

Keeping the scope narrow allows TestSeed to remain predictable, transparent, and reliable in CI/CD environments.

Determinism over realism

Many tools prioritize realism by introducing randomness. While useful for exploratory testing, this often causes instability in automated pipelines. TestSeed prioritizes reproducibility, explicit structure, and controlled edge cases.

Randomness is replaced by deterministic variation driven by seeds and explicit rules, so failures can be reproduced exactly and debugged efficiently.

Seed A -> output A (always)
Seed B -> output B (always)
Same seed version + same mode + same params = same data

Business logic stays in code

TestSeed provides structured, consistent input data. It does not attempt to simulate complex business logic. Examples of logic intentionally out of scope:

• financial calculations where sums must exactly match
• derived values that depend on domain-specific rules
• cross-entity mathematical constraints

These rules belong in application code and should be tested explicitly. TestSeed keeps inputs stable so business logic can be validated reliably.

Schema-first, not schema-heavy

Using TestSeed does not require manually modeling complex schemas from scratch. There are multiple ways to define data structures:

• select predefined entities from the built-in entity pool
• combine and extend existing entities in a hybrid schema
• import schemas from OpenAPI, GraphQL, or Swagger specifications

In most modern systems a schema already exists. TestSeed leverages this technical truth instead of duplicating it.

Seeds as a logical source of truth

TestSeed does not rely on shared test databases. Instead, a seed acts as a logical source of truth:

• services consume data independently
• no shared state or synchronization is required
• consistency emerges from using the same seed

This enables stateless CI/CD pipelines and isolated service tests without central data stores.

Versioning and reproducibility

TestSeed does not version test data in Git. Instead, seed versions are immutable references: the same seed version always produces the same data (given the same mode and parameters), and rerunning tests reproduces the same results.

This makes CI failures reproducible without managing database snapshots or dumps.

Define -> Save -> Generate -> Reuse

Summary

TestSeed is designed to eliminate flaky tests caused by data drift, support stateless API-driven CI/CD pipelines, and provide deterministic test data across services and environments. It deliberately avoids problems that belong to application logic or enterprise data simulation.

FAQ

Introduction to TestSeed

Welcome to TestSeed, the modern solution for deterministic, schema-driven test data generation. Stop wasting time with brittle test fixtures and start creating reliable, high-quality test data that matches your schema, constraints, and business rules. In practice, one Seed typically represents the test data contract of a single service.

Quickstart: Your First Seed in 2 Minutes

Get up and running instantly. TestSeed is API-first (curl-ready). SDKs and CLI are coming soon, so the REST API is the source of truth.

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.json

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 the generation rules (e.g., data quality modes, custom patterns).

• 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

Automate your data generation by integrating TestSeed directly into your CI/CD pipelines. This ensures that each service build is tested against its own fresh, deterministic dataset.

Data quality modes

Every Seed is saved with a data quality mode. The mode is deterministic, so the same Seed always produces the same quality profile across local, preview, and CI runs.

• Valid - Fully schema-compliant data for happy-path tests.
• Boundary (Edge-valid) - One or two fields per entity are pushed to exact min/max limits (lengths or ranges), remaining fields stay normal. Always valid, no markers.
• Invalid - One or two fields per entity use explicit markers like __invalid:format__. IDs and relations stay intact.
• Mixed - Valid-first. Only the first record per entity contains the same invalid markers (1-2 fields). All other records remain fully valid.

Platform Examples

Here's how to set up TestSeed in common CI/CD environments. Call the TestSeed API to generate a data file before running your tests. Each Seed can be used independently, so align it with the service you are testing.

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 }} # Each service uses its own 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.json

SDKs & CLI (Coming Soon)

The REST API is the primary interface today. SDKs and the CLI will be thin wrappers around these HTTP endpoints.

Node.js / TypeScript (HTTP)

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 (HTTP)

import os
import sys
import 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 response cheatsheet

Common API errors and what they mean in CI/CD pipelines:

Deterministic data examples

Explore ready-to-use examples from our open-source org. Each repo demonstrates a single deterministic testing scenario and links back to TestSeed integrations.