> 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/guides/start-the-environment.md). # 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.md). * 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.md). 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.md) 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.md). 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.md#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, your agent turns to your user flows. If none are recorded yet, it maps the journeys that matter with you and offers to test one. See [How to Test a User Flow](/docs/guides/test-a-user-flow.md). To test a single entry point, [capture a baseline](/docs/guides/capture-a-baseline.md). Kerno generates tests for it and runs them against your app to record how it behaves today, which becomes the reference every future change is checked against.