dx-test

Give it your repo. Get a test client that exercises your product like a real customer.

dx-test reads your product's codebase, deduces the user-facing flows (signup, create resource, ingest data, etc.), then generates a test client that runs those flows against your live API.

What it does

1. Analyze — Reads your routes, docs, and config. Deduces what a customer would actually do with your product.

2. Show flows — Prints the deduced test flows in the terminal before generating anything. You see what it plans to test.

3. Generate — Produces a standalone TypeScript test client that exercises those flows with realistic fake data. One script, runs with tsx.

4. Run — Executes the test client against your running product. Fixes itself if tests fail (up to 3 iterations).

Quick start

# Option A: Just point it at your product (works without config)
npx dx-test generate ./path-to-your-product

# Option B: Run init first for smarter, deterministic test clients
npx dx-test init
npx dx-test generate ./path-to-your-product

# Full loop: generate → install → run → fix → repeat
npx dx-test run ./path-to-your-product

Install

npm install -g dx-test

How it works

Init (optional, recommended)

dx-test init

Interactive wizard that asks 5 questions about your product, then generates dx-test.config.json with:

• Product features and their endpoints
• 10-15 realistic test customers with diverse plans and scenarios
• Target URL and auth config
• Optional Stripe config

The config makes re-runs deterministic and test clients smarter. Without it, dx-test still works — it just relies entirely on codebase analysis.

Generate

dx-test generate ./my-product

1. Reads your codebase (routes, README, .env.example, docs)
2. If dx-test.config.json exists, merges product info, features, and customers into the analysis
3. Calls an LLM to deduce user-facing test flows
4. Displays the flows in the terminal
5. Generates a test client that exercises them

Output in ./dx-test-app/:

• flows.json — the deduced test plan (scenarios, endpoints, expected outcomes)
• src/test-client.ts — standalone script that runs the flows
• package.json, .env.example, tsconfig.json

Supports: Express, Spring Boot, Go, Python route patterns.

Run

dx-test run ./my-product

Full loop: generate → install → run test client → if errors, send to LLM for fix → re-run. Up to 3 iterations until clean.

Walk (browser testing)

dx-test walk --url http://localhost:3000

Opens a real browser with Playwright. Hits API routes, visits UI pages, checks for console errors and broken states. Use with --demo generated apps.

Demo mode

dx-test generate ./my-product --demo

Generates a frontend demo app (Express + HTML) instead of a test client. Useful for visual testing with walk.

Options

dx-test init [options]
  -o, --output <dir>    Directory to write config to

dx-test generate <path> [options]
  -o, --output <dir>    Output directory (default: ./dx-test-app)
  -c, --config <path>   Path to dx-test.config.json
  --demo                Generate a demo frontend app instead of test client

dx-test run <path> [options]
  -o, --output <dir>    Output directory (default: ./dx-test-app)
  -m, --max-iterations  Max fix iterations (default: 3)
  -c, --config <path>   Path to dx-test.config.json

dx-test walk [options]
  -u, --url <url>       App URL (default: http://localhost:3000)
  -r, --report <dir>    Report directory (default: ./dx-test-reports)

Example output

dx-test — Generate

Product: ./observe
Mode: test client
Reading product codebase...
Context: 12k chars
Routes: 47 | Categories: analytics, billing, alerts

Analyzing product to deduce test flows...

Deduced test flows:

  [happy] ingest-events
    Send cost/usage events for multiple customers via the ingest API
    → Create 3 fake customers
    → POST events with different models and features
    → Verify events appear in GET /api/events

  [multi-step] full-customer-lifecycle
    Create customer, send events, check analytics, verify margin calculation
    → POST /api/customers/create
    → POST /api/events/ingest (5 events)
    → GET /api/analytics/overview
    → Verify cost and revenue numbers

  [error] invalid-api-key
    Attempt ingest with bad auth, expect 401
    → POST /api/events/ingest with invalid Bearer token
    → Verify 401 response

  8 flows total

Generating test client...
  wrote src/test-client.ts
  wrote src/scenarios.ts
  wrote package.json
  wrote .env.example
  wrote tsconfig.json

Generated 5 files in ./dx-test-app

Philosophy

Every testing tool checks whether code works. Nobody checks whether someone can successfully use your product. dx-test tests the experience, not just the code.

• Tests experience, not code — flows are "create a customer and ingest events" not "assert function returns true"
• Real API calls — no mocks, no stubs, hits your running product
• Deduced from your codebase — you don't write the tests, it figures them out
• Self-healing — when tests fail, it fixes the test client and re-runs

Built by

Kat Laszlo

License

MIT