# Testkit

> Testkit is a test runner and CLI for coding agents and CI. These pages cover Testkit 0.4.1.

Each link below is a Markdown page, except Get started. [llms-full.txt](https://turnstone.cloud/llms-full.txt) holds every page in one file.

## Start

- [Overview](https://turnstone.cloud/docs.md): Testkit is a test runner and CLI for coding agents and CI. These pages cover Testkit 0.4.1.
- [Get started](https://turnstone.cloud/quickstart): Five steps from install to a merge gate.

## Write tests

- [Test files](https://turnstone.cloud/docs/test-files.md): Where a test file lives, what its name means, and the one declaration every file needs.
- [Write a contract test](https://turnstone.cloud/docs/contract-tests.md): A contract test runs in Node under Vitest. Testkit starts your service, gives the test an HTTP client that points at it, and stops the service when the run ends.
- [Write an HTTP test](https://turnstone.cloud/docs/http-tests.md): An HTTP test drives your running service with k6. Use it for int, e2e, and load files.
- [Write a browser test](https://turnstone.cloud/docs/browser-tests.md): A browser test opens your running app in Chromium with Playwright. Use it when the browser is part of the assertion.
- [Test the database](https://turnstone.cloud/docs/database-tests.md): A database test runs SQL against a local Postgres that Testkit builds from your schema. Use it for constraints, queries, and anything else the database decides.

## Run

- [Gate merges in CI](https://turnstone.cloud/docs/ci.md): Run Testkit on every pull request, block the merge when a test fails, and report each run to GitHub or Gitea as a commit status and a pull request comment.
- [Read a run's results](https://turnstone.cloud/docs/results.md): Every run prints a summary and seals a record under .testkit/results. This page shows how to read both.
- [CLI reference](https://turnstone.cloud/docs/cli.md): Every command and flag in Testkit 0.4.1.
- [Configuration reference](https://turnstone.cloud/docs/configuration.md): The fields of testkit.config.ts in Testkit 0.4.1. The file lives at the repo root and holds the repo's test policy.

## Hunt bugs

- [Run a campaign](https://turnstone.cloud/docs/campaigns.md): A campaign gives your coding agent a target. The agent works through the CLI, and each bug it proves lands in GitHub or Gitea as an issue that names a failing test.
- [What a bug report states](https://turnstone.cloud/docs/bug-reports.md): Testkit files each bug as an issue in GitHub or Gitea. The issue has five sections, names the test that fails, and ends with a facts block.

## Turnstone

- [What Turnstone keeps](https://turnstone.cloud/docs/cloud.md): Turnstone is an optional, read-only dashboard. It keeps facts about bugs and charts them. Your reports, tests, and evidence stay in GitHub or Gitea.
- [Connect a GitHub repository](https://turnstone.cloud/docs/connect-github.md): Connect a GitHub repository to a Turnstone project, and see the access that Turnstone asks for.
- [Connect a Gitea repository](https://turnstone.cloud/docs/connect-gitea.md): Add your Gitea host to Turnstone, connect a repository, and see the access that Turnstone asks for.
- [How Turnstone syncs a repository](https://turnstone.cloud/docs/sync.md): When Turnstone reads your issues, what it reads, and what it does with an issue that has no facts.
- [The facts Turnstone keeps](https://turnstone.cloud/docs/facts.md): Each fact that Turnstone keeps about a bug, where Turnstone reads it from, and what Turnstone never stores.