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.
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 endpoints. See Codebase indexing.
If your repository contains more than one app, Kerno shows you the ones it found and asks which to index. Pick the backend(s) you want to test.
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:
Or start the app yourself and tell your agent to connect Kerno to it:
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:
Step 3. Giving Kerno database access (optional)
Kerno tests in one of two modes, depending on how much access you give it.
Black box (default). Kerno talks to your app only over HTTP, like any external client, and works entirely through your own endpoints.
White box. 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 that has no creation endpoint, or checking that a stored password was hashed.
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:
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. Kerno records only the name of the environment variable each secret lives in, such as DB_PASSWORD, and reads the value when a test runs.
Step 4. Updating your configuration
Kerno stores your settings under .kerno/ at your repository root:
config.yaml holds your local settings and credentials and is gitignored. default.config.yaml holds team-wide defaults and is committed, as are your generated tests under scenarios/.
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:
Next Steps
Your app is connected to Kerno 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. Kerno generates tests for your endpoints and runs them against your app to record how it behaves today, which becomes the reference every future change is checked against. Continue to Capture a baseline.
Last updated