# Scenarios and Baselines

### Scenarios

Scenarios are the test cases Kerno generates for your endpoints. Each scenario describes what state to set up, what request to send, what response to expect, and how to verify side effects. Scenarios live under `.kerno/scenarios/` in your repository as TypeScript files.

{% hint style="info" %}
Kerno always generates scenarios in TypeScript, regardless of your application's language.
{% endhint %}

A scenario runs in four phases.

* **Arrange.** Set up any state the test needs (seed a user, sign a JWT, insert a row).
* **Act.** Make the subject HTTP call to the endpoint under test.
* **Assert.** Check the response and any observable side effects.
* **Clean up.** Tear down test data and close connections.

Each scenario also exports a `baseline` describing the expected response shape, including dynamic values (IDs, tokens, timestamps) marked with `{{dynamic}}` placeholders so they do not trigger false diffs on every run.

### Baselines

Each scenario exports a baseline: a snapshot of what your endpoint actually returned when the scenario last passed.

When capturing the baseline for the first time, Kerno runs each scenario twice. Fields that produce different values across the two runs are automatically marked with `{{dynamic}}` placeholders. Those fields are excluded from all future comparisons so IDs, tokens, and timestamps never cause false diffs.

On subsequent validation runs, Kerno compares results against the stored baseline in two passes. First, a structural check compares status codes, JSON shape, and field types. If that detects a diff, a semantic pass determines whether the change is meaningful. Accept a diff and the baseline updates. reject a diff and the baseline stays.

### What scenarios cover

Kerno generates scenarios that cover common behavioral dimensions, including:

<table><thead><tr><th width="197.994873046875">Category</th><th width="581.7186279296875">Description</th></tr></thead><tbody><tr><td><strong>Functional API Workflows</strong></td><td>Covers endpoint behaviour, multi step request sequences, coordinated service interactions, and integration patterns across services.</td></tr><tr><td><strong>Contract &#x26; Schema Validation</strong></td><td>Checks request and response structures, data types, required fields, serialization rules, and version compatibility for the API.</td></tr><tr><td><strong>Error Handling &#x26; Resilience</strong></td><td>Validates status codes, error body formats, retry behaviour, backoff procedures, timeout handling, and controlled fallback behaviour.</td></tr><tr><td><strong>Authorization &#x26; Authentication</strong></td><td>Reviews token validation, role based access rules, permission scopes, session handling, and all credential related flows.</td></tr><tr><td><strong>Boundary &#x26; Edge Cases</strong></td><td>Examines payload size limits, pagination behaviour, null or empty values, malformed inputs, and constraint based validation.</td></tr><tr><td><strong>Data Integrity &#x26; Persistence</strong></td><td><p>Confirms data consistency, transaction behaviour, idempotent operations,</p><p>state handling, and enforcement of database rules.</p></td></tr></tbody></table>

The exact set varies per endpoint based on what the code requires.

### 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.

### Self-healing

As your codebase evolves, Kerno keeps your scenarios in sync automatically. On each validation run, Kerno evaluates every scenario against the current code and assigns it one of four states:

* **Keep.** The scenario is still valid. No changes needed.
* **Check.** The endpoint contract changed. Kerno updates the scenario to match.
* **Remove.** The endpoint no longer exists. Kerno retires the scenario.
* **Add.** A new endpoint was detected. Kerno generates scenarios for it.

Kerno never modifies your application code. Self-healing only touches files under `.kerno/`. It runs automatically as part of the validation cycle. See [Change Validation](/docs/core-concepts/change-validation.md) for how approval triggers these updates.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kerno.gitbook.io/docs/core-concepts/scenarios-and-baselines.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.