SDKs, mock & lint
SDK contract tests
Call every operation through the generated TypeScript SDK against the mock server with the examples from your spec, and fail CI when anything breaks.
orbitdocs sdk test checks that your TypeScript SDK, your spec and its examples agree. It calls every operation through the SDK against an in-process mock server built from the spec, and fails on anything but a 2xx. Run it in CI to catch a broken SDK, a wrong example or a spec change the SDK didn't follow.
Run the tests
npx orbitdocs extract
npx orbitdocs sdk --lang typescript
npx orbitdocs sdk test› travel: 12 operations through the TypeScript SDK against the mock
✓ listBookings GET /v1/bookings → 200
✓ createABooking POST /v1/bookings → 201
✗ getABooking → 422 {"error":"Request validation failed","violations":[…]}
…
✗ travel: 11/12 SDK calls passedThe command exits with code 1 when any call fails, so CI stops.
| Flag | Default | |
|---|---|---|
--api <id> | every API in sdks.apis | Test one API. |
What it does
For each API:
- Bundles the SDK from
sdks/<api>/typescript/src/index.tswith esbuild, as it would ship. - Starts the mock server on a free port, in the same process. Your
mock.handlersandmock.validatesettings apply. - Sets placeholder credentials for each security scheme:
test-keyfor header API keys,Bearer test-tokenfor bearer, OAuth 2 and OpenID Connect, andtest:testfor Basic. The mock only checks that they are present and well formed. - Calls each operation, in spec order, with arguments built from the spec:
- path, query and header parameters that are required or have an example, using the example or a value generated from the schema;
- the request body's example, or one generated from its schema. File fields in multipart bodies get a small test file.
- Passes when the response is 2xx and the SDK returned no error.
An operation with no SDK function (for example, after a spec change without regenerating) fails with "no SDK function".
Read the failures
| Failure | Usual cause |
|---|---|
→ 422 with violations | An example in your spec doesn't match its own schema. Fix the example (@ApiProperty({ example }) or the DTO). |
→ 401 | The operation uses a security scheme the test can't fill, such as an API key in a query string or cookie. |
→ 404 | A mock handler's store.get or update found nothing. Seed the store in an earlier handler, or return a value. |
no SDK function | The SDK is older than the spec. Run orbitdocs sdk --lang typescript. |
→ 500 | A mock handler threw. The message is in the output. |
Requirements
sdks.typescriptmust be configured, and the SDK generated. Other languages aren't tested.- The spec must be extracted (
openapi/<api>.json). - Mock handlers share one store for the whole run. A
createhandler that runs before agethandler can make thegetsucceed.
In CI
Add it after generating the SDK, for example in the workflow from Regenerate in CI:
- name: SDK contract tests
working-directory: docs
run: npx orbitdocs sdk --lang typescript && npx orbitdocs sdk test