> 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/change-validation.md).

# Change Validation

When you make a code change, Kerno re-runs your existing scenarios against your running application and reports whether behaviour moved. If nothing changed, you get a clean run. If something did, Kerno shows you exactly what.

### How validation works

{% code expandable="true" %}

```mermaid
  flowchart LR
      A[Code change] --> B[Sync workspace]
      B --> C[Find impacted endpoints]
      C --> D[Run their scenarios]
      D --> E{Behaviour moved?}
      E -->|No| F[Clean run]
      E -->|Yes| G[Differences reported]
```

{% endcode %}

Because you run your own application, there is nothing for Kerno to rebuild. You restart your app with your changes, tell Kerno to sync the workspace, and validate.

### Finding what your change affected

Kerno compares your working tree against `HEAD`, including both staged and unstaged changes, and maps the touched files to the endpoints they reach.

This follows the call graph rather than stopping at the file you edited. A change to a shared helper surfaces every endpoint downstream of it, which is the case manual test selection reliably misses.

{% hint style="info" %}
This works off uncommitted changes. If everything is already committed, there is nothing in the diff, so target an endpoint or file directly instead.
{% endhint %}

### What counts as a difference

Every assertion in the scenario runs, so one validation reports **all** the differences it found, each with a clue explaining what was being checked and a diff of expected against actual. You are not left fixing one mismatch only to discover the next.

Differences in key ordering, array ordering, and numeric precision are ignored. Values that legitimately vary between runs, such as generated ids, tokens and timestamps, are matched by shape rather than pinned, so they never produce noise.

A field appearing where none was expected **does** count as a difference, even though no assertion was written for it. That is how an accidentally leaked field gets caught.

### Validation scope

Use a scope when asking Kerno which endpoints need attention:

| Scope                   | What it covers                                      |
| ----------------------- | --------------------------------------------------- |
| `changed`               | Only endpoints affected by your current changes     |
| `all`                   | Every endpoint in the app                           |
| `file:<path>`           | All endpoints in a specific file                    |
| `endpoint:METHOD /path` | A single endpoint, e.g. `endpoint:POST /api/orders` |

See [Scopes](/docs/references/scopes.md) for the full reference. Note that a validation run itself targets one endpoint at a time; the scope is how you decide which endpoints to run.

### Responding to a difference

Kerno tells you what changed. Deciding whether that change is correct is yours.

{% code expandable="true" %}

```mermaid
flowchart LR
      A[Difference found] --> B{Intentional?}
      B -->|No| C[Fix the code]
      C --> D[Validate again]
      D --> A
      B -->|Yes| E[Update the tests]
```

{% endcode %}

**It's a bug.** Your change broke something. Fix the code and validate again.

**It's intentional.** Your endpoint genuinely changed and the tests should follow. Run an update, describing what changed. Kerno keeps every scenario that still applies and edits only what your change requires.

There is no blanket approve step that rewrites your baseline wholesale. Bringing tests along is an explicit action with a described reason, so the change is reviewable in your pull request like any other.

### Automating the check

Kerno can write the list of impacted endpoints to `.kerno/CHANGES_DETECTED.md` and install a git hook to keep it current, so your coding agent knows what to validate without being asked.