Testing the TypeScript SDK

Overview

Relevant for Developers maintaining or extending the SDK

The TypeScript SDK isn't trusted on its own word. The Python reference SDK is verified live against a real tenant and exports conformance vectors: the exact request it sends for every op, its core decisions, and recorded traces of every helper and semantic flow. The TypeScript suites replay all of them and must match byte for byte. A live suite then checks transport, auth and TLS against the tenant.

Run the suites

Relevant for Developers before every commit

npm run check                                     # typecheck + conformance + build
ALERTOPS_DOTENV=path/to/.env npm run test:live   # live smoke and semantic blueprint

Suite	File	What it proves
Requests	test/requests.test.ts	Every op (802 public + 30 internal) sends Python's exact method, URL, query, auth header and body.
Core	test/core.test.ts	Error parsing, status → error class, retry decisions, every paginator's page sequence, envelopes and .env parsing.
Flows	test/flows.test.ts	All 247 helper traces: the same requests in the same order, then the same result or error.
Functions	test/functions.test.ts	109 pure helpers and the Python semantics they rely on (str(), json.dumps, quote, title case …).
Semantic	test/semantic.test.ts	58 planner vectors and 35 executor traces.
Drift	test/drift.test.ts	The generated code, the vendored spec and its lock hash agree, and no helper is a stub.
Live	test/live/*.live.ts	Real tenant: auth, error mapping, pagination, ingest-to-close, blueprint apply, verify and rollback.

Update after a reference change

Relevant for Developers syncing with the Python reference

In alertops-python, run python tools/export_spec.py (it re-derives sdk-spec/ from the Python SDK).
Run python tools/sync_spec.py (it copies the bundle into every language repo).
Run python tools/codegen/run.py ts (it regenerates src/generated/).
Run npm run check. A failing vector means the TS core or a helper no longer matches Python. Fix it until the suite is green.

Never edit src/generated/
Those files are produced from the spec and carry a DO NOT EDIT header with the spec hash. The drift test fails if they are edited or stale.

Live testing rules

Relevant for Anyone running the live suites

Run them only against a test tenant.
Every object is named sdktest-…, users are @example.com, and everything is deleted in reverse order, even when a step fails.
Leftovers can be listed and removed with alertops-python's python tools/sweep.py --prefix sdktest-ts.

Live coverage

Relevant for Anyone checking how much was verified against the tenant

docs/LIVE_COVERAGE.md classifies every op:

live: the TS SDK got a 2xx, from its own live tests or from the cross-language replay of every safe GET the Python suite made.
parity: Python got a 2xx live, and TS sends the identical request.
exempt: no live 2xx is possible, for a documented reason.

There must be no gaps.

Troubleshooting

Relevant for Anyone whose suite fails

drift.test.ts: vendored sdk-spec matches its lock fails

The sdk-spec/ copy was edited or has CRLF line endings. Re-run sync_spec.py. The repo pins LF in .gitattributes.

A flow vector fails with "made more requests than Python"

The TS helper calls an extra endpoint, or misses an early return. Compare it line by line with the Python flow named in the vector.

Need help?

Email support@alertops.com or contact your AlertOps representative.