Guides

Practical patterns for adding behaviours, investigating failures, and making regressions visible.

Author a suite with an explicit engine

Testkit supports three engines: k6 for int, e2e, scenario, and load through k6-http, plus dal through k6-dal; node-vitest for data and contract; and playwright for ui. A filename suffix and defineFile({ engine: "..." }) must be a supported pair.

// frontend/src/components/layout/__testkit__/navigation.ui.testkit.ts
import { defineFile } from "@(scope)/testkit";
import { test, expect } from "@(scope)/testkit/playwright";

export const testkit = defineFile({ engine: "playwright" });

test("navigation remains available", async ({ page }) => {
  await page.goto("/");
  await expect(page.getByRole("navigation")).toBeVisible();
});

Discover before you run

npx testkit discover
npx testkit discover --output-mode verbose
npx testkit discover --json > .testkit/discovery.json

Discovery shows the service, test type, suite, file, engine, ownership, and skip information that Testkit derives before it schedules work.

Investigate and verify

npx testkit --service api --type int -s health
npx testkit --type ui --file frontend/src/components/layout/__testkit__/navigation.ui.testkit.ts
npx testkit status

Use the targeted run to reproduce a result, then inspect the sealed run bundle in .testkit/results/runs/<run-id>/. The latest run projection is available at .testkit/results/latest.json; it is a convenience view, not the historical authority.