FRD / Build Prompt: TypeScript Backend Conformance Kit (Reusable Contract Test Suite)

FRD / Build Prompt: TypeScript Backend Conformance Kit (Reusable Contract Test Suite)

You are an expert TypeScript test-infrastructure engineer. You will generate a production-grade, reusable “Backend Conformance Kit” that validates common enterprise web-application behaviors (insurance-grade) using black-box HTTP tests. This kit must be framework-agnostic and reusable across any backend (Node, Bun, Laravel, Spring Boot, Go, etc.) by configuration only. Do NOT use any framework-native testing utilities. Treat the target system as an external HTTP API.

0) High-level Goal

Build a TypeScript monorepo (or single package) that provides:

1. A configurable conformance test runner (Vitest-based) that hits a running API via HTTP.
2. A stable configuration contract (TypeScript config file) that adapts the same tests to new services.
3. Modular test suites for common “enterprise + insurance” backend requirements.
4. Deterministic output and CI-friendly behavior.

Primary design principle: One test kit for my whole career. New services should require minimal work: only implement endpoints + fill out a config file + optional seed hooks.

1) Non-goals / Constraints

• Do NOT rely on Postman/Newman or any GUI tool.
• Do NOT rely on framework-native test clients (no Spring MockMvc, no Laravel feature test helpers, no Supertest bound to an in-process app).
• The kit must run against a server reachable by base URL (local, docker, staging).
• Must support Node LTS as the canonical runtime. Bun may be supported as a secondary runtime, but Node LTS is the source of truth.
• Do NOT assume a specific auth provider or DB.
• Prefer stable, conservative dependencies. Avoid heavy abstractions.

2) Tech Stack Requirements

• Language: TypeScript (strict)
• Runtime: Node LTS (primary), Bun (optional compatibility)
• Package manager: pnpm
• Test runner: Vitest
• HTTP client: got + tough-cookie (cookie jar support is mandatory)
• Env loader: dotenv (via dotenv/config or explicit dotenv.config()), plus process.env access
• Schema validation: Ajv (JSON Schema)
• Optional OpenAPI validation: include as an extension point; do not block v1 on it if it becomes complex.
• Logging: minimal; test output should be clean and deterministic.

3) Deliverables (Repository Output)

Generate a repo with:

• package.json with scripts
• tsconfig.json (strict)
• vitest config
• a core “harness” library for:
  • loading config
  • building an HTTP client with cookie jar
  • reading env vars safely
  • standard assertions (status, headers, cookies, schema)
  • retries for flaky network (bounded + deterministic)
  • optional seed/reset hooks
