Test Environment
Understand how Kerno connects to your running application and its dependencies to test against your real stack.
Kerno connects to your running app and the services it depends on, so it runs tests against your real stack. That gives you high-fidelity results that reflect how your app behaves in production.
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 ashttp://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.
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.
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 for the full list.
Any individual run can opt out and go black box. See 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:
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.
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 that every test reads.
The infrastructure inventory is saved for each application.
A
calibrationrecord 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:
In Claude Code, you can also type /kerno-calibrate. During first-time setup, the Kerno portal 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.
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.
Last updated