Skip to content

testing.md

Latest commit

 

History

History
80 lines (59 loc) · 3.35 KB

testing.md

File metadata and controls

80 lines (59 loc) · 3.35 KB
Raw

Testing

Documentation home · Getting started · Architecture · Deployment

Testing is risk-based and organized by the boundary that can prove each behavior.

Commands

pnpm run format:check
pnpm run docs:check
pnpm run config:check
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run test:contract
pnpm run test:wire
pnpm run test:browser
pnpm run test:smoke
pnpm run build
pnpm run deploy:dry-run
pnpm run validate

pnpm test runs unit and Worker integration tests inside the Cloudflare Workers Vitest runtime. pnpm run test:wire starts local workerd and uses a low-level HTTP client to verify transmitted bytes without Fetch's automatic decoding. pnpm run test:browser starts a local Worker and runs Playwright Chromium tests. The build and dry-run scripts package the Worker locally without publishing it.

pnpm run docs:check verifies every local Markdown link in the public-facing repository documentation suite.

pnpm run config:check parses wrangler.jsonc with the installed Wrangler version and prevents deployment from dropping http.btlr.me or resetting log and trace sampling above 10%.

pnpm run test:contract starts an isolated local Worker and exercises Fetch, curl, Python Requests, and Python HTTPX. Install its pinned Python dependencies once with:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-contract.txt

pnpm run test:smoke runs nine low-load, read-only checks against an isolated local Worker. The owner may run the same safe subset against a deployed origin:

BTLR_BASE_URL=https://your-approved-host.example pnpm run test:smoke

Automated repository validation never sets a production URL or runs the owner-only form.

Install the pinned Playwright browser after a fresh dependency install:

pnpm exec playwright install chromium

CI installs the browser and its Linux system dependencies explicitly.

Dependency policy

Direct dependencies track current stable compatible releases and are locked by pnpm-lock.yaml; Python contract clients use exact direct pins. Upgrade the TypeScript and lint stack together so their declared compatibility ranges remain valid. Record point-in-time dependency audits in commits or audit artifacts rather than treating a dated package result as durable test documentation.

Evidence rules

  • Public routes receive Worker integration or contract coverage for success, malformed input, method handling, and meaningful boundaries.
  • Fixed defects receive a regression test.
  • Browser-visible behavior is asserted from the final rendered DOM using stable selectors and fixture completion markers.
  • Wire-sensitive behavior is tested at a runtime level that can prove it; response headers alone are not sufficient evidence.
  • Timing assertions use bounded tolerances and deterministic seeded behavior.
  • Snapshots are used only when they communicate a stable contract better than focused assertions.
  • Focused, skipped, placeholder, and silently disabled tests are prohibited.

Production-only verification

Local tests cannot prove custom-domain routing, WAF behavior, Cloudflare's distributed rate-limit accuracy, or edge-cache behavior. deployment.md defines a small owner-run production smoke procedure; production verification is never part of automated repository validation.