• modular suites under src/suites/*
• example config + docs
• example CI script snippet (GitHub Actions compatible)

Provide a runnable example:

• pnpm test:conformance -- --config ./conformance.config.example.ts or similar.

4) User Experience (DX)

The kit should be used like this:

4.1 Minimal per-project work

• Copy conformance.config.example.ts to conformance.config.ts
• Set baseUrl
• Set endpoint paths + cookie names
• Provide test credentials (for a seed user), or provide a login fixture generator
• (Optional) implement seed/reset endpoints or hooks for deterministic data

4.2 Command line usage

• pnpm test runs all conformance suites
• pnpm test:auth runs only auth suite
• BASE_URL=http://localhost:3000 pnpm test

4.3 Configuration contract

Config must be strongly typed and validated at startup. Missing fields should fail fast with human-readable errors.

5) Core Concepts and Architecture

5.1 “Contract-driven suites”

Each suite:

• reads required config fields
• runs black-box HTTP assertions
• exposes clear failure messages: “expected Set-Cookie to include HttpOnly” etc.

5.2 Determinism

• No random data unless seeded and controlled.
• If random is needed, use a deterministic seed from config.
• No reliance on time of day; mock time is not possible in black-box mode, so test endpoints should accept test-mode overrides OR the suite should allow skipping time-sensitive checks.

5.3 Extensibility

Allow enabling/disabling suites and individual tests via config flags:

• features: { csrf: true, idempotency: true, audit: false, ... } Allow custom “service adapters” if an org has multiple API styles.

6) v1 Suites (Must Implement)

Implement these suites in v1:

6.1 Auth Session Suite (HTTP-only cookies)

Config fields:

• loginPath, mePath, logoutPath
• credentials (email/password)
• sessionCookieName
• cookiePolicy: sameSite (Lax/Strict/None), path, requireSecureCookie boolean
• allowedStatusCodes: login, logout, unauthorized (configurable) Assertions:

1. Login sets cookie:
   • status is allowed (default: 200 or 204)
   • response includes Set-Cookie for sessionCookieName
   • Set-Cookie includes HttpOnly
   • Set-Cookie includes SameSite as configured
   • Set-Cookie includes Path as configured
   • Secure is present when requireSecureCookie=true
2. Access with cookie:
   • after login, GET mePath returns 200
3. Access without cookie:
   • fresh client GET mePath returns unauthorized (default: 401 or 403)
4. Logout:
   • logout returns allowed (default: 200 or 204)
   • response clears cookie (Max-Age=0 and/or Expires in the past)
   • subsequent GET mePath returns unauthorized

Notes:

• Use got + tough-cookie jar so cookies persist automatically.
• Provide clear error messages showing the offending Set-Cookie header(s).

6.2 Error Envelope Suite

Purpose: enforce consistent API error shape across endpoints. Config fields:

• standardErrorShape: JSON Schema OR required keys list
• sampleErrorEndpoints: list of endpoints to intentionally trigger errors (e.g., GET /me without auth, GET non-existing resource) Assertions:
• errors have correct HTTP status
• errors match schema / contain required keys (code, message, requestId, etc.)
• no stack traces or internal details leaked (basic string checks)

6.3 Pagination Suite (generic)

Config fields:

• pagination: mode ('offset' | 'cursor')
• listEndpoint: endpoint that returns a list
• defaultLimit, maxLimit
• response selectors/adapters:
  • selectItems(json): unknown[]
  • selectNextCursor(json): string | null (cursor mode)
  • selectTotal(json): number | null (optional) Assertions:
• respects limit
• enforces maxLimit
• stable ordering requirement (repeated calls with same params yield same order when data unchanged)
• cursor mode: next cursor works and terminates

6.4 Idempotency Suite

Config fields:

• idempotency: header name (default: Idempotency-Key)
• endpoint: a POST endpoint safe to test in non-prod env
• request body fixture
• response identity selector (e.g., extract created resource ID)
• expectedStatusCodes for first and second request (configurable) Assertions:
• same key + same body does not create duplicates
• changing body with same key yields expected error semantics (configurable; often 409 or 422) Include explicit guidance that this should run only in test/staging.

6.5 Observability Suite

Config fields:

• correlationIdHeaderName (e.g., x-request-id)
• endpointsToCheck
• feature flag: echoRequestCorrelationId (optional) Assertions:
• response includes correlation id header for each checked endpoint
• if request provides correlation id and echoRequestCorrelationId=true, server echoes it

7) Harness Requirements

Implement a harness that provides:

• createClient() returns:
  • a got instance with tough-cookie jar
  • helpers: get/post/put/delete with defaults
• assertStatus(response, allowedStatuses)
• assertHeader(response, name, predicate)
• assertSetCookieHasAttributes(setCookieHeaders, cookieName, attributes[])
• assertCookieCleared(setCookieHeaders, cookieName)
• assertJsonSchema(data, schema) using Ajv
• parseJson(response) with robust JSON parsing and helpful errors
• withFreshClient() utility to test “no cookie” scenarios
• suite runner that can:
  • run all suites
  • run a subset by tag or path

Also include a small retry wrapper:

• Only for network-level transient errors (connection refused, timeouts)
• Max retries small (e.g. 3) and deterministic backoff

8) Configuration Format (TypeScript) + .env Policy (Must Implement)

8.1 Core rule

• TypeScript config defines the STANDARD (paths, cookie policy, suite flags, selectors).
• .env provides ENVIRONMENT-SPECIFIC overrides and sensitive values (base URL, credentials).

Do not let .env become “the real config.” If it changes the meaning of the standard, it belongs in TypeScript config.

8.2 Required files

• .env.example (committed): shows required env vars and safe defaults
• .env (gitignored): developer/CI-specific values
• conformance.config.example.ts (committed): uses env vars but keeps standards in code

8.3 Env variables (v1)

Support these env vars:

• BASE_URL (string) - base URL of the target API
• TEST_EMAIL (string) - seed user email
• TEST_PASSWORD (string) - seed user password
• REQUIRE_SECURE_COOKIE ("true" | "false") - whether to enforce Secure on cookies
• Optional harness vars:
  • HTTP_TIMEOUT_MS
  • HTTP_RETRY_COUNT

8.4 Precedence order

1. CLI-provided env vars (CI) override everything
2. .env values loaded by dotenv
3. TypeScript config defaults

8.5 Validation and failure behavior

• On startup, validate required env vars if the suite needs them.
• Error messages must be explicit:
  • “Missing TEST_EMAIL. Provide it via .env or environment variables.”
• Never print secrets in logs.

8.6 Implementation detail

• Use import "dotenv/config" at the entry point OR an explicit dotenv.config() in a dedicated module.
• Provide a small env.ts helper:
  • getEnvString(name, { required, defaultValue })
  • getEnvBoolean(name, { defaultValue })
  • parses safely and throws friendly errors

9) Scripts

Add scripts:

• pnpm test -> vitest run
• pnpm test:auth -> vitest run (only auth suite)
• pnpm typecheck
• pnpm lint (optional; keep minimal if too much)

10) Documentation

Write a README that explains:

• what the kit is
• how to point it at an API
• how to configure endpoints and cookie names
• how env vars work (.env.example + precedence)
• how to run suites
• how to add new suites
• cautions: idempotency suite should run only in safe environments

Include:

• conformance.config.example.ts
• .env.example

11) Output Requirements

• Generate the full repository structure with all files.
• Keep code clean, strict, and readable.
• Avoid any. Use proper types and narrowings.
• Provide meaningful error messages.
• Do not include unnecessary complexity.
• Ensure everything runs with pnpm install then pnpm test (assuming BASE_URL points to a running API).

Now generate the repo.