> For the complete documentation index, see [llms.txt](https://kerno.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kerno.gitbook.io/docs/core-concepts/scenarios-and-baselines.md). # Scenarios and Baselines ### Scenarios Scenarios are the test cases Kerno generates for your endpoints. Each one describes what state to set up, what request to send, what response to expect, and how to verify side effects. They live under `.kerno/scenarios/endpoints/` in your repository as TypeScript files, and are meant to be committed alongside your code. {% hint style="info" %} Kerno always writes scenarios in TypeScript, whatever language your application is written in. They reach your app over HTTP, so the language of your service does not matter. {% endhint %} A scenario runs in four phases. * **Arrange.** Set up any state the test needs — seed a user, obtain a token, insert a row. * **Act.** Make the request to the endpoint under test. * **Assert.** Check the response and any observable side effects. * **Clean up.** Tear down test data and close connections. Preconditions that several scenarios share are factored out, so setting up a logged-in user is written once rather than repeated in every test. ### Baselines A baseline is the record of how your endpoint actually behaves. It is not a separate file or a separate step — it is the assert phase of the scenario itself. Each assertion carries a clue explaining what it checks. When a run does not match, every assertion still runs, so one run reports every difference with its own clue and diff rather than stopping at the first mismatch. You see the whole picture instead of the first line of it. **Expected values are derived from your code, not guessed.** Kerno traces where each field in a response comes from. A value your handler produces deterministically is pinned exactly. A value that legitimately varies between runs — a generated id, a token, a timestamp — is matched by shape instead, so it never causes false failures. **Assertions are closed.** Each artifact is checked against its full expected shape, covering every field it actually returns. This means a field that *appears* where none was expected fails the scenario even though nobody wrote an assertion for it. That is deliberate: it is how an accidentally leaked field gets caught. ### What scenarios cover Kerno generates scenarios that cover common behavioral dimensions, including:
CategoryDescription
Functional API WorkflowsCovers endpoint behaviour, multi step request sequences, coordinated service interactions, and integration patterns across services.
Contract & Schema ValidationChecks request and response structures, data types, required fields, serialization rules, and version compatibility for the API.
Error Handling & ResilienceValidates status codes, error body formats, retry behaviour, backoff procedures, timeout handling, and controlled fallback behaviour.
Authorization & AuthenticationReviews token validation, role based access rules, permission scopes, session handling, and all credential related flows.
Boundary & Edge CasesExamines payload size limits, pagination behaviour, null or empty values, malformed inputs, and constraint based validation.
Data Integrity & Persistence

Confirms data consistency, transaction behaviour, idempotent operations,

state handling, and enforcement of database rules.

The exact set varies per endpoint based on what the code requires. Security scenarios are opt-in and covered separately in [Security testing](/docs/core-concepts/security-testing.md). ### Coverage Coverage is the share of detected endpoints that have at least one scenario: ``` Coverage = tested endpoints ÷ total endpoints ``` Tested endpoints show a play icon in the Kerno panel; uncovered endpoints show a plus icon. Kerno measures endpoint-level coverage, not branch or statement coverage. The meaningful question is whether any change you make gets validated. ### Keeping scenarios in sync Kerno does not silently rewrite your tests. Changes to a scenario suite happen when you ask for them, in one of two ways. * **Update.** For an intentional change to an endpoint. Kerno reads the previous run's failures and the files your change touched, defaults every existing scenario to keep, and edits only what your change requires. It will not delete the happy path. * **Generate.** To start an endpoint's coverage over. You review a fresh plan before anything is written. In both cases Kerno shows you what it intends to do before doing it, and **nothing is written to your repository until you approve the plan**. A plan you reject or abandon leaves your existing scenarios untouched. Kerno never modifies your application code. It only touches files under `.kerno/`. ### Why you can trust the results **The agent does not grade its own homework.** Scenarios execute in Kerno's sandbox, not inside your coding agent's context, and a verdict comes from what the assertions actually did against your running application. It is not the agent's opinion of its own work. Three things back that up: * **Endpoints are found deterministically.** Kerno's engine understands each framework's routing constructs and reads routes out of a real index. It does not infer them from filenames or ask a model to guess. * **Expected values are traced to their source.** Kerno follows each response field back to the code that produces it, so a value your handler fixes is pinned and a value that legitimately varies is matched by shape. Neither is guessed from the field's name. * **Scenarios are proven, then reviewed.** At `medium` effort and above, each scenario runs twice in a row, so one that only passed because of leftover state gets caught. At the default `high` effort, a second independent reviewer inspects the finished scenario and rejects assertions that were weakened, made tautological, or had their errors swallowed to force a green run. See [Testing modes](/docs/references/testing-modes.md) for the trade-offs. ### Reading results Each scenario reports one of four verdicts. * **Passed** — the scenario ran and the endpoint behaved as expected. * **Failed** — the endpoint did something the scenario did not expect. * **Blocked** — the scenario could not run, usually because a dependency it needs is not configured. Blocked is neither a pass nor a fail; nothing was tested. * **Not implemented** — Kerno could not produce a working scenario for this case. This is reported honestly rather than counted as a pass. A passing scenario may also carry a **potential bug**, where Kerno found the endpoint doing something unexpected, confirmed it against your source, and documented the real behaviour. See [Security testing](/docs/core-concepts/security-testing.md) for how to review and dismiss these.