Skip to content

feat: typed reads, request log, self-tests, published contracts and hermetic CI - #13

Open
VincentJerico wants to merge 6 commits into
mainfrom
feat/framework-upgrades
Open

VincentJerico wants to merge 6 commits into
mainfrom
feat/framework-upgrades

Conversation

@VincentJerico

Copy link
Copy Markdown
Owner

What & why

Takes the framework from a solid starter to something I'd defend in a senior SDET interview: typed reads, failures that explain themselves, gates proven able to fail, hermetic CI and contract drift alerts. One commit per feature.

  1. Typed reads (src/http/readJson.ts): readJson(res, Schema) parses the body, validates it against its contract and returns a typed value, or throws a ContractError listing every broken field with the status and URL. All tests now use it instead of the untyped res.json(), so every body a test reads is also a contract check.
  2. Request log on failure (src/http/recorder.ts): the request fixture records every call (method, URL, query, status, duration, both bodies) and attaches it as api-calls.json when a test fails. Tokens and passwords are redacted; API_LOG=always attaches it to passing tests too.
  3. Offline self-tests (tests/selftest/, new selftest project): a local stub server proves the matcher, readJson, cleanup() and log redaction each fail when they should. The API suite is now the api project.
  4. Published contracts (docs/schemas/*.schema.json): the five Zod response contracts exported as JSON Schema (draft 2020-12). A self-test fails if a contract changes without its file being regenerated (npm run schemas:update), or if a file outlives its contract.
  5. CI layers:
    • the quality job now also runs the self-tests;
    • pushes and PRs run the API suite against mwinteringham/restfulbooker as a Docker service container;
    • the weekly schedule, or a manual run with live: true, tests the live API;
    • a failed weekly run opens a "Contract drift" issue, or comments on the open one.
  6. README: documents all of the above, with a real api-calls.json entry.

How it was tested

Node 22.23.4 locally:

  • npm run lint, format:check, typecheck: pass.
  • npm test: 32 passed (15 self-tests + 17 API tests against the live API).
  • npm run test:api against Restful-Booker in Docker (BASE_URL=http://localhost:3001): 17 passed.
  • Planted bugs, each caught by exactly the self-test meant for it (output in the commit messages):
    • a matcher that always passes;
    • a cleanup() that ignores leaks;
    • a recorder that leaks passwords;
    • a contract changed without regenerating its schema file;
    • a deleted schema file.

Not yet proven: the drift-issue job. It only runs when a scheduled live run fails, and testing it would open a real issue on this public repo, so I haven't triggered it. The gh commands it uses are standard (issue list / issue create / issue comment) and need only issues: write.

🤖 Generated with Claude Code

VincentJerico and others added 6 commits November 6, 2026 21:17
… typed

Tests no longer read the untyped value res.json() returns. readJson parses,
checks the contract and throws a ContractError listing every broken
field path, so every body read doubles as a contract check. The matcher
shares the same issue formatting.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The request fixture records method, URL, params, status, duration and
both bodies (token and password redacted, long bodies truncated) and
attaches them as api-calls.json on failure, or always with API_LOG=always.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n can fail

A new offline 'selftest' project runs against a local stub server, so it
needs no API. Each planted bug was checked: a matcher that always passes,
a cleanup that ignores leaks and a recorder that leaks passwords each fail
exactly one self-test. The API suite is now the 'api' project.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…emas

A self-test fails when a contract changes and its published file doesn't
(compared as parsed JSON, so formatting can't break it), or when a file
outlives its contract. npm run schemas:update regenerates them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… drift

Pushes and PRs run the API suite against mwinteringham/restfulbooker as a
service container, so results don't depend on the shared public demo.
The weekly schedule (or a manual run with live: true) tests the live API,
and a failed weekly run opens or comments on a 'Contract drift' issue.
The quality job now runs the offline self-tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…CI layers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant