# Read the manual.

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

## Pages

### Start

- [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 lives and what its name means.
- [Contract tests](https://turnstone.cloud/docs/contract-tests.md): Call your running service from Node.
- [HTTP tests](https://turnstone.cloud/docs/http-tests.md): Drive routes with k6, signed in as named actors.
- [Browser tests](https://turnstone.cloud/docs/browser-tests.md): Assert on a real page in Chromium.
- [Database tests](https://turnstone.cloud/docs/database-tests.md): Run SQL against a Postgres that Testkit builds.

### Run

- [CI](https://turnstone.cloud/docs/ci.md): One command decides whether a pull request merges.
- [Results](https://turnstone.cloud/docs/results.md): Where a run's evidence lands and how to read it.
- [CLI](https://turnstone.cloud/docs/cli.md): Every command and flag.
- [Configuration](https://turnstone.cloud/docs/configuration.md): Every field of `testkit.config.ts`.

### Hunt bugs

- [Campaigns](https://turnstone.cloud/docs/campaigns.md): Give your agent a target and collect proven bugs.
- [Bug reports](https://turnstone.cloud/docs/bug-reports.md): The five things every issue states.

### Turnstone

- [Turnstone](https://turnstone.cloud/docs/cloud.md): What the dashboard keeps, and what it never stores.
- [Connect GitHub](https://turnstone.cloud/docs/connect-github.md): Connect a repository, and see the access Turnstone asks for.
- [Connect Gitea](https://turnstone.cloud/docs/connect-gitea.md): Add your Gitea host, then connect a repository.
- [Sync](https://turnstone.cloud/docs/sync.md): When Turnstone reads your issues, and what it reads.
- [Facts](https://turnstone.cloud/docs/facts.md): Each fact about a bug, and where Turnstone reads it.

## Four parts, and one is optional

- **Your repo** holds the tests and the config. Policy goes in `testkit.config.ts`.
- **The CLI** runs in your repo. Your coding agent uses it to write tests and hunt bugs, and CI uses it to run them. It works without a server.
- **GitHub or Gitea** gets everything a person acts on: issues, checks and statuses, and pull requests that add tests.
- **Turnstone** is an optional, read-only dashboard. It receives run facts from GitHub or Gitea and charts them.

The first three are free. None of them asks for an account, a licence key, or a payment. Turnstone has a free tier.

## What you need

| Requirement | Version |
| --- | --- |
| Node | `>=22.15.0 <23.0.0` or `>=24.14.1 <25.0.0` |
| npm | `>=11.6.0 <12.0.0` |
| Docker | Only for a service that declares `database.postgres(...)` |

```sh
npm install --save-dev @gfdelarue/testkit
```

If Testkit is not in your repo yet, start with [Get started](https://turnstone.cloud/quickstart). It has five steps and ends with a merge gate.

## Hand these pages to your agent

Every page here has a Markdown copy. Add `.md` to the page's URL, or press **Copy page** at the top of the page.

| URL | Contents |
| --- | --- |
| [`/llms.txt`](https://turnstone.cloud/llms.txt) | Every page, with a one-line summary of each |
| [`/llms-full.txt`](https://turnstone.cloud/llms-full.txt) | Every page in one file |
| [`/docs/ci.md`](https://turnstone.cloud/docs/ci.md) | One page, in this case the CI guide |

The package ships its own reference too. Your agent can read these files without a network call.

| File | Contents |
| --- | --- |
| `node_modules/@gfdelarue/testkit/README.md` | The CLI, the engines, and the CI gate |
| `node_modules/@gfdelarue/testkit/testkit-config-schema.md` | Every field of `testkit.config.ts` |
| `node_modules/@gfdelarue/testkit/docs/bug-records.md` | The format of the issues that Testkit files |