@gfdelarue/testkit 0.5.0 → 0.6.0

package/dist/types/workspace.d.ts

@@ -4,14 +4,10 @@ declare const ENGINE_IDS: readonly [
 ];
 export type EngineId = (typeof ENGINE_IDS)[number];
 declare const PUBLIC_TEST_TYPES: readonly [
-	"ui",
-	"contract",
-	"data"
+	"ui"
 ];
 export type PublicTestType = (typeof PUBLIC_TEST_TYPES)[number];
 declare const RUNNER_PROFILE_IDS: readonly [
-	"node-vitest-data",
-	"node-vitest-contract",
 	"node-vitest",
 	"playwright-ui"
 ];
@@ -23,8 +19,7 @@ declare const RUNTIME_ISOLATION_POLICIES: readonly [
 export type RuntimeIsolationPolicy = (typeof RUNTIME_ISOLATION_POLICIES)[number];
 declare const RUN_TYPE_VALUES: readonly [
 	"ui",
-	"contract",
-	"data",
+	"plain",
 	"all"
 ];
 export type RunType = (typeof RUN_TYPE_VALUES)[number];
@@ -55,6 +50,28 @@ export interface SerializedError {
 	diagnostics?: ErrorMetadataObject;
 	stack?: string;
 }
+declare const RETIRED_SUITE_IDENTITIES: readonly [
+	...{
+		readonly engineId: "k6";
+		readonly profileId: "k6-http";
+		readonly testType: "e2e" | "int" | "load" | "scenario";
+	}[],
+	{
+		readonly engineId: "k6";
+		readonly profileId: "k6-dal";
+		readonly testType: "dal";
+	},
+	{
+		readonly engineId: "node-vitest";
+		readonly profileId: "node-vitest-contract";
+		readonly testType: "contract";
+	},
+	{
+		readonly engineId: "node-vitest";
+		readonly profileId: "node-vitest-data";
+		readonly testType: "data";
+	}
+];
 export type ReportingRecord = Record<string, unknown>;
 export interface ReportingFailureRequest extends ReportingRecord {
 	method?: string;
@@ -131,9 +148,9 @@ export interface RunArtifactSuite extends ReportingRecord {
 	files?: RunArtifactFile[];
 	name: string;
 	passedFileCount?: number;
-	profileId: RunnerProfileId | "k6-dal" | "k6-http";
+	profileId: RunnerProfileId | (typeof RETIRED_SUITE_IDENTITIES)[number]["profileId"];
 	skippedFileCount?: number;
-	testType?: PublicTestType | "dal" | "e2e" | "int" | "load" | "scenario";
+	testType?: PublicTestType | (typeof RETIRED_SUITE_IDENTITIES)[number]["testType"];
 }
 export interface RunArtifactGroup extends ReportingRecord {
 	name: string;
@@ -370,7 +387,7 @@ export type VitestSelection = Readonly<{
 	project: null | string;
 	runner: "auto" | "managed" | "repo";
 }>;
-export type TestGroupSource = "groups" | "implicit" | "services";
+export type TestGroupSource = "groups" | "implicit";
 export interface DiscoverySummary {
 	activeFiles: number;
 	byGroup: Record<string, number>;
@@ -608,7 +625,6 @@ export interface WorkspaceInspection {
 export interface InspectWorkspaceOptions {
 	dir?: string;
 	group?: null | string;
-	notice?: (message: string) => void;
 	status?: boolean;
 	targetLimit?: number;
 }

package/docs/bug-records.md

@@ -45,10 +45,10 @@ Two overlapping refund requests for one order both pay out.
 ## Reproduce
 
 ```sh
-npx testkit run --file src/checkout/__testkit__/refund.contract.testkit.ts
+npx testkit run --file src/checkout/refund.test.ts
 ```
 
-Test: `src/checkout/__testkit__/refund.contract.testkit.ts`, "a refund pays out once".
+Test: `src/checkout/refund.test.ts`, "a refund pays out once".
 Found at `4f0c2d1e9b7a4c3d8e6f5a4b3c2d1e0f9a8b7c6d`.
 Fault: `src/checkout/refunds.ts`, lines 41 to 58.
 
@@ -66,9 +66,8 @@ Fault: `src/checkout/refunds.ts`, lines 41 to 58.
   "escape": "no-test",
   "caughtBy": "campaign",
   "campaign": "refunds-2026-10",
-  "testType": "contract",
   "test": {
-    "file": "src/checkout/__testkit__/refund.contract.testkit.ts",
+    "file": "src/checkout/refund.test.ts",
     "title": "a refund pays out once"
   },
   "foundAt": "4f0c2d1e9b7a4c3d8e6f5a4b3c2d1e0f9a8b7c6d",
@@ -90,10 +89,6 @@ When `testkit bug file` ran the test against [supplied values](../README.md#run-
 
 A fault on one line reads `line 41`.
 
-```markdown
-Test: `src/health/__testkit__/health.contract.testkit.ts`, the whole script, recorded as "the health endpoint answers".
-```
-
 Testkit redacts the secrets it recognises in the title, in every section, and in `test.title`. It does so when it records the bug and again when it files the issue. `testkit run` applies the same rules when it stores a run result. Testkit recognises these forms.
 
 - The value of a `KEY=value` assignment whose key names a secret.

package/docs/engines.md

@@ -11,18 +11,17 @@ attachments, and installation.
 Each engine keeps its own test language. The root package declares a typed
 file's engine, and each engine's subpath exposes that engine's API.
 
-Node/Vitest runs plain Vitest test files, and data and contract suites:
+Node/Vitest runs plain Vitest test files. A plain file records data-flow
+evidence with `dataFlow(context)`:
 
 ```ts
-import { defineFile } from "@gfdelarue/testkit";
-import { dataScenario } from "@gfdelarue/testkit/node-vitest/data";
-import { expect } from "vitest";
-
-export const testkit = defineFile({ engine: "node-vitest" });
+import { dataFlow } from "@gfdelarue/testkit/node-vitest/data";
+import { expect, test } from "vitest";
 
-dataScenario("records checkout traffic", ({ count, record }) => {
-  record("checkout", { count: 1 });
-  count("orders", 1);
+test("records checkout traffic", (context) => {
+  const flow = dataFlow(context);
+  flow.record("checkout", { count: 1 });
+  flow.count("orders", 1);
   expect(1).toBe(1);
 });
 ```
@@ -41,14 +40,34 @@ test("shows the account", async ({ page }) => {
 });
 ```
 
+### Browser launch options
+
+A UI file can set Playwright's `launchOptions` with `test.use`. Testkit applies
+them and sets `executablePath` last, so the file still runs on the Chromium
+that Testkit manages, and a file's own `executablePath` has no effect. This
+holds whether the file imports `test` from `@playwright/test`,
+`playwright/test`, or `@gfdelarue/testkit/playwright`.
+
+Playwright starts Chromium with `--disable-back-forward-cache`. To check that
+Back restores a page from the back/forward cache, drop that flag in the file:
+
+```ts
+test.use({ launchOptions: { ignoreDefaultArgs: ["--disable-back-forward-cache"] } });
+```
+
 ## Typechecking
 
 `testkit typecheck` groups the discovered test files by engine and by their
 nearest tsconfig, and checks each group with native `tsc --noEmit`. Plain Vitest
 test files written in TypeScript join the Node/Vitest program, and plain
-JavaScript files are skipped. Config and Node/Vitest use Node types and ES2022;
-Playwright adds DOM and DOM.Iterable. Each check has a deadline and can be
-cancelled. When a program fails, the report includes the programs that passed
+JavaScript files are skipped. Every program uses Node types. The config program
+uses ES2022, and Playwright programs use ES2022, DOM, and DOM.Iterable. A
+Node/Vitest program uses the `lib` of the tsconfig it extends, as the
+repository's own `tsc` does, so a test that runs in a jsdom or happy-dom
+environment can use the DOM libraries that tsconfig lists. When that tsconfig
+sets no `lib`, TypeScript's default for ES2022 applies, which includes DOM.
+Without a tsconfig, a Node/Vitest program uses ES2022. Each check has a deadline
+and can be cancelled. When a program fails, the report includes the programs that passed
 before it.
 
 Testkit supports consumer TypeScript 5.9.3 and 6.0.2. Each program uses the
@@ -66,6 +85,21 @@ typecheck in each engine's program. Testkit's generated configs don't set
 Aliases inherited from a config with `baseUrl` keep their target directory and
 fallback order.
 
+A plain file's program also includes the TypeScript setup files of its Vitest
+project, because Vitest loads them before the file and a setup file can declare
+types, such as the matchers that `@testing-library/jest-dom/vitest` adds. Those
+setup files are type-checked too. Files whose projects load different setup
+files go to separate programs, so one project's setup types never reach another
+project's files, and a file that two such projects include is checked in both.
+The label of a program with setup files names them, as in
+`node-vitest with tests/setup.ts`. A JavaScript setup file, or a package named
+directly in `setupFiles`, adds no types. Import the package from a TypeScript
+setup file instead.
+
+`testkit typecheck --group <name>` checks the config and the files that group
+owns, with the setup files of their Vitest projects. An unknown group fails and
+lists the groups.
+
 ### Playwright support files
 
 A Playwright program always includes the discovered UI suites and the nearest
@@ -100,15 +134,15 @@ runtime string or function names. Include those files in the companion.
 The environment declared for a test is part of the test's input. Each engine
 exposes it through its own authoring surface:
 
-- Node/Vitest data and contract callbacks read it from immutable `context.env`.
+- Node/Vitest tests read it from `process.env`, and named values from
+  `@gfdelarue/testkit/environment`.
 - Playwright files read immutable `context.env` from `readPlaywrightContext()`
   when Testkit runs them.
 
-Outside a Testkit run, a Node/Vitest authoring context has an empty `env`, and
-`readPlaywrightContext()` returns `null`.
+Outside a Testkit run, `readPlaywrightContext()` returns `null`.
 
-Typed Node/Vitest files, and plain files under `--vitest-runner managed`, also
-see each value as an immutable, non-enumerable `process.env.KEY` property, so
+Plain files under `--vitest-runner managed` see each value as an immutable,
+non-enumerable `process.env.KEY` property, so
 libraries that read `process.env` see it. `process.env` isn't the enumerable
 list of the test's values, though. A Node child that inherits Testkit's
 bootstrap sees the values too. A non-Node child process receives only the
@@ -116,6 +150,18 @@ values the test passes it. Plain files under the repository's Vitest get the
 values as ordinary environment variables, which tests and child processes can
 read, enumerate, change, and delete like any other.
 
+Vitest and Vite write some keys into each test process's environment
+themselves. Under either runner, a test sees:
+
+- the group's `NODE_ENV`, or `test` when the group sets none
+- the group's `VITE_` values, ahead of the same keys in `.env` files
+- Vitest's own `TEST`, `VITEST`, `VITEST_MODE`, `FORCE_TTY`, `MODE`, `DEV`,
+  `PROD`, and `SSR`, whatever the group sets
+
+Under `--vitest-runner managed`, `NODE_ENV` and `VITE_` values are ordinary
+variables rather than immutable ones, and they count toward the process
+environment limit.
+
 Test files of every engine may import `@gfdelarue/testkit/environment` and read
 named endpoints, databases, and handles with `endpoint(name)`, `database(name)`,
 and `handle(name)`. See