@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 160 lines 5.45 KB
Raw
1 /**
2 * Core data model for the alchemy-test harness.
3 *
4 * A test file is collected into a tree of {@link Suite}s and {@link TestCase}s
5 * by evaluating its module body (describe/test calls register nodes). The
6 * runner then walks the tree and executes every test as an Effect.
7 */
8 import type * as Effect from "effect/Effect";
9 import { mergeTags, type Tags } from "./Tags.ts";
10
11 /** Execution mode attached to a suite or test at registration time. */
12 export type Mode = "run" | "skip" | "only" | "todo";
13
14 /** A single log line captured from a test's Effect Logger or Console. */
15 export interface LogEntry {
16 readonly level: string;
17 readonly message: string;
18 readonly time: Date;
19 }
20
21 /**
22 * The body of a test. Always an Effect — plain-function tests are wrapped
23 * at registration time. The Effect must be self-contained (R = never);
24 * wrapping (scope, TestClock/TestConsole, shared layers) happens in the
25 * harness closures, NOT in the runner.
26 */
27 export type TestBody = () => Effect.Effect<unknown, unknown, never>;
28
29 /** A hook body. Same contract as {@link TestBody}. */
30 export type HookBody = () => Effect.Effect<unknown, unknown, never>;
31
32 /** `true` for the whole-process lock, or a label naming a narrower lock. */
33 export type Exclusive = boolean | string;
34
35 export interface Hook {
36 readonly body: HookBody;
37 readonly timeout?: number | undefined;
38 /**
39 * `true` takes the whole-process write lock for this hook. A label (e.g.
40 * `"hetzner"`) only serializes the hook with tests and hooks holding the
41 * same label — use it for deploys that consume a scarce cloud quota.
42 */
43 readonly exclusive?: Exclusive;
44 }
45
46 export interface TestCase {
47 /** Deduplicated labels, including tags inherited from suites. */
48 readonly tags: ReadonlyArray<string>;
49 /** Inherited tags requiring explicit selection. */
50 readonly optInTags: ReadonlyArray<string>;
51 readonly type: "test";
52 readonly name: string;
53 readonly mode: Mode;
54 /** Invert the result: the test passes only if the body fails. */
55 readonly fails?: boolean;
56 /**
57 * `true` runs this test with the whole-process write lock: no other test
58 * in the run executes concurrently with it. Required for tests that mutate
59 * process-global state (e.g. `process.env.PATH`) — the runner executes
60 * everything in ONE bun process, so such mutations are visible everywhere.
61 *
62 * A label (e.g. `"hetzner"`) only serializes the test with others holding
63 * the same label — use it for a shared cloud quota, not global state.
64 */
65 readonly exclusive?: Exclusive;
66 /** Override the run-wide retry budget for this test. */
67 readonly retry?: number | undefined;
68 readonly timeout?: number | undefined;
69 readonly body: TestBody | undefined;
70 readonly parent: Suite;
71 }
72
73 export interface Suite {
74 /** Deduplicated labels, including tags inherited from parent suites. */
75 readonly tags: ReadonlyArray<string>;
76 /** Inherited tags requiring explicit selection. */
77 readonly optInTags: ReadonlyArray<string>;
78 readonly type: "suite";
79 readonly name: string;
80 mode: Mode;
81 /** When true, children run one at a time (the default; describe.concurrent opts out). */
82 sequential: boolean;
83 readonly children: Array<Suite | TestCase>;
84 readonly beforeAll: Array<Hook>;
85 readonly afterAll: Array<Hook>;
86 readonly beforeEach: Array<Hook>;
87 readonly afterEach: Array<Hook>;
88 readonly parent: Suite | undefined;
89 }
90
91 /** The root suite of a single test file. */
92 export interface FileSuite extends Suite {
93 /** Path relative to the run root, e.g. `test/Cloudflare/R2/Bucket.test.ts`. */
94 readonly file: string;
95 /** Framework resources, disposed even when user hooks are skipped. */
96 readonly cleanups: Array<Hook>;
97 }
98
99 export const makeSuite = (
100 name: string,
101 parent: Suite | undefined,
102 mode: Mode = "run",
103 tags?: Tags,
104 optInTags?: Tags,
105 ): Suite => ({
106 tags: mergeTags(parent?.tags ?? [], tags),
107 optInTags: mergeTags(parent?.optInTags ?? [], optInTags),
108 type: "suite",
109 name,
110 mode,
111 sequential: true,
112 children: [],
113 beforeAll: [],
114 afterAll: [],
115 beforeEach: [],
116 afterEach: [],
117 parent,
118 });
119
120 export const makeFileSuite = (file: string): FileSuite => ({
121 ...makeSuite(file, undefined),
122 file,
123 cleanups: [],
124 });
125
126 /** Full title path from the file root down to (and including) this node. */
127 export const titlePath = (node: Suite | TestCase): ReadonlyArray<string> => {
128 const parts: Array<string> = [];
129 let current: Suite | TestCase | undefined = node;
130 while (current !== undefined) {
131 // Skip the file-root suite name (it's reported separately as `file`).
132 if (current.parent !== undefined || current.type === "test") {
133 parts.unshift(current.name);
134 } else if (current.parent === undefined && current.type === "suite") {
135 // file root — stop
136 }
137 current = current.parent;
138 }
139 return parts;
140 };
141
142 export const fullTitle = (node: Suite | TestCase): string => titlePath(node).join(" > ");
143
144 /** Walk every test in a suite subtree (depth-first, registration order). */
145 export const forEachTest = (suite: Suite, f: (test: TestCase) => void): void => {
146 for (const child of suite.children) {
147 if (child.type === "test") f(child);
148 else forEachTest(child, f);
149 }
150 };
151
152 /** True if the subtree contains a node marked `only`. */
153 export const containsOnly = (suite: Suite): boolean => {
154 if (suite.mode === "only") return true;
155 for (const child of suite.children) {
156 if (child.type === "test" && child.mode === "only") return true;
157 if (child.type === "suite" && containsOnly(child)) return true;
158 }
159 return false;
160 };