@specific.dev/spectest 0.52.0 → 0.53.0

package/dist/daemon.js

@@ -30,6 +30,7 @@ import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // each easy to restate subtly differently.
 import { buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
+import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
@@ -102,15 +103,13 @@ const CA_BUNDLE_PATH = process.env.SPECTEST_CA_BUNDLE_PATH ?? "/etc/spectest/ca-
 // after generating the CA, so this normally already carries both halves.
 const SYSTEM_CA_BUNDLE = process.env.SPECTEST_SYSTEM_CA_BUNDLE ?? "/etc/ssl/certs/ca-certificates.crt";
 let loaded = null;
+/** The catalogue mapping lives in `harness/catalogue.ts`; these wrappers
+ *  keep the call sites reading off the suite. */
 function casesMetadata(suite) {
-    if (!suite)
-        return [];
-    return suite.tests.map((t) => ({
-        id: t.id,
-        name: t.name,
-        dependsOn: t.dependsOn?.id,
-        timeoutMs: t.timeoutMs,
-    }));
+    return catalogueCases(suite?.tests);
+}
+function groupsMetadata(suite) {
+    return catalogueGroups(suite?.tests);
 }
 // Display-only summary of the project's fakes for the control plane (folded
 // into the env config's `fakes`, surfaced on the run page). Fakes aren't part
@@ -270,11 +269,14 @@ function docker(args, timeoutMs, env) {
  * the full captured output + exit code, so existing error handling and
  * post-hoc parsing (`summarizeBuildKit`) are unchanged.
  */
-function shxStream(file, args, timeoutMs, env, onLine) {
+function shxStream(file, args, timeoutMs, env, onLine, stdin) {
     return new Promise((resolve) => {
         const child = spawn(file, args, {
             env: env ? { ...process.env, ...env } : process.env,
         });
+        if (stdin !== undefined) {
+            child.stdin?.end(stdin);
+        }
         let stdout = "";
         let stderr = "";
         let buf = "";
@@ -416,6 +418,8 @@ async function hasBuildx() {
 // in-VM builder, so a missing/dead buildkitd just means slower builds.
 const REMOTE_BUILDER_ADDR = process.env.SPECTEST_BUILDKIT_ADDR ?? "tcp://10.42.0.1:1234";
 const REMOTE_BUILDER_NAME = "spectest-remote";
+/** Parent of the per-build buildx config dirs (see isolatedBuildxConfig).
+ *  On tmpfs: each holds a builder stub and an 8-byte node id. */
 let _remoteBuilder;
 async function ensureRemoteBuilder() {
     if (_remoteBuilder !== undefined)
@@ -829,16 +833,8 @@ async function prepareServiceImage(svc, opts) {
     }
     return buildServiceImage(svc.name, image, tag);
 }
-/**
- * What the folded CA step prints when it could not write the trust store
- * at all — the one outcome that still needs {@link ensureCaTrustedImage},
- * which can take root for the write.
- *
- * The step assembles this prefix from a shell variable so that the marker
- * appears ONLY in the step's output. BuildKit echoes each instruction into
- * the same log verbatim, so a marker written literally in the RUN would
- * match on every build whether or not the step ever printed it.
- */
+/** Printed by the folded CA step when it could not write the trust
+ *  store at all — the one outcome that still needs the derivative build. */
 const CA_FOLD_UNWRITABLE = "[spectest-ca] trust store not writable";
 /**
  * The CA-trust steps as a suffix appended to a dockerfile service's OWN
@@ -4640,6 +4636,7 @@ function loadedSummary(l) {
     return {
         environment: l.project.environment,
         cases: casesMetadata(l.project.tests),
+        groups: groupsMetadata(l.project.tests),
         fakes: fakesSummary(l.project),
     };
 }
@@ -4703,6 +4700,7 @@ export function harnessMethods(state) {
             return {
                 environment: proj.environment,
                 cases: casesMetadata(proj.tests),
+                groups: groupsMetadata(proj.tests),
                 fakes: fakesSummary(proj),
             };
         },
@@ -4737,7 +4735,10 @@ export function harnessMethods(state) {
             return loadedSummary(requireLoaded());
         },
         envConfig: async () => requireLoaded().project.environment,
-        cases: async () => ({ cases: casesMetadata(requireLoaded().project.tests) }),
+        cases: async () => ({
+            cases: casesMetadata(requireLoaded().project.tests),
+            groups: groupsMetadata(requireLoaded().project.tests),
+        }),
         // Union of platform secret refs the loaded fakes declare (replayFake's
         // `secretRefs`). The control plane resolves these server-side and pushes
         // the values on the eval path only. Empty if nothing's loaded.

package/dist/harness/catalogue.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The test catalogue the control plane reads: one entry per case, plus the
+ * display-only groups.
+ *
+ * Ported out of `daemon.ts`. Three harness methods (`load`, `loadTests`,
+ * `cases`) return this, so the mapping lives in one place.
+ */
+/** The subset of a `TestCase` the catalogue describes. Structural, so the
+ *  mapping needs no import from the SDK entry point. */
+export interface CatalogueCase {
+    id: string;
+    name: string;
+    dependsOn?: {
+        id: string;
+    };
+    timeoutMs?: number;
+    group?: {
+        id: string;
+        name: string;
+        dependsOn?: {
+            id: string;
+        };
+    };
+}
+export interface CaseMeta {
+    id: string;
+    name: string;
+    dependsOn?: string;
+    timeoutMs?: number;
+    /** The group this case is shown in, if any. Display only — a group never
+     *  changes the DAG, which `dependsOn` still describes in full. */
+    groupId?: string;
+}
+/** A display-only test group (`env.group(...)`), for the CLI tree and the
+ *  dashboard. `dependsOn` is the group's own level: every member of the
+ *  group depends on that same case (or on nothing, at the top level). */
+export interface GroupMeta {
+    id: string;
+    name: string;
+    dependsOn?: string;
+}
+export declare function casesMetadata(cases: readonly CatalogueCase[] | undefined): CaseMeta[];
+/**
+ * The groups the suite uses, in the order their first member appears —
+ * which is the order both surfaces render in.
+ *
+ * A group is a value the tests point at, not a registry, so the list is
+ * derived here. Members of one group hold the same group value, and its id
+ * is derived from its name and its parent, so keying by id collapses them
+ * to one entry.
+ */
+export declare function groupsMetadata(cases: readonly CatalogueCase[] | undefined): GroupMeta[];

package/dist/harness/catalogue.js

@@ -0,0 +1,39 @@
+/**
+ * The test catalogue the control plane reads: one entry per case, plus the
+ * display-only groups.
+ *
+ * Ported out of `daemon.ts`. Three harness methods (`load`, `loadTests`,
+ * `cases`) return this, so the mapping lives in one place.
+ */
+export function casesMetadata(cases) {
+    if (!cases)
+        return [];
+    return cases.map((t) => ({
+        id: t.id,
+        name: t.name,
+        dependsOn: t.dependsOn?.id,
+        timeoutMs: t.timeoutMs,
+        groupId: t.group?.id,
+    }));
+}
+/**
+ * The groups the suite uses, in the order their first member appears —
+ * which is the order both surfaces render in.
+ *
+ * A group is a value the tests point at, not a registry, so the list is
+ * derived here. Members of one group hold the same group value, and its id
+ * is derived from its name and its parent, so keying by id collapses them
+ * to one entry.
+ */
+export function groupsMetadata(cases) {
+    if (!cases)
+        return [];
+    const groups = new Map();
+    for (const t of cases) {
+        const g = t.group;
+        if (!g || groups.has(g.id))
+            continue;
+        groups.set(g.id, { id: g.id, name: g.name, dependsOn: g.dependsOn?.id });
+    }
+    return [...groups.values()];
+}

package/dist/index.d.ts

@@ -868,13 +868,69 @@ export interface TestCase<T = unknown, S extends ServicesMap = ServicesMap, F ex
     readonly name: string;
     /** Parent test, if any. Single-parent for now. */
     readonly dependsOn?: TestCase<unknown, S, F>;
+    /** The group this test is shown in, if any — set by the `group`
+     *  option, which also supplies `dependsOn`. Display only: a group
+     *  never changes how the suite runs. See {@link TestGroup}. */
+    readonly group?: TestGroup<unknown, S, F>;
     /** Override the default per-test timeout (default 60s). */
     readonly timeoutMs?: number;
     /** @internal — the body that the in-sandbox daemon invokes. */
     readonly run: TestFn<T, unknown, S, F>;
 }
+/**
+ * A named group of sibling tests, created by `env.group(...)`. A group is
+ * purely informative — the CLI and the dashboard show its name above the
+ * tests in it, and nothing about the run changes.
+ *
+ * A group holds tests at ONE level of the tree: every member shares the
+ * group's own parent. That is why a member declares `group` INSTEAD OF
+ * `dependsOn` — the group supplies the parent, so a group can never span
+ * two levels. The descendants of a member are shown inside the group as
+ * well, but they declare only their own parent, as they always did.
+ *
+ * `P` is the return type of the parent test, so a member's `ctx.parent`
+ * is typed exactly as if it had named `dependsOn` itself.
+ *
+ * ```ts
+ * export const billing = env.group("Billing");                 // top level
+ * export const createInvoice = env.test("create invoice", { group: billing }, fn);
+ * // A child. It is shown inside "Billing" already, so it names its parent.
+ * export const refund = env.test("refund", { dependsOn: createInvoice }, fn);
+ * // Groups nest through tests: this one sits under createInvoice.
+ * export const errors = env.group("Invoice errors", { dependsOn: createInvoice });
+ * ```
+ */
+export interface TestGroup<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    /** Stable id — `<parent-case-id>/<slug of name>`, or the bare slug at
+     *  top level. Derived from the name and the parent, never minted, so it
+     *  is the same in every run: the dashboard and the run diff key on it.
+     *  Qualifying by the parent is what lets the same name appear in
+     *  different parts of the tree. */
+    readonly id: string;
+    readonly name: string;
+    /** The parent test every member of this group depends on. `undefined`
+     *  for a top-level group. */
+    readonly dependsOn?: TestCase<P, S, F>;
+}
+/** Options for {@link DefinedEnvironment.group}. */
+export interface GroupOpts<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    /** The parent every member of the group depends on. Omit it for a
+     *  top-level group. */
+    dependsOn?: TestCase<P, S, F>;
+}
+/** Test options that name the parent directly. `group` is `never` here,
+ *  so giving both options is a compile error rather than a rule the
+ *  suite has to check at load time. */
 export interface TestOpts<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
     dependsOn?: TestCase<P, S, F>;
+    group?: never;
+    timeoutMs?: number;
+}
+/** Test options that name a group. The group supplies the parent, so
+ *  `dependsOn` is `never` here — see {@link TestOpts}. */
+export interface GroupedTestOpts<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    group: TestGroup<P, S, F>;
+    dependsOn?: never;
     timeoutMs?: number;
 }
 export type TestFn<T = void, P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> = (ctx: TestContext<P, S, F>) => T | Promise<T>;
@@ -1226,6 +1282,7 @@ export type FakeHandlesFor<F extends FakesMap> = string extends keyof F ? Record
 export interface TypedTest<S extends ServicesMap, F extends FakesMap = FakesMap> {
     <T = void>(name: string, fn: TestFn<T, undefined, S, F>): TestCase<T, S, F>;
     <T = void, P = undefined>(name: string, opts: TestOpts<P, S, F>, fn: TestFn<T, P, S, F>): TestCase<T, S, F>;
+    <T = void, P = undefined>(name: string, opts: GroupedTestOpts<P, S, F>, fn: TestFn<T, P, S, F>): TestCase<T, S, F>;
 }
 /**
  * A complete project definition: an environment, an optional one-shot
@@ -1341,6 +1398,21 @@ export interface DefinedEnvironment<S extends ServicesMap, F extends FakesMap =
      * `ctx.fakes.<key>` are strongly typed against the services and fakes
      * maps. */
     readonly test: TypedTest<S, F>;
+    /**
+     * Declare a group of sibling tests, for display only. Pass the group to
+     * a test's `group` option instead of `dependsOn` — the group carries the
+     * parent, so every member sits at one level of the tree.
+     *
+     * ```ts
+     * export const billing = env.group("Billing");
+     * export const errors = env.group("Errors", { dependsOn: createInvoice });
+     * ```
+     *
+     * Two groups with the same name AND the same parent are an error:
+     * export one group value and import it where you need it. The same name
+     * under a different parent is fine.
+     */
+    group<P = undefined>(name: string, opts?: GroupOpts<P, S, F>): TestGroup<P, S, F>;
     /** Bundle this environment with a test suite into the project default
      * export. Pass tests as a plain array for the common case, or an
      * options bag to attach project-level `setup`. (Fakes are declared on

package/dist/index.js

@@ -337,6 +337,27 @@ export function defineEnvironment(input) {
         registry.push(tc);
         return tc;
     });
+    // Group ids are derived (`<parent-case-id>/<slug>`), never minted, so a
+    // group keeps its id across runs — the dashboard and the run diff key on
+    // it. Qualifying by the parent is what lets the same name be used in
+    // different parts of the tree; only two groups under the SAME parent
+    // collide, and that is the one case we refuse. Checking at creation time
+    // (rather than in `validateSuite`) puts the error at the `env.group` call
+    // that is wrong, and catches a group that no test has joined yet.
+    const groupIds = new Set();
+    const group = (name, opts) => {
+        const parent = opts?.dependsOn;
+        const slug = slugify(name, "group");
+        const id = parent ? `${parent.id}/${slug}` : slug;
+        if (groupIds.has(id)) {
+            throw new Error(`group ${JSON.stringify(name)} is declared twice${parent ? ` under "${parent.name}"` : " at the top level"} — export one group value and import it in both places`);
+        }
+        groupIds.add(id);
+        const g = parent
+            ? { id, name, dependsOn: parent }
+            : { id, name };
+        return g;
+    };
     function project(arg) {
         const opts = Array.isArray(arg)
             ? { tests: arg }
@@ -371,6 +392,7 @@ export function defineEnvironment(input) {
     return {
         config,
         test,
+        group,
         project,
     };
 }
@@ -430,7 +452,12 @@ maybeFn) {
     return {
         id: slugify(name),
         name,
-        dependsOn: opts.dependsOn,
+        // `group` and `dependsOn` are mutually exclusive in the types, so at
+        // most one of these is set. A grouped test takes the group's parent —
+        // which is what keeps a group to one level of the tree, with no rule
+        // for the suite to check.
+        dependsOn: opts.dependsOn ?? opts.group?.dependsOn,
+        group: opts.group,
         timeoutMs: opts.timeoutMs,
         run: fn,
     };
@@ -453,13 +480,13 @@ function validateSuite(suite) {
     }
     return suite;
 }
-function slugify(name) {
+function slugify(name, kind = "test") {
     const slug = name
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
     if (!slug) {
-        throw new Error(`cannot derive id from test name ${JSON.stringify(name)}`);
+        throw new Error(`cannot derive id from ${kind} name ${JSON.stringify(name)}`);
     }
     return slug;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -50,6 +50,12 @@ import {
   unionDockerignore,
 } from "./harness/build-context.js";
 import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
+import {
+  casesMetadata as catalogueCases,
+  groupsMetadata as catalogueGroups,
+  type CaseMeta,
+  type GroupMeta,
+} from "./harness/catalogue.js";
 import { summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import {
@@ -137,6 +143,7 @@ import {
 import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
 import type { Wrapped, WrappedResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
+import { generateId } from "./ids.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 
 import type {
@@ -247,21 +254,14 @@ interface Loaded {
 
 let loaded: Loaded | null = null;
 
-interface CaseMeta {
-  id: string;
-  name: string;
-  dependsOn?: string;
-  timeoutMs?: number;
+/** The catalogue mapping lives in `harness/catalogue.ts`; these wrappers
+ *  keep the call sites reading off the suite. */
+function casesMetadata(suite: TestSuite | undefined): CaseMeta[] {
+  return catalogueCases(suite?.tests);
 }
 
-function casesMetadata(suite: TestSuite | undefined): CaseMeta[] {
-  if (!suite) return [];
-  return suite.tests.map((t) => ({
-    id: t.id,
-    name: t.name,
-    dependsOn: t.dependsOn?.id,
-    timeoutMs: t.timeoutMs,
-  }));
+function groupsMetadata(suite: TestSuite | undefined): GroupMeta[] {
+  return catalogueGroups(suite?.tests);
 }
 
 interface FakeMeta {
@@ -468,11 +468,15 @@ function shxStream(
   timeoutMs: number | undefined,
   env: Record<string, string> | undefined,
   onLine: (line: string) => void,
+  stdin?: string,
 ): Promise<CmdResult> {
   return new Promise((resolve) => {
     const child = spawn(file, args, {
       env: env ? { ...process.env, ...env } : process.env,
     });
+    if (stdin !== undefined) {
+      child.stdin?.end(stdin);
+    }
     let stdout = "";
     let stderr = "";
     let buf = "";
@@ -649,6 +653,8 @@ async function hasBuildx(): Promise<boolean> {
 // in-VM builder, so a missing/dead buildkitd just means slower builds.
 const REMOTE_BUILDER_ADDR = process.env.SPECTEST_BUILDKIT_ADDR ?? "tcp://10.42.0.1:1234";
 const REMOTE_BUILDER_NAME = "spectest-remote";
+/** Parent of the per-build buildx config dirs (see isolatedBuildxConfig).
+ *  On tmpfs: each holds a builder stub and an 8-byte node id. */
 let _remoteBuilder: boolean | undefined;
 async function ensureRemoteBuilder(): Promise<boolean> {
   if (_remoteBuilder !== undefined) return _remoteBuilder;
@@ -1116,16 +1122,8 @@ async function prepareServiceImage(
   return buildServiceImage(svc.name, image, tag);
 }
 
-/**
- * What the folded CA step prints when it could not write the trust store
- * at all — the one outcome that still needs {@link ensureCaTrustedImage},
- * which can take root for the write.
- *
- * The step assembles this prefix from a shell variable so that the marker
- * appears ONLY in the step's output. BuildKit echoes each instruction into
- * the same log verbatim, so a marker written literally in the RUN would
- * match on every build whether or not the step ever printed it.
- */
+/** Printed by the folded CA step when it could not write the trust
+ *  store at all — the one outcome that still needs the derivative build. */
 const CA_FOLD_UNWRITABLE = "[spectest-ca] trust store not writable";
 
 /**
@@ -1302,13 +1300,13 @@ async function runServiceBuild(
         });
         return;
       }
-      m = line.match(/^Step (\d+\/\d+)\s*:\s*(.+)$/);
-      if (m) {
-        progressService(name, {
-          status: "building",
-          detail: `step ${m[1]} ${m[2].trim().slice(0, 60)}`,
-        });
-      }
+        m = line.match(/^Step (\d+\/\d+)\s*:\s*(.+)$/);
+        if (m) {
+          progressService(name, {
+            status: "building",
+            detail: `step ${m[1]} ${m[2].trim().slice(0, 60)}`,
+          });
+        }
     });
     const log = `${build.stderr.trim()}\n${build.stdout.trim()}`;
     if (build.code !== 0) {
@@ -5651,6 +5649,7 @@ function loadedSummary(l: ReturnType<typeof requireLoaded>) {
   return {
     environment: l.project.environment,
     cases: casesMetadata(l.project.tests),
+    groups: groupsMetadata(l.project.tests),
     fakes: fakesSummary(l.project),
   };
 }
@@ -5719,6 +5718,7 @@ export function harnessMethods(state: RouteState): MethodTable {
       return {
         environment: proj.environment,
         cases: casesMetadata(proj.tests),
+        groups: groupsMetadata(proj.tests),
         fakes: fakesSummary(proj),
       };
     },
@@ -5758,7 +5758,10 @@ export function harnessMethods(state: RouteState): MethodTable {
 
     envConfig: async () => requireLoaded().project.environment,
 
-    cases: async () => ({ cases: casesMetadata(requireLoaded().project.tests) }),
+    cases: async () => ({
+      cases: casesMetadata(requireLoaded().project.tests),
+      groups: groupsMetadata(requireLoaded().project.tests),
+    }),
 
     // Union of platform secret refs the loaded fakes declare (replayFake's
     // `secretRefs`). The control plane resolves these server-side and pushes

package/src/groups.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+
+import { defineEnvironment } from "./index";
+
+const newEnv = () =>
+  defineEnvironment({
+    name: "groups",
+    services: { web: { image: { type: "registry", reference: "nginx" } } },
+  });
+
+describe("env.group", () => {
+  test("a member takes the group's parent, so a group is one level", () => {
+    const env = newEnv();
+    const parent = env.test("create invoice", async () => ({ id: 7 }));
+    const errors = env.group("Errors", { dependsOn: parent });
+    const member = env.test("refund too much", { group: errors }, async () => {});
+
+    expect(member.dependsOn).toBe(parent);
+    expect(member.group).toBe(errors);
+  });
+
+  test("a top-level group leaves its members roots", () => {
+    const env = newEnv();
+    const billing = env.group("Billing");
+    const member = env.test("create invoice", { group: billing }, async () => {});
+
+    expect(member.dependsOn).toBeUndefined();
+    expect(member.group!.id).toBe("billing");
+  });
+
+  test("the id is qualified by the parent, so a name can repeat elsewhere", () => {
+    const env = newEnv();
+    const a = env.test("create invoice", async () => {});
+    const b = env.test("refund", { dependsOn: a }, async () => {});
+
+    expect(env.group("Errors", { dependsOn: a }).id).toBe("create-invoice/errors");
+    expect(env.group("Errors", { dependsOn: b }).id).toBe("refund/errors");
+    expect(env.group("Errors").id).toBe("errors");
+  });
+
+  test("two groups with the same name and parent are refused", () => {
+    const env = newEnv();
+    const parent = env.test("create invoice", async () => {});
+    env.group("Errors", { dependsOn: parent });
+
+    expect(() => env.group("Errors", { dependsOn: parent })).toThrow(
+      /"Errors" is declared twice under "create invoice"/,
+    );
+  });
+
+  test("two top-level groups with the same name are refused", () => {
+    const env = newEnv();
+    env.group("Billing");
+    expect(() => env.group("Billing")).toThrow(/twice at the top level/);
+  });
+
+  test("a grouped test still validates its parent is in the suite", () => {
+    const env = newEnv();
+    const parent = env.test("create invoice", async () => {});
+    const errors = env.group("Errors", { dependsOn: parent });
+    const member = env.test("refund too much", { group: errors }, async () => {});
+
+    expect(() => env.project({ tests: [member] }).tests).toThrow(
+      /depends on "create invoice" which is not in the suite/,
+    );
+    expect(env.project({ tests: [parent, member] }).tests!.tests).toHaveLength(2);
+  });
+});

package/src/harness/catalogue.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+
+import { casesMetadata, groupsMetadata, type CatalogueCase } from "./catalogue";
+
+const billing = { id: "billing", name: "Billing" };
+const errors = {
+  id: "create-invoice/errors",
+  name: "Errors",
+  dependsOn: { id: "create-invoice" },
+};
+
+const cases: CatalogueCase[] = [
+  { id: "create-invoice", name: "create invoice", group: billing },
+  { id: "list-invoices", name: "list invoices", group: billing },
+  { id: "refund", name: "refund", dependsOn: { id: "create-invoice" } },
+  {
+    id: "refund-too-much",
+    name: "refund too much",
+    dependsOn: { id: "create-invoice" },
+    group: errors,
+    timeoutMs: 1000,
+  },
+];
+
+describe("casesMetadata", () => {
+  test("flattens the case refs to ids", () => {
+    expect(casesMetadata(cases)[3]).toEqual({
+      id: "refund-too-much",
+      name: "refund too much",
+      dependsOn: "create-invoice",
+      timeoutMs: 1000,
+      groupId: "create-invoice/errors",
+    });
+  });
+
+  test("a case in no group carries no group id", () => {
+    expect(casesMetadata(cases)[2]!.groupId).toBeUndefined();
+  });
+
+  test("no suite is an empty catalogue", () => {
+    expect(casesMetadata(undefined)).toEqual([]);
+  });
+});
+
+describe("groupsMetadata", () => {
+  test("one entry per group, where its first member appears", () => {
+    expect(groupsMetadata(cases)).toEqual([
+      { id: "billing", name: "Billing", dependsOn: undefined },
+      {
+        id: "create-invoice/errors",
+        name: "Errors",
+        dependsOn: "create-invoice",
+      },
+    ]);
+  });
+
+  test("a suite with no groups has none", () => {
+    expect(groupsMetadata([{ id: "a", name: "a" }])).toEqual([]);
+    expect(groupsMetadata(undefined)).toEqual([]);
+  });
+});

package/src/harness/catalogue.ts

@@ -0,0 +1,67 @@
+/**
+ * The test catalogue the control plane reads: one entry per case, plus the
+ * display-only groups.
+ *
+ * Ported out of `daemon.ts`. Three harness methods (`load`, `loadTests`,
+ * `cases`) return this, so the mapping lives in one place.
+ */
+
+/** The subset of a `TestCase` the catalogue describes. Structural, so the
+ *  mapping needs no import from the SDK entry point. */
+export interface CatalogueCase {
+  id: string;
+  name: string;
+  dependsOn?: { id: string };
+  timeoutMs?: number;
+  group?: { id: string; name: string; dependsOn?: { id: string } };
+}
+
+export interface CaseMeta {
+  id: string;
+  name: string;
+  dependsOn?: string;
+  timeoutMs?: number;
+  /** The group this case is shown in, if any. Display only — a group never
+   *  changes the DAG, which `dependsOn` still describes in full. */
+  groupId?: string;
+}
+
+/** A display-only test group (`env.group(...)`), for the CLI tree and the
+ *  dashboard. `dependsOn` is the group's own level: every member of the
+ *  group depends on that same case (or on nothing, at the top level). */
+export interface GroupMeta {
+  id: string;
+  name: string;
+  dependsOn?: string;
+}
+
+export function casesMetadata(cases: readonly CatalogueCase[] | undefined): CaseMeta[] {
+  if (!cases) return [];
+  return cases.map((t) => ({
+    id: t.id,
+    name: t.name,
+    dependsOn: t.dependsOn?.id,
+    timeoutMs: t.timeoutMs,
+    groupId: t.group?.id,
+  }));
+}
+
+/**
+ * The groups the suite uses, in the order their first member appears —
+ * which is the order both surfaces render in.
+ *
+ * A group is a value the tests point at, not a registry, so the list is
+ * derived here. Members of one group hold the same group value, and its id
+ * is derived from its name and its parent, so keying by id collapses them
+ * to one entry.
+ */
+export function groupsMetadata(cases: readonly CatalogueCase[] | undefined): GroupMeta[] {
+  if (!cases) return [];
+  const groups = new Map<string, GroupMeta>();
+  for (const t of cases) {
+    const g = t.group;
+    if (!g || groups.has(g.id)) continue;
+    groups.set(g.id, { id: g.id, name: g.name, dependsOn: g.dependsOn?.id });
+  }
+  return [...groups.values()];
+}

package/src/index.ts

@@ -1330,18 +1330,89 @@ export interface TestCase<
   readonly name: string;
   /** Parent test, if any. Single-parent for now. */
   readonly dependsOn?: TestCase<unknown, S, F>;
+  /** The group this test is shown in, if any — set by the `group`
+   *  option, which also supplies `dependsOn`. Display only: a group
+   *  never changes how the suite runs. See {@link TestGroup}. */
+  readonly group?: TestGroup<unknown, S, F>;
   /** Override the default per-test timeout (default 60s). */
   readonly timeoutMs?: number;
   /** @internal — the body that the in-sandbox daemon invokes. */
   readonly run: TestFn<T, unknown, S, F>;
 }
 
+/**
+ * A named group of sibling tests, created by `env.group(...)`. A group is
+ * purely informative — the CLI and the dashboard show its name above the
+ * tests in it, and nothing about the run changes.
+ *
+ * A group holds tests at ONE level of the tree: every member shares the
+ * group's own parent. That is why a member declares `group` INSTEAD OF
+ * `dependsOn` — the group supplies the parent, so a group can never span
+ * two levels. The descendants of a member are shown inside the group as
+ * well, but they declare only their own parent, as they always did.
+ *
+ * `P` is the return type of the parent test, so a member's `ctx.parent`
+ * is typed exactly as if it had named `dependsOn` itself.
+ *
+ * ```ts
+ * export const billing = env.group("Billing");                 // top level
+ * export const createInvoice = env.test("create invoice", { group: billing }, fn);
+ * // A child. It is shown inside "Billing" already, so it names its parent.
+ * export const refund = env.test("refund", { dependsOn: createInvoice }, fn);
+ * // Groups nest through tests: this one sits under createInvoice.
+ * export const errors = env.group("Invoice errors", { dependsOn: createInvoice });
+ * ```
+ */
+export interface TestGroup<
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  /** Stable id — `<parent-case-id>/<slug of name>`, or the bare slug at
+   *  top level. Derived from the name and the parent, never minted, so it
+   *  is the same in every run: the dashboard and the run diff key on it.
+   *  Qualifying by the parent is what lets the same name appear in
+   *  different parts of the tree. */
+  readonly id: string;
+  readonly name: string;
+  /** The parent test every member of this group depends on. `undefined`
+   *  for a top-level group. */
+  readonly dependsOn?: TestCase<P, S, F>;
+}
+
+/** Options for {@link DefinedEnvironment.group}. */
+export interface GroupOpts<
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  /** The parent every member of the group depends on. Omit it for a
+   *  top-level group. */
+  dependsOn?: TestCase<P, S, F>;
+}
+
+/** Test options that name the parent directly. `group` is `never` here,
+ *  so giving both options is a compile error rather than a rule the
+ *  suite has to check at load time. */
 export interface TestOpts<
   P = undefined,
   S extends ServicesMap = ServicesMap,
   F extends FakesMap = FakesMap,
 > {
   dependsOn?: TestCase<P, S, F>;
+  group?: never;
+  timeoutMs?: number;
+}
+
+/** Test options that name a group. The group supplies the parent, so
+ *  `dependsOn` is `never` here — see {@link TestOpts}. */
+export interface GroupedTestOpts<
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  group: TestGroup<P, S, F>;
+  dependsOn?: never;
   timeoutMs?: number;
 }
 
@@ -1772,6 +1843,11 @@ export interface TypedTest<
     opts: TestOpts<P, S, F>,
     fn: TestFn<T, P, S, F>,
   ): TestCase<T, S, F>;
+  <T = void, P = undefined>(
+    name: string,
+    opts: GroupedTestOpts<P, S, F>,
+    fn: TestFn<T, P, S, F>,
+  ): TestCase<T, S, F>;
 }
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -1914,6 +1990,24 @@ export interface DefinedEnvironment<
    * `ctx.fakes.<key>` are strongly typed against the services and fakes
    * maps. */
   readonly test: TypedTest<S, F>;
+  /**
+   * Declare a group of sibling tests, for display only. Pass the group to
+   * a test's `group` option instead of `dependsOn` — the group carries the
+   * parent, so every member sits at one level of the tree.
+   *
+   * ```ts
+   * export const billing = env.group("Billing");
+   * export const errors = env.group("Errors", { dependsOn: createInvoice });
+   * ```
+   *
+   * Two groups with the same name AND the same parent are an error:
+   * export one group value and import it where you need it. The same name
+   * under a different parent is fine.
+   */
+  group<P = undefined>(
+    name: string,
+    opts?: GroupOpts<P, S, F>,
+  ): TestGroup<P, S, F>;
   /** Bundle this environment with a test suite into the project default
    * export. Pass tests as a plain array for the common case, or an
    * options bag to attach project-level `setup`. (Fakes are declared on
@@ -2023,6 +2117,35 @@ export function defineEnvironment<
     return tc;
   }) as unknown as TypedTest<S, F>;
 
+  // Group ids are derived (`<parent-case-id>/<slug>`), never minted, so a
+  // group keeps its id across runs — the dashboard and the run diff key on
+  // it. Qualifying by the parent is what lets the same name be used in
+  // different parts of the tree; only two groups under the SAME parent
+  // collide, and that is the one case we refuse. Checking at creation time
+  // (rather than in `validateSuite`) puts the error at the `env.group` call
+  // that is wrong, and catches a group that no test has joined yet.
+  const groupIds = new Set<string>();
+  const group = <P = undefined>(
+    name: string,
+    opts?: GroupOpts<P, S, F>,
+  ): TestGroup<P, S, F> => {
+    const parent = opts?.dependsOn;
+    const slug = slugify(name, "group");
+    const id = parent ? `${parent.id}/${slug}` : slug;
+    if (groupIds.has(id)) {
+      throw new Error(
+        `group ${JSON.stringify(name)} is declared twice${
+          parent ? ` under "${parent.name}"` : " at the top level"
+        } — export one group value and import it in both places`,
+      );
+    }
+    groupIds.add(id);
+    const g: TestGroup<P, S, F> = parent
+      ? { id, name, dependsOn: parent }
+      : { id, name };
+    return g;
+  };
+
   function project(
     arg?: TestCase<unknown, S, F>[] | ProjectOpts<S, F>,
   ): Project<S, F> {
@@ -2056,6 +2179,7 @@ export function defineEnvironment<
   return {
     config,
     test,
+    group,
     project,
   };
 }
@@ -2113,12 +2237,12 @@ function validateFakes(env: EnvironmentConfig, fakes: FakesMap): void {
 function buildTestCase(
   name: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  optsOrFn: TestOpts<any> | TestFn<unknown, any>,
+  optsOrFn: AnyTestOpts | TestFn<unknown, any>,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   maybeFn?: TestFn<unknown, any>,
 ): TestCase<unknown> {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const [opts, fn]: [TestOpts<any>, TestFn<unknown, any>] =
+  const [opts, fn]: [AnyTestOpts, TestFn<unknown, any>] =
     typeof optsOrFn === "function" ? [{}, optsOrFn] : [optsOrFn, maybeFn!];
   if (typeof fn !== "function") {
     throw new TypeError(
@@ -2128,12 +2252,27 @@ function buildTestCase(
   return {
     id: slugify(name),
     name,
-    dependsOn: opts.dependsOn,
+    // `group` and `dependsOn` are mutually exclusive in the types, so at
+    // most one of these is set. A grouped test takes the group's parent —
+    // which is what keeps a group to one level of the tree, with no rule
+    // for the suite to check.
+    dependsOn: opts.dependsOn ?? opts.group?.dependsOn,
+    group: opts.group,
     timeoutMs: opts.timeoutMs,
     run: fn,
   };
 }
 
+/** The two option shapes as one, for the untyped runtime implementation.
+ *  The public overloads keep them apart — see {@link TestOpts}. */
+interface AnyTestOpts {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  dependsOn?: TestCase<any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  group?: TestGroup<any>;
+  timeoutMs?: number;
+}
+
 function validateSuite<
   S extends ServicesMap,
   F extends FakesMap,
@@ -2162,13 +2301,15 @@ function validateSuite<
   return suite;
 }
 
-function slugify(name: string): string {
+function slugify(name: string, kind: "test" | "group" = "test"): string {
   const slug = name
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
   if (!slug) {
-    throw new Error(`cannot derive id from test name ${JSON.stringify(name)}`);
+    throw new Error(
+      `cannot derive id from ${kind} name ${JSON.stringify(name)}`,
+    );
   }
   return slug;
 }