> ## Documentation Index
> Fetch the complete documentation index at: https://help.stralos.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing strategy

> Verification expectations for Stralos changes

Testing should match the risk and ownership of the change.

## Expected checks

* Unit tests for isolated calculations and helpers.
* API integration tests for route/database behaviour.
* Backend contract tests for endpoints that have backend callers — pins request validation and response shape without a database.
* Type checks for package contracts.
* Lint checks for code quality.
* Browser smoke tests for user-facing flows.
* Pipeline tests for document processing state and idempotency.

## Backend contract tests

`stralos-api-estimate` uses a dedicated contract test suite (`pnpm test:contract`) to pin the request and response shapes for endpoints consumed by other backend services. CI runs these under the step named **Backend API contracts (receiving requests and responses)**.

Each contract test file uses the `*.backendContract.unit.test.ts` suffix and is tagged `[backend-contract]`. Tests register production route handlers and execute real validation, error mapping, and JSON serialisation. Only the persistence boundary is simulated; responses are not prebuilt fixtures. This means a handler refactor that breaks a caller's expected field names or status codes fails the suite without any integration database.

Add a contract test whenever an endpoint gains a backend caller. Include: valid requests, required and optional parameters, wrong types and out-of-range bounds, status codes, non-empty response data, null and omitted fields, and error responses. Keep expected fields explicit — do not derive them from the serialiser under test.

Each repository that has a contract suite documents its covered contracts, coverage limits, and cross-repository links in `BACKEND_CONTRACTS.md` at its root. Repositories that also send requests to peer services document their outgoing contracts in `SENDING_CONTRACTS.md`. Contract IDs (e.g. `BC-03`) are shared between the sending and receiving repositories to make both sides discoverable.

`stralos-api-global` has both files: `BACKEND_CONTRACTS.md` for the endpoints it receives from backend callers (BC-03 from `stralos-api-assistant`, BC-05 and BC-09 from `stralos-api-rates` and `stralos-api-estimate`, BC-11 from `stralos-api-scheduler`, BC-12 from `stralos-api-documents`, and BC-14 from `stralos-api-estimate`), and `SENDING_CONTRACTS.md` for the requests it sends to `stralos-api-rates` (BC-10) and `stralos-api-estimate` (BC-13).

`stralos-api-estimate` has a `BACKEND_CONTRACTS.md` documenting its own receiving side. Run its contract suite with `pnpm test:contract`.

## Current reality

Coverage is uneven. `stralos-api-documents` has a Vitest suite covering file rules and pipeline behaviour; `stralos-api-estimate` and `stralos-api-global` have integration tests and backend contract suites (`pnpm test:contract`); several other API repos currently expose build/lint but not a `test` script. Frontend packages expose type-check, lint, test, and build scripts.

## When to broaden verification

Broaden verification when a change touches:

* Shared UI or domain contracts.
* Auth/session behaviour.
* API list envelopes or validation shape.
* Estimate pricing calculations.
* Document pipeline state transitions.
* Terraform or deployment configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.