| Test a User Flow | Learn how to test a key journey through your app end to end | How to Test a User Flow |
| Configure the Kerno Test Environment | Learn how to connect Kerno to your running application | How to Configure the Kerno Test Environment |
| Create Baseline Tests for your Entry Points | Learn how to generate baseline tests for an entry point | How to Create Baseline Tests for your Entry Points |
| :comment-question: Support | Get help from the Kerno team. | https://join.slack.com/t/kerno-community/shared_invite/zt-3fzrjxgog-voatSyyKY78uDj6QaNW4OQ |
| :lightbulb: FAQs | Get answers to common questions. | FAQs |
| :shield-check: Security | Learn how Kerno handles your code and data. | Security & Privacy |
What is Kerno?
Kerno learns how your product works, maps the user flows through your app, and records how they behave in tests that run against your real stack. Every time your code changes, Kerno validates the change inside your coding agent's loop and shows what behavior moved. Kerno runs every change against your real stack and validates it across functional behavior, error handling, edge cases, security, auth, and response content.What makes Kerno different from other tools
Most code tools either statically analyze your code or run unit tests in isolation against mocks. Kerno does neither. **It knows the exact blast radius of every change.** Kerno indexes your code deterministically, so it can tell you precisely which entry points a change affects, following the call graph rather than returning approximate matches from vector embeddings. **It tests against your real stack.** Scenarios run against your actual running application and its real databases and queues, not mocks. **You don't write or maintain the tests.** Kerno generates them, and updates them when your entry points change on purpose. When it writes new tests for an entry point, it shows you the plan and waits for your approval first. Updates and batch runs go ahead unless you ask to review the plan.Does Kerno support my backend stack?
Most likely, yes. Kerno detects routes in TypeScript, JavaScript, Python, Java, Kotlin, Scala, Go, Ruby, PHP, C#, Rust, and Swift, across the common web framework for each. Your scenarios are always written in TypeScript and reach your application over HTTP, MCP, or the queue a background consumer reads, so the language your service is written in doesn't change how tests run. Kerno can also connect directly to PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Kafka, RabbitMQ, Amazon SQS, Azure Service Bus, DynamoDB, ClickHouse, Azure Storage and S3-compatible object storage, for setting up and verifying state your API can't express. It also reads Zitadel and Amazon Cognito to obtain test credentials. The full matrix lives in [Supported technologies](/docs/references/supported-technologies).Does Kerno store my code
No. Kerno never stores your source code on its servers. Relevant excerpts pass through Kerno's proxy to LLM providers (Anthropic and OpenAI) configured with zero-data-retention tiers, so nothing is persisted on the provider side either. Note that the report of every test run your agent starts is uploaded as the run progresses, so your team can view it in the portal. That report includes the request and response payloads your application produced during the run. See [Security & Privacy](/docs/references/security-and-privacy).Does Kerno use my code for training or fine tuning LLMs?
No. Kerno doesn't train models. The LLM providers Kerno uses run on zero-data-retention tiers, so your code isn't stored, logged, or used for training on their side.Are there discounts available for startups?
Kerno offers free usage for qualified Open Source Projects and a significant discounts for pre-Series A startups. [Drop us a note](https://www.kerno.io/contact) to check your availability.Can Kerno test an app that spans several repositories?
Kerno works within one repository at a time. That repository can hold several apps, such as the services of a monorepo, and Kerno tests each of them.Does Kerno work with my coding agent?
Yes, if your agent supports MCP. Kerno exposes a set of MCP tools your agent calls to connect to your running app, generate tests, and validate changes. Claude Code, Cursor, Windsurf, and Codex are the verified setups. See the [Quickstart](/docs/getting-started/quickstart) to install the CLI and register the MCP server with your agent.What if I'm not using a coding agent?
Kerno runs through a coding agent that supports MCP, such as Claude Code, Cursor or Codex. The agent connects Kerno to your running app, generates tests for an entry point, and validates your changes. See the [Quickstart](/docs/getting-started/quickstart) to set one up. Once your tests are committed, the [CI action](/docs/guides/run-tests-in-ci) re-runs them on your pull requests without an agent.
.png?alt=media&token=89e27ff3-d4dc-4305-aee0-d35c364f252d)
queues, auth)] APP --> DEPS end SANDBOX[Kerno sandbox
runs the tests] SANDBOX -->|HTTP| APP SANDBOX -.->|optional read/write access| DEPS ``` ### How Kerno connects to your application Kerno connects to your running application, and optionally to the services it depends on. Where your application runs takes one of two shapes. * **`local`.** The application runs on your machine, reached at the URL it listens on, such as `http://localhost:3000`. * **`remote`.** The application runs somewhere else you can reach, such as a shared dev environment. Before relying on that address, Kerno probes it from inside its own sandbox, so an unreachable application is caught immediately rather than surfacing later as a confusing test failure. Kerno treats the environment as ready only once that check passes, and runs entry point tests only against a ready environment. Kerno can run tests in two modes, black box and white box. White box is the default, and it is what a run uses once you have given Kerno access to your dependencies. #### Black box testing In black box mode, Kerno tests your application entirely from the outside, like any external client. It talks to your application only over HTTP, and sets up and verifies everything through your own entry points, with no direct access to your dependencies. This sets two limits. Kerno will not generate tests that rely on direct database access, and it cannot validate side effects that are not visible through your API, such as confirming what your entry point wrote to the database. ```mermaid flowchart LR S[Kerno sandbox] -->|HTTP| A[Your application] A --> D[(Dependencies)] ``` #### White box testing Kerno may additionally reach those dependencies directly, for the cases your API cannot express. Two common examples are seeding a record your API has no way to create, and confirming that a stored password is not the plaintext that was submitted. ```mermaid flowchart LR S[Kerno sandbox] -->|HTTP| A[Your application] A --> D[(Dependencies)] S -->|read/write| D linkStyle 2 stroke:#f59e0b,stroke-width:2px ``` With that access, Kerno handles the data layer for you, reading and writing your dependencies to establish the state a test needs and to verify what your entry point actually persisted. That is the work you would otherwise write fixtures and teardown code for. To enable it, provide connection details for the services your application depends on: its database, but also a cache like Redis, a queue like Kafka or RabbitMQ, object storage, or an auth provider like Zitadel. See [Supported Technologies](/docs/references/supported-technologies) for the full list. Any individual run can opt out and go black box. See [Testing modes](/docs/references/testing-modes) for the dial that does it. #### Services your app calls over HTTP If your app calls other HTTP services, tell Kerno about them: ``` My app calls a billing service at http://localhost:4000, with its OpenAPI spec in docs/billing.yaml. Add it to Kerno's config. ``` For each service you can give its address, so tests can reach it, and its OpenAPI spec, as a URL or a path in your repository, so tests check the real request and response shapes. Kerno uses this only when it writes tests, and your app's configuration stays as it is. ### Calibration Once your application is connected and ready, your agent calibrates Kerno to your repository. Calibration runs once per repository and records the facts every test relies on, so each test starts from them. It works in three passes. Your agent first reads a handful of files, such as your agent instructions, README, scripts and env files. It then checks what it found against your running application with a few live requests. Finally, it walks you through each item, one at a time, and asks you to confirm or correct it. The cost stays the same however many entry points your application has. | Item | What calibration records | | -------------- | ----------------------------------------------------------------------------------------------------------- | | Sign-in | How to sign in as a real user, with working test credentials | | API token | A ready API token and its scope, or how to create one | | Seeding | How to create test data the way your application does, such as a seed or factory command | | Write blockers | What makes a write fail regardless of the entry point, such as plan limits, rate limits or required headers | | Tenancy | For multi-tenant applications, a second account outside the first one's tenant, for isolation tests | | Infrastructure | Every database, cache, queue and store your code talks to, and whether Kerno may access each one | You decide what Kerno may touch. Each infrastructure component is recorded either with its connection details, or as off limits with an optional reason. **What calibration writes.** Calibration saves its results in `.kerno/config.yaml`, which you commit: * The confirmed facts become [custom rules](/docs/core-concepts/custom-rules) that every test reads. * The infrastructure inventory is saved for each application. * A `calibration` record notes the outcome, so your agent doesn't run it again. Secret values stay out of that file. It holds only the variable name, and the value goes in `.kerno/.env`, which Kerno keeps out of git. **The environment healthcheck.** From the infrastructure inventory, Kerno generates `.kerno/healthcheck.local.ts` (or `healthcheck.remote.ts`), with one check for your application and one for each component Kerno may access. The check runs periodically, and while it fails, Kerno reports the environment as not ready for tests. The file is yours to edit, and Kerno keeps your changes. **Declining or running it again.** You can decline calibration at any point. Kerno records that you declined and stops asking, and tests then run without shared sign-in, seeding or tenancy setup. To calibrate later, or again after you reset your environment, ask your agent: ``` Calibrate Kerno for this repo. ``` In Claude Code, you can also type `/kerno-calibrate`. During first-time setup, the [Kerno portal](/docs/portal/overview) shows calibration progress on its setup page. ### How Kerno reads your database schema Credentials alone are not enough to write to your database: Kerno also needs to know its shape. It reads that from your source, never by introspecting your running database. A final-state snapshot such as `schema.rb`, a `*.prisma` file or `schema.sql` is used when present, otherwise Kerno reads your migrations. Most projects work automatically. When a schema cannot be derived, Kerno pauses and asks you for a path or for the DDL. It keeps your answer for that one entry point. Another entry point asks again, and clearing Kerno's cache for the whole workspace forgets the answer. See [Environment setup issues](/docs/troubleshooting/environment-setup-issues). ### How Kerno authenticates to your entry points For each entry point, Kerno analyses your authentication code and records the mechanism it uses, how to present the credential, and which roles or scopes it requires. Because Kerno reads your actual authentication code, it can handle a wide range of schemes. Common ones include bearer tokens and JWTs, session tokens, API keys in a custom header, and OAuth 2.0 Where it can, Kerno gets the credential the way a client would, by calling your sign-up or login route. Where no such route exists, it seeds the credential directly in your datastore or identity provider, one of the cases direct access exists for. Some entry points require Kerno to construct the credential itself. It reads the exact claims your verifier enforces, including the audience and issuer from your own configuration, and mints a properly signed JWT using the signing secret you supplied. This is real authentication. Your application verifies the token exactly as it verifies production traffic. {% hint style="info" %} **Kerno never keeps your secret values**. It records only the name of the environment variable each secret lives in, such as `DB_PASSWORD`. You put the value in `.kerno/.env`, which Kerno keeps out of git and reads when a test runs. {% endhint %} # Baseline Tests Understand how Kerno generates test scenarios for your entry points, what a baseline is, and how both stay in sync as your code evolves. A baseline test reflects how your app currently behaves. Kerno captures your entry point's current behavior as a test, then assesses every future code change against it. If a change alters how your entry point behaves, the baseline catches it. ### Test scenarios Scenarios are the test cases Kerno generates for your entry points. 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 and are meant to be committed alongside your code. Kerno also tests [user flows](/docs/core-concepts/user-flows), journeys that walk several entry points in order. Each flow gets one test, stored under `.kerno/scenarios/flows/`. Every scenario is written twice, as a plain-English `.scenario.md` for you and an executable `.scenario.ts` for the sandbox. See [Anatomy of a Kerno test](/docs/references/anatomy-of-a-kerno-test) for how to read them. {% 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 test scenario runs in four phases. * **Arrange.** Set up any state the test needs, such as seeding a user, obtaining a token, or inserting a row. * **Act.** Make the request to the entry point under test. * **Assert.** Check the response and any observable side effects. * **Clean up.** Tear down test data and close connections. ### What baseline test record A baseline records what a correct response looks like. It captures the status code, every field in the response body, the response headers that describe behavior, and any state the entry point stored. Kerno builds the baseline from your entry point's own data contract, the response types defined in your code. So it checks that every field holds the type and value your handler produces, deciding each expected value from its source: * A value your handler always produces the same way, like a fixed status code, a constant string, or a field copied straight from the request, is recorded exactly. Any change to it shows up as a diff. * A value generated fresh on every run, like an id, a token, or a timestamp, is recorded by its format. A new id on each run never counts as a diff. The baseline also fixes the exact set of fields a response returns. A field the entry point did not return before shows up as a diff, which is how an accidentally exposed field, like an internal flag or a leaked password hash, gets caught. For HTTP routes, the baseline also records headers such as `Content-Type`, `Cache-Control`, `Set-Cookie`, the CORS headers and the security headers, each with its current value or as absent. A header-only change, like a CORS policy switched to a wildcard, shows up as a diff. Headers that change on every run, like `Date` or a request id, are left out. A baseline never records a leaked error detail, such as a stack trace, a file path, SQL text or an exception class name, as the expected error response. In security tests, each error response is also checked for the absence of those details. ### What Kerno tests Kerno generates two kinds of tests. **Validation tests** check that your entry point behaves correctly, and **security tests** check that it resists the vulnerabilities that apply to it. Kerno generates validation tests, and adds security tests when you ask for them. {% hint style="info" %} Before a run, your agent may confirm with you which kinds of tests you want, the effort level, and whether to test white box or black box, unless you already said so. Kerno keeps no preferences of its own. Your agent can save your answer in its own instruction files, such as `CLAUDE.md` or `AGENTS.md`, so it stops asking. {% endhint %} #### **Validation tests** For each entry point, Kerno generates validation scenarios across several categories of behavior, including:
| Category | Description |
|---|---|
| Functional API Workflows | Covers entry point behaviour, multi step request sequences, coordinated service interactions, and integration patterns across services. |
| Contract & Schema Validation | Checks request and response structures, data types, required fields, serialization rules, and version compatibility for the API. |
| Error Handling & Resilience | Validates status codes, error body formats, retry behaviour, backoff procedures, timeout handling, and controlled fallback behaviour. |
| Authorization & Authentication | Reviews token validation, role based access rules, permission scopes, session handling, and all credential related flows. |
| Boundary & Edge Cases | Examines 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. |
(wins on conflict)"] --> E E --> G[Planner] ``` For `POST /api/v1/payments` on the `payments-api` application, all four apply, in that order. For `GET /api/v1/invoices`, only the error-envelope and tenant rules apply; the payments-api rules do not. The planner also reads two sources that rank below your rules: * Context Kerno distills from your repository's documentation, such as `AGENTS.md`, `CLAUDE.md` and `README.md`. Text between `` and `` in those files is left out. * Lessons Kerno learned from earlier runs. See [Memory and learning](/docs/core-concepts/memory-and-learning). ```yaml # .kerno/config.yaml test-generation: context: | Error responses use our standard envelope. On every failure, assert the body matches { error: { code, message } }, not only the status code. endpoints: "/api/v1/**": | Every v1 route is tenant-scoped. Always assert that a request authenticated as tenant A cannot read or modify tenant B's records. applications: payments-api: test-generation: context: | Money amounts are integer minor units, never floats. Idempotency keys are required on every mutating request. endpoints: "POST /api/v1/payments": | Cover the duplicate-idempotency-key case explicitly: the second request must return the original payment, not create a second one. ``` #### Matching entry points | Pattern | Matches | | ------------------------------- | ---------------------------------------- | | `*` | Every entry point | | `/api/users` | That exact path, any method | | `GET /api/users` | That path and method only | | `/api/v1/*` | One path segment, e.g. `/api/v1/users` | | `/api/v1/**` | Any depth, e.g. `/api/v1/users/42/roles` | | `regex:^/api/v[0-9]+/users/.+$` | Anything the expression matches | # Memory and Learning Understand how Kerno remembers what it learns about your codebase and improves over time. Memory and learning is how Kerno gets better as it works with your codebase and learns from your feedback. ```mermaid flowchart LR A[Kerno needs an analysis] --> C{In memory and
still current?} C -->|Yes| F[Reuse it] C -->|No| E[Work it out] E --> G[Store it, stamped with
the current revision] U[A finding you review] --> G G --> F ``` Kerno learns in three ways: * **From your code** – Kerno works out how your app is structured, which files serve which routes, and how each entry point authenticates. This analysis is slow, so Kerno does it once and reuses it, re-deriving only the parts a code change affects. * **From running your tests** – While setting up and running tests, Kerno remembers what actually worked, like the steps needed to seed a user before a test can run. The next entry point in the same service reuses that instead of working it out again. * **From your feedback** – When you dismiss a flagged issue, Kerno saves your decision and applies it on every later run. When you answer a question Kerno asks, like where to find a schema, Kerno reuses your answer for that entry point. ### Reviewing what Kerno learned As Kerno tests your entry points, it writes down what it works out along the way. How a particular entry point authenticates, say, or what has to exist before a request will succeed. Kerno calls these lessons, and it reuses them when planning your next tests so it never works the same thing out twice. Sometimes a lesson is wrong. Kerno shows you what it has learned so you can say so. Ask your agent once a batch of tests has finished: ``` Show me what Kerno learned from that batch. ``` You get each lesson with what it says, which entry points it covers, and how many runs back it up. For each one you can: * **Agree.** It matches what you saw. Kerno keeps using it and marks it as checked by you. * **Amend.** The idea is right and the wording is off. Give Kerno better wording and it uses yours from then on. * **Disagree.** It should not be there at all. Kerno stops using it and will not write it again. The review also lists what Kerno's analyses read from your code, covering your repository's documentation, your build, your security setup, and the external services your app calls. Each analysis arrives as several records, one per part, and you judge each one the same way. These records come from reading your code, so they carry no run counts. {% hint style="info" %} Reviewing is optional and never holds up a run. Kerno carries on using a lesson you have not looked at, and labels it as unchecked while it does, so you can always tell what Kerno worked out on its own apart from what you confirmed. {% endhint %} ### How Memory is Stored Memory is kept as a git history alongside Kerno's working copy of your repository, on your machine. Each entry is a commit whose trailer records the code revision it was learned at: ``` kerno-scenarios | scenario memory: GET /users/me --- refs/HEAD/d3e136b8ec06451739fe5428789268317b976472 ``` Kerno also writes a copy of its memory records, such as lessons, into your repository at `.kerno/memory/`, one Markdown file per record with a header that shows whether it was reviewed, plus a generated `README.md`. The folder is meant to be committed, so your team can review what Kerno learned in pull requests, and Kerno removes any line in `.kerno/.gitignore` that would hide it. The copy leaves your machine only when you commit and push it. Kerno never reads it back. Two consequences worth knowing: * Memory persists across agent restarts. Clearing Kerno's cache for the whole workspace erases it, including the potential bugs you told Kerno to ignore, which then get flagged again. The copy in `.kerno/memory/` restores nothing. * Because entries are commits, older versions remain, so a memory that was recomputed still has its previous value in history. Every memory is stamped with the exact code revision it came from, so Kerno knows when a memory has gone stale and re-derives it. # How to Configure the Kerno Test Environment Learn how to connect Kerno to your running application, give it access to your database, and confirm the environment is ready to test. ### Introduction Kerno tests your application by calling it over HTTP against your real stack, which means it needs your app running at an address it can reach. You connect the two through your coding agent, which saves the configuration, points Kerno at your app, and confirms Kerno can reach it. In this guide, you will connect Kerno to your application, give it access to your database, and confirm the environment is ready to test. ### Prerequisites Before you begin, you will need: * Kerno installed and the agent running, with your coding agent connected over MCP. See the [Quickstart](/docs/getting-started/quickstart). * Docker running on your machine. ### Step 1. Index your app Tell your agent to set up Kerno for your project: ``` Set up Kerno for this project. ``` Kerno analyses your repository, indexes your codebase, and analyses its entry points. See [Codebase indexing](/docs/core-concepts/codebase-indexing). Setup also adds Kerno's skills for your coding agent under `.agents/skills/`, linked from `.claude/skills/`, and lists them in your local git exclude file so they never show up as changes. Your agent may also add a short Kerno note to its own instructions file, such as `CLAUDE.md` or `AGENTS.md`. If your repository contains more than one app, Kerno indexes all of them and your agent shows you the ones it found. Tell it which backend(s) you want to test. Each one is configured separately, with its own URL and its own dependency access, so a monorepo's services can run on different ports and against different databases. They all live in the one `.kerno/config.yaml` at your repository root, keyed by application. See [Ports and file paths](/docs/references/ports-and-file-paths) for the shape. ### Step 2. Connecting your app Kerno needs your app running before it can test it. Start it yourself, or ask your coding agent to start it for you, then point Kerno at it. To have your agent start the app and connect Kerno in one go: ``` Start my app locally and set up the Kerno environment for it. ``` Or start the app yourself and tell your agent to connect Kerno to it: ``` Set up the Kerno environment for this app. ``` If your app runs somewhere else you can reach, such as a shared dev environment, give that URL instead. Your agent saves the URL, and Kerno probes it from inside its sandbox to confirm it is reachable, so a wrong address is caught now instead of failing mid-test. Kerno then reports whether the environment is ready. Your agent waits for `ready_for_endpoint_test` to report `true` before running any tests, and you can check at any time: ``` Check the Kerno environment status. ``` {% hint style="info" %} Kerno reaches your app from inside its own sandbox and routes `localhost` to your machine, so an app bound to `127.0.0.1` works as is in most setups. Running containers do not mean Kerno is ready, so wait for the readiness signal before generating tests. {% endhint %} ### Step 3. Giving Kerno database access (optional) Kerno tests in one of two modes, depending on how much access you give it. * **White box (default).** Kerno also connects to your dependencies, such as your database, cache, or queue. This lets it set up state and verify results your API does not expose, like seeding a record your API has no way to create, or checking that a stored password was hashed. * **Black box.** Kerno talks to your app only over HTTP, like any external client, and works entirely through your own entry points. Kerno defaults to white box, and uses direct dependency access once you have configured it. Any individual run can opt out by asking for black box. See [Testing modes](/docs/references/testing-modes). To turn on white box, tell your agent to connect your dependencies. It works out the connection details from your project, so you do not need to give ports or URLs yourself: ``` Connect Postgres and Redis to Kerno. ``` Kerno also needs your database schema, which it derives from your source automatically for most projects. If it cannot, it pauses and asks you for a path rather than guessing. Your credentials stay on your machine. `config.yaml` records only the name of the environment variable each secret lives in, such as `DB_PASSWORD`, and you put the real value in `.kerno/.env`, which Kerno gitignores for you. Kerno reads it when a test runs. To keep Kerno away from a component your code talks to, such as a shared queue or a third-party service, tell your agent. Kerno records it as off limits and leaves it alone: ``` Kerno must never touch our Kafka cluster. ``` If your app calls other HTTP services, point Kerno at their OpenAPI specs, so tests match the real request and response shapes of those calls: ``` Our app calls the billing service. Its OpenAPI spec is at specs/billing.yaml. Add it to Kerno. ``` ### Step 4. Calibrating Kerno Once the environment is ready, your agent calibrates Kerno to your repository. This happens once per repository, and your agent starts it on its own. It works out how to sign in, how to seed test data, what makes writes fail and which infrastructure Kerno may touch. It checks each against your running app, then asks you to confirm them one at a time. Calibration records every piece of infrastructure your code talks to, so if you skipped Step 3, this is where you can give Kerno access. If your agent doesn't start it, or you want to run it again, ask: ``` Calibrate Kerno for this repo. ``` Calibration also generates an environment healthcheck from your infrastructure. From then on, readiness depends on it too, so `ready_for_endpoint_test` stays `false` while your app or a dependency Kerno may access is failing its check. To re-run the check after a fix: ``` Check the Kerno environment status and refresh the healthcheck. ``` See [Calibration](/docs/core-concepts/environment-setup#calibration) for what it records and how to decline it. ### Step 5. Updating your configuration Kerno stores your settings under `.kerno/` at your repository root: ``` .kerno/ ├── config.yaml # how Kerno reaches your app and its dependencies, committed ├── .env # the real secret values, gitignored ├── .gitignore # keeps .env out of git ├── healthcheck.local.ts # the environment healthcheck from calibration, committed ├── memory/ # what Kerno has learned about your repository, committed ├── criticality.json # entry points your team marked critical in the Portal, committed └── scenarios/ # generated tests, committed ``` In a monorepo, each app keeps its own `scenarios/` and `criticality.json` in a `.kerno/` folder inside the app's directory. `config.yaml` is committed, so your whole team shares one configuration and every change to it is reviewable in a pull request. It names the environment variable each secret uses. The values themselves live in `.kerno/.env`, which Kerno adds to `.kerno/.gitignore` for you. Your generated tests under `scenarios/` are committed as well. You rarely edit these by hand. Your agent writes them and keeps them current as things change. If your app moves to a new port or a dependency changes, Kerno reports that it can no longer reach your app, and your agent works out the new details and saves them. You can also tell it directly: ``` My app moved to port 4000. Update the Kerno config. ``` ### Next Steps Your app is connected to Kerno, calibrated, and the environment reports ready. Kerno can now reach your app over HTTP, and if you gave it dependency access, it can set up and verify state directly as well. Next, [capture a baseline](/docs/guides/capture-a-baseline). Kerno generates tests for your entry points and runs them against your app to record how it behaves today, which becomes the reference every future change is checked against. # How to Create Baseline Tests for your Entry Points Learn how to generate baseline tests for an entry point, review the plan, and run them to capture how your app behaves. ### Introduction A baseline is a test that records how an entry point behaves against your running stack, and the reference point Kerno uses to detect changes later. Kerno captures one by analysing the entry point, writing a set of tests, and running them against your app to capture its actual responses. In this guide, you will list your entry points, generate baseline tests for one and review the plan, then run them to capture the baseline. ### Prerequisites Before you begin, you will need: * Your application running, with Kerno pointed at it. See [How to Configure the Kerno Test Environment](/docs/guides/start-the-environment). * The environment reporting `ready_for_endpoint_test`. ### Step 1. Listing your entry points Ask your agent to list the entry points Kerno found: ``` Use Kerno to list the entry points in this app. ``` You get the entry points Kerno discovered, such as HTTP routes, background consumers and MCP tools, grouped by the file that defines them, each one showing whether it already has baseline tests. {% hint style="warning" %} In a large app, listing everything can return thousands of entry points. Narrow it with a scope to the part you care about, such as a single file or one entry point. {% endhint %} Narrow it to a single file: ``` Use Kerno to list the entry points in src/routes/users.ts. ``` Or a single route: ``` Use Kerno to list POST /users. ``` ### Step 2. Generating baseline tests for an entry point Pick an entry point and ask your agent to generate baseline tests for it: ``` Use Kerno to generate baseline tests for POST /users. ``` Before it starts, your agent confirms three choices with you, unless you have already stated them in the chat or in your agent's rules file: * **Effort.** How hard Kerno works to prove each test is solid. `low` writes and runs each test once. `medium` runs it twice to prove it is repeatable. `high`, the default, adds an iterative pass that critiques and repairs each test until it holds up. Higher effort takes longer and produces sturdier tests. An entry point your team marked as critical in the Kerno Portal always runs at `high`, whatever you choose. See [Testing modes](/docs/references/testing-modes). * **Testing mode.** White box, the default, lets Kerno use the dependency access you configured to set up and check state directly. Black box limits it to calling your app like any external client. See [Testing modes](/docs/references/testing-modes). * **Test types.** Validation tests, security tests, or both. Validation, the default, checks that the entry point behaves correctly. Security assesses the entry point against the OWASP Top 10 and writes tests that probe for vulnerabilities. Asking for security on its own narrows the run to the happy path plus those vulnerability tests, so ask for both when you want your functional coverage as well. See [Security testing](/docs/references/security-testing). With those set, Kerno analyses the entry point, works out how it authenticates and what it depends on, and plans a set of scenarios covering the happy path, error handling, edge cases, and authorization. It then stops to show you the plan. #### 2.1 Covering multiple entry points You can cover several entry points in one go. Ask your agent to work through a group of them, or a whole file: ``` Use Kerno to create baseline tests for all the entry points in my users API. ``` Your agent can cover them one at a time, approving each plan before moving to the next, or dispatch the whole group in a single batch. See [Testing many entry points in one call](/docs/references/kerno-mcp#testing-many-entry-points-in-one-call). ### Step 3. Reviewing the plan The plan is Kerno's read of your entry point. It lists the test scenarios Kerno intends to write, each with the situation to set up, the request to send, and the response it expects. Reading it is the point of this step, because it shows you what Kerno believes your entry point does before it writes any code. Approve the plan and Kerno starts implementing: ``` Looks good, go ahead. ``` Or send it back with changes. You can drop scenarios, add new ones Kerno missed, or ask for something specific: ``` Drop the pagination test and add one for a duplicate email. ``` ``` Add a scenario that checks a non-admin cannot create a user. ``` Sending it back re-plans with your feedback and shows you a new plan. You can iterate as many times as you need. {% hint style="info" %} Changes you make to a plan apply to the current run. The feedback Kerno carries between runs is the decisions you make on results, like telling it a finding is intended so it stops flagging that entry point, along with what it learns about your entry point such as how to authenticate. See [Memory and learning](/docs/core-concepts/memory-and-learning). {% endhint %} Approving is what tells Kerno to write and implement the test scenarios. ### Step 4. Letting Kerno implement and run Once you approve, Kerno writes each scenario and runs it against your application, repeating until it passes. Tes scenarios land under `.kerno/scenarios/endpoints/` as TypeScript files. Before it runs anything, Kerno checks its **preconditions**, a set of readiness checks that confirm it can actually test the entry point. They verify the entry point is reachable, the intended user can authenticate, any required environment variables are set, and expected seed data exists. Whether your dependencies are up is the job of the [environment healthcheck](/docs/core-concepts/environment-setup#calibration). The checks read your data and change nothing, apart from one case. If you have not given Kerno a working test login, they may create a throwaway test user, through your app's signup route when there is one. What the entry point should do is left for the tests to decide. If Kerno cannot satisfy the preconditions, it stops and tells you what it needs, such as a schema it could not derive or a credential, so you can provide it and run again. {% hint style="info" %} Kerno always writes test 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 %} {% hint style="info" %} Kerno writes two files per scenario. The `.scenario.md` is the one to read, since it describes the scenario in plain English. The `.scenario.ts` beside it is the executable version the sandbox runs. See [Anatomy of a Kerno test](/docs/references/anatomy-of-a-kerno-test). {% endhint %} ### Step 5. Reading the result When you are signed in to Kerno, your agent also gives you a link to the run's page in the [Kerno Portal](/docs/portal/overview), where you can follow it and read the results. Kerno reports each scenario as one of: * **passed** means the scenario ran and recorded the entry point's behaviour as your baseline. * **failed** means Kerno wrote the scenario and ran it, but it did not pass. Kerno reports what went wrong so you can fix the cause and run it again. * **blocked** means the scenario could not run because a precondition or capability it needs is missing, so nothing was tested. Often it needs direct database access that is not configured, and Kerno tells you which dependency to add to unblock it. {% hint style="info" %} You may occasionally see **not implemented**. This means Kerno could not produce a working scenario for a case and left the placeholder from the plan in place, rather than counting it as a pass. Nothing was tested. {% endhint %} A baseline captures how your entry point behaves today, including any bugs it currently has. Once your tests pass, read through the recorded responses and confirm they are what the entry point should return. If they look right, your baseline is ready. If something is wrong, fix your code and run the baseline again so it records the corrected behaviour. #### 5.1 Potential bugs A scenario that passed can also carry a **potential bug**. Kerno found the entry point doing something the plan did not expect, confirmed it against your source, and wrote the test to document the real behaviour. The note explains the root cause and what a future change would mean. If the behaviour is known or intended, tell your agent to ignore it, and Kerno stops flagging it on that entry point: ``` The role field on GET /users/:id is intentional, we return it for backwards compatibility. Have Kerno ignore that potential bug. ``` Later runs, including reviews of your code changes, no longer report it. The test file keeps its note about the bug until you ask Kerno to update that entry point's tests. Clearing Kerno's whole cache forgets the decision, and the bug is reported again. ### Editing baseline tests To change what a baseline test does, ask your agent to update it rather than editing the file by hand. Kerno rewrites the test and re-runs it against your app, so the baseline still reflects real behaviour. ``` Use Kerno to update the baseline tests for POST /users. The response no longer includes the role field. ``` ### Next Steps You now have baseline tests capturing how your entry points behave today. From here, Kerno re-runs them each time you change code and tells you what moved, so a regression surfaces the moment it appears. # How to Review your Code Changes Learn how to review a code change against your baseline tests, read the result, and update them when the change was intentional. ### Introduction Reviewing your changes is the day-to-day loop. You change some code, Kerno re-runs the baseline tests for the affected entry points, and tells you whether their behaviour moved. In this guide, you will trigger a review, read the result, and bring the tests along when a change was intentional. ### Prerequisites Before you begin, you will need: * Baseline tests already generated for the entry points you want to review. See [How to Create Baseline Tests for your Entry Points](/docs/guides/capture-a-baseline). * Your application running with your changes applied. ### Step 1. Triggering a review After changing code, ask your agent to review the entry points your change affected: ``` Use Kerno to validate the entry points and flows my changes affected. ``` Kerno maps your change through the call graph to every entry point it reaches, so a change to a shared helper is reviewed alongside the obvious ones. For each affected entry point, it re-runs the baseline tests already on disk against your current code and reports where behaviour moved. It also re-runs the [user flows](/docs/core-concepts/user-flows) that cross those entry points. Kerno reviews the changes you have not committed yet, staged or unstaged, against your last commit. Run the review before you commit, and `git add` any new files first, since Kerno only sees files git tracks. See [Code Change Review](/docs/core-concepts/change-validation#detecting-diffs). You can also review a single entry point: ``` Use Kerno to validate POST /users. ``` A review only re-runs tests that already exist. If an entry point has no tests yet, Kerno reports that it has none, so ask your agent to [create a baseline](/docs/guides/capture-a-baseline) for it first. ### Step 2. Reading the result When a review finishes, Kerno re-runs each baseline test against your current code and checks whether the response still matches the one the baseline recorded. When you are signed in to Kerno, your agent also gives you a link to each review's page in the [Kerno Portal](/docs/portal/overview). A diff is a difference between the response the baseline recorded and what your entry point returns now. Kerno matches values that legitimately change between runs, such as generated ids, tokens, and timestamps, by their shape, so a fresh id or timestamp never counts as a diff. A field that appears where the baseline had none does count, even without an explicit assertion for it, which is how an accidentally leaked field, like an internal flag or a password hash, gets caught. The same goes for response headers that describe behaviour, such as content type, caching, cookies, CORS and security headers, so a header that changes, appears or disappears is a diff too. Each test comes back as one of four outcomes: * **Passed.** No diff was detected. The behaviour this test covers matches the baseline, so your change left it unchanged. * **Blocked.** The scenario never ran, usually because a dependency it needs is not configured. Nothing was tested. Kerno tells you what is missing, so you can ask your agent to fix it and run the review again. See [How to Configure the Kerno Test Environment](/docs/guides/start-the-environment). * **Failed.** A diff was detected. The behaviour moved from the baseline. Kerno reports every assertion that did not match, each with a clue explaining what it was checking and a diff of expected against actual, so you see every change from one run. * **Not implemented.** The test still holds the placeholder from its plan, because Kerno never finished writing it. Nothing was tested. A diff does not always mean something is broken. It only tells you the behaviour changed, and it is up to you to decide: * **The change is a bug.** Fix your code and review again. * **The change is intentional.** Your entry point genuinely changed and the tests need to follow, so update the baseline (Step 3). ### Step 3. Updating baseline tests Ask your agent to update when a diff is intentional, or when you have added logic that no test covers yet: ``` Use Kerno to update the tests for POST /users. The response no longer includes the role field. ``` Kerno reconciles the suite with your change: * It re-baselines the tests that diffed, so their expectations match the new behaviour. * It adds tests for new logic your change introduced that nothing covers yet. * It keeps every test that still applies, and removes one only when you tell it that test is obsolete. {% hint style="info" %} When you add logic that none of the existing tests exercise, the review shows no diff. Ask Kerno to update the tests for that entry point and it adds coverage for the new logic: ``` Use Kerno to update the tests for POST /users. ``` {% endhint %} ### Conclusion That is the loop. Change code, review the affected entry points, and update the tests when a change is intentional, so your baseline always reflects how your app should behave. From here, see [Custom Rules](/docs/core-concepts/custom-rules) to shape how Kerno tests, and [Memory and learning](/docs/core-concepts/memory-and-learning) to see how it improves over time. # How to Test a User Flow Learn how to map the key journeys through your app, test one end to end, and re-check it after a code change. ### Introduction A user flow is a journey a person takes through your product, such as signing up and creating a first project. Kerno tests it end to end, across every entry point it crosses, and checks that the outcome actually happened. See [User flows](/docs/core-concepts/user-flows) for the concept. In this guide, you will map your key flows, test one, and re-check it after a code change. ### Prerequisites Before you begin, you will need: * Kerno set up, with your environment ready and calibrated. See [How to Configure the Kerno Test Environment](/docs/guides/start-the-environment). * Your application running. ### Step 1. Mapping your flows Your agent usually maps your flows with you right after calibration. To map them, or to add more later, ask: ``` Map the key user flows in this app with Kerno. ``` Your agent asks which journeys matter most, then records the flows you confirm in your own words. Recording a flow runs nothing yet. ### Step 2. Testing a flow Pick a journey and ask your agent to test it: ``` Use Kerno to test the checkout flow. ``` Kerno plans one test that walks the steps in order and checks the outcome at the end. If the journey needs an account or credential Kerno doesn't have yet, Kerno may ask you for it through your agent. ### Step 3. Approving the plan Kerno always shows you the plan before it writes the test. Read it through and check that the steps and the expected outcome match the journey you meant, then approve it, or tell your agent what to change. Once you approve, Kerno writes the test, checks that it passes twice in a row, and runs it against your application. If the journey breaks, the result shows the step where it failed. ### Step 4. Re-checking after a change After you change code, ask your agent to review it: ``` Use Kerno to validate the entry points and flows my changes affected. ``` Kerno reports which flows your change touches, and your agent re-runs them along with the affected entry points' tests. When a journey changed on purpose, tell your agent, and Kerno plans the flow's test again for your approval. ### Next Steps Your first flow is tested, and it is re-checked whenever you review a change that reaches it. Map the rest of your key journeys the same way, and see [How to Review your Code Changes](/docs/guides/validate-code-changes) for reading the results of a review. # How to Customize Kerno with Custom Rules Learn how to add a custom rule, apply it to your entry points, and edit or remove rules as your team's conventions change. ### Introduction Custom rules are standing guidance you keep in your repository, so Kerno applies them on every run without you restating them. They shape how the planner writes tests, and they travel with your code. In this guide, you will add a rule, apply it to an entry point, and then edit and remove rules. For how rules are weighed, merged, and matched to entry points, see [Custom Rules](/docs/core-concepts/custom-rules). ### Prerequisites Before you begin, you will need: * [Kerno installed](/docs/getting-started/quickstart) and connected to your coding agent over MCP. * Your application running, with the [Kerno test environment configured and ready.](/docs/guides/start-the-environment) ### Step 1. Add a rule The quickest way to add a rule is to ask your agent: ``` Add a Kerno rule for POST /api/users: a duplicate email should return 409. ``` Your agent writes the rule into `.kerno/config.yaml` under `test-generation`. That file is committed, so your team inherits your rules. A `context` block applies to every entry point, and an `endpoints` map scopes guidance to specific routes: ``` test-generation: context: | ... endpoints: "POST /api/users": | ... ``` You can also edit this file by hand. The entry point pattern grammar is covered in [Custom Rules.](/docs/core-concepts/custom-rules) ### Step 2. Apply and verify A new rule shapes the next `generate` for an entry point that has no tests yet. Ask your agent to generate that entry point: ``` Use Kerno to generate tests for POST /api/users. ``` When the plan comes back for review, the guidance shows up in the scenarios it proposes, here a scenario covering the duplicate-email case. Approve the plan to implement them. ### Step 3. Apply a rule to an entry point that already has tests To bring an entry point that already has tests in line with a new rule, ask your agent to update its tests: ``` Use Kerno to update the tests for POST /api/users to follow the new duplicate-email rule. ``` Kerno keeps the tests that still apply, revises the ones the rule changes, and adds the ones it is missing. Editing the config on its own leaves existing tests as they are, see [Custom Rules](/docs/core-concepts/custom-rules). Generating again keeps the tests you already have, and generating with new one-off guidance replaces the whole suite with a fresh plan once you approve it. ### Step 4. Edit or remove a rule Ask your agent to change or remove a rule: ``` Update the Kerno rule for POST /api/users to also assert the response includes the created user id. Remove the Kerno rule for POST /api/users. ``` You can also edit `.kerno/config.yaml` by hand, change a rule's text to edit it, or delete its `context` block or `endpoints` entry to remove it. Edits and removals behave like additions. They change what Kerno plans on the next run, and they leave existing tests untouched. Update the affected entry points' tests when you want the change to apply. Where several rules match the same entry point, Kerno applies all of them, and guidance you give for a single run takes precedence when they conflict. For the full merge and precedence order, see [Custom Rules](/docs/core-concepts/custom-rules). ### Conclusion That is the rule lifecycle. Add a rule, generate to apply it, and edit or remove it as your conventions change, updating the affected entry points' tests each time. From here, see [Custom Rules](/docs/core-concepts/custom-rules) for how rules are weighed and matched, [Testing modes](/docs/references/testing-modes) for per-run guidance, and [How to Review your Code Changes](/docs/guides/validate-code-changes) for the everyday validation loop. # How to Run your Baseline Tests in CI Learn how to replay your committed baseline tests against your application on every pull request, and read the result as a check. ### Introduction The baseline tests Kerno writes are files in your repository. Once they are committed, anything that can run them can run them, including your CI. This guide wires up the Kerno GitHub Action. On every pull request it replays the baseline tests you have committed against your running application and reports the result as a check, so behaviour that moved is caught where your team already reviews changes rather than on one developer's machine. It needs **no Kerno account, no API key and no agent**. The action pulls one public image and runs the tests already in your repository. Nothing calls a language model, which is also why it is fast and free to run. To also follow each run in the Kerno portal, add an API key ([Step 6](#step-6-seeing-runs-in-the-kerno-portal)). ### Prerequisites Before you begin, you will need: * Baseline tests committed under `
| :chart-line: Analytics | Coverage, code changes tested and potential issues caught across your repositories. | Analytics |
| :list-check: Coverage | Every user flow and entry point Kerno tests, and which ones have tests today. | Coverage |
| :flask: Runs | Every run Kerno executed on your code, and what it found. | Runs |
| :code-compare: Behaviour Drift | How the tests behind each flow and entry point changed, period by period. | Behaviour Drift |
| :folder-tree: Repos | Every repository Kerno has seen, with its coverage, runs and drift. | Repos |
| :users: Orgs and Teams | Manage your organization, invite teammates, and set roles. | Organizations and Teams |
| :plug: Integrations and API keys | Issue an API key, pick up the CI workflow, and connect GitHub. | Integrations and API keys |
| :credit-card: Billing | Manage your plan, payment method and invoices. | Billing |
| Project Name | GitHub Repo | Framework | Dependencies |
|---|---|---|---|
| Typescript Example Project | https://github.com/kernoio/example-typescript | Express.js | PostgreSQL |
| Project Name | GitHub Repo | Framework | Dependencies |
|---|---|---|---|
| Python Example Project | https://github.com/kernoio/example-python | FastAPI | PostgreSQL |