Docs

Start

Read the manual.

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

View as Markdown

Start

Write tests

Run

Hunt bugs

Turnstone

On this page
  1. Four parts, and one is optional
  2. What you need
  3. Hand these pages to your agent

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

RequirementVersion
Node>=22.15.0 <23.0.0 or >=24.14.1 <25.0.0
npm>=11.6.0 <12.0.0
DockerOnly for a service that declares database.postgres(...)
$npm install --save-dev @gfdelarue/testkit

If Testkit is not in your repo yet, start with Get started. 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.

URLContents
/llms.txtEvery page, with a one-line summary of each
/llms-full.txtEvery page in one file
/docs/ci.mdOne page, in this case the CI guide

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

FileContents
node_modules/@gfdelarue/testkit/README.mdThe CLI, the engines, and the CI gate
node_modules/@gfdelarue/testkit/testkit-config-schema.mdEvery field of testkit.config.ts
node_modules/@gfdelarue/testkit/docs/bug-records.mdThe format of the issues that Testkit files
  1. OverviewStartWhat Testkit is, and what you need to run it.
  2. Get startedStartFive steps from install to a merge gate.
  3. Test filesWrite testsWhere a test lives and what its name means.
  4. Contract testsWrite testsCall your running service from Node.
  5. HTTP testsWrite testsDrive routes with k6, signed in as named actors.
  6. Browser testsWrite testsAssert on a real page in Chromium.
  7. Database testsWrite testsRun SQL against a Postgres that Testkit builds.
  8. CIRunOne command decides whether a pull request merges.
  9. ResultsRunWhere a run's evidence lands and how to read it.
  10. CLIRunEvery command and flag.
  11. ConfigurationRunEvery field of testkit.config.ts.
  12. CampaignsHunt bugsGive your agent a target and collect proven bugs.
  13. Bug reportsHunt bugsThe five things every issue states.
  14. TurnstoneTurnstoneWhat the dashboard keeps, and what it never stores.
  15. Connect GitHubTurnstoneConnect a repository, and see the access Turnstone asks for.
  16. Connect GiteaTurnstoneAdd your Gitea host, then connect a repository.
  17. SyncTurnstoneWhen Turnstone reads your issues, and what it reads.
  18. FactsTurnstoneEach fact about a bug, and where Turnstone reads it.