@c9up/helix 0.1.8 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/README.md +274 -5
  2. package/bin/helix.js +312 -13
  3. package/dist/cli/failed-cache.d.ts +27 -0
  4. package/dist/cli/failed-cache.d.ts.map +1 -0
  5. package/dist/cli/failed-cache.js +64 -0
  6. package/dist/cli/failed-cache.js.map +1 -0
  7. package/dist/cli/glob.d.ts +36 -0
  8. package/dist/cli/glob.d.ts.map +1 -0
  9. package/dist/cli/glob.js +185 -0
  10. package/dist/cli/glob.js.map +1 -0
  11. package/dist/cli/native.d.ts +4 -0
  12. package/dist/cli/native.d.ts.map +1 -1
  13. package/dist/cli/native.js.map +1 -1
  14. package/dist/cli/pool.d.ts +11 -0
  15. package/dist/cli/pool.d.ts.map +1 -1
  16. package/dist/cli/pool.js +12 -0
  17. package/dist/cli/pool.js.map +1 -1
  18. package/dist/cli/reporter.d.ts +11 -0
  19. package/dist/cli/reporter.d.ts.map +1 -1
  20. package/dist/cli/reporter.js +53 -0
  21. package/dist/cli/reporter.js.map +1 -1
  22. package/dist/cli/run.d.ts +41 -0
  23. package/dist/cli/run.d.ts.map +1 -1
  24. package/dist/cli/run.js +181 -21
  25. package/dist/cli/run.js.map +1 -1
  26. package/dist/cli/runner.d.ts +19 -0
  27. package/dist/cli/runner.d.ts.map +1 -0
  28. package/dist/cli/runner.js +15 -0
  29. package/dist/cli/runner.js.map +1 -0
  30. package/dist/cli/suites.d.ts +102 -0
  31. package/dist/cli/suites.d.ts.map +1 -0
  32. package/dist/cli/suites.js +226 -0
  33. package/dist/cli/suites.js.map +1 -0
  34. package/dist/index.d.ts +10 -9
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +9 -8
  37. package/dist/index.js.map +1 -1
  38. package/dist/japa/core.d.ts +106 -0
  39. package/dist/japa/core.d.ts.map +1 -0
  40. package/dist/japa/core.js +128 -0
  41. package/dist/japa/core.js.map +1 -0
  42. package/dist/runtime/assert.d.ts +174 -0
  43. package/dist/runtime/assert.d.ts.map +1 -0
  44. package/dist/runtime/assert.js +591 -0
  45. package/dist/runtime/assert.js.map +1 -0
  46. package/dist/runtime/bootstrap.d.ts +47 -0
  47. package/dist/runtime/bootstrap.d.ts.map +1 -0
  48. package/dist/runtime/bootstrap.js +166 -0
  49. package/dist/runtime/bootstrap.js.map +1 -0
  50. package/dist/runtime/cli-args.d.ts +77 -0
  51. package/dist/runtime/cli-args.d.ts.map +1 -0
  52. package/dist/runtime/cli-args.js +85 -0
  53. package/dist/runtime/cli-args.js.map +1 -0
  54. package/dist/runtime/configure.d.ts +214 -0
  55. package/dist/runtime/configure.d.ts.map +1 -0
  56. package/dist/runtime/configure.js +164 -0
  57. package/dist/runtime/configure.js.map +1 -0
  58. package/dist/runtime/context.d.ts +84 -0
  59. package/dist/runtime/context.d.ts.map +1 -0
  60. package/dist/runtime/context.js +146 -0
  61. package/dist/runtime/context.js.map +1 -0
  62. package/dist/runtime/emitter.d.ts +141 -0
  63. package/dist/runtime/emitter.d.ts.map +1 -0
  64. package/dist/runtime/emitter.js +79 -0
  65. package/dist/runtime/emitter.js.map +1 -0
  66. package/dist/runtime/global-hooks.d.ts +31 -0
  67. package/dist/runtime/global-hooks.d.ts.map +1 -0
  68. package/dist/runtime/global-hooks.js +126 -0
  69. package/dist/runtime/global-hooks.js.map +1 -0
  70. package/dist/runtime/index.d.ts +14 -3
  71. package/dist/runtime/index.d.ts.map +1 -1
  72. package/dist/runtime/index.js +7 -2
  73. package/dist/runtime/index.js.map +1 -1
  74. package/dist/runtime/run.d.ts +49 -2
  75. package/dist/runtime/run.d.ts.map +1 -1
  76. package/dist/runtime/run.js +618 -94
  77. package/dist/runtime/run.js.map +1 -1
  78. package/dist/runtime/runner.d.ts +97 -0
  79. package/dist/runtime/runner.d.ts.map +1 -0
  80. package/dist/runtime/runner.js +160 -0
  81. package/dist/runtime/runner.js.map +1 -0
  82. package/dist/runtime/suite-config.d.ts +23 -0
  83. package/dist/runtime/suite-config.d.ts.map +1 -0
  84. package/dist/runtime/suite-config.js +52 -0
  85. package/dist/runtime/suite-config.js.map +1 -0
  86. package/dist/runtime/suite-taps.d.ts +122 -0
  87. package/dist/runtime/suite-taps.d.ts.map +1 -0
  88. package/dist/runtime/suite-taps.js +218 -0
  89. package/dist/runtime/suite-taps.js.map +1 -0
  90. package/dist/runtime/suite.d.ts +277 -8
  91. package/dist/runtime/suite.d.ts.map +1 -1
  92. package/dist/runtime/suite.js +255 -4
  93. package/dist/runtime/suite.js.map +1 -1
  94. package/dist/runtime/test-context.d.ts +50 -3
  95. package/dist/runtime/test-context.d.ts.map +1 -1
  96. package/dist/runtime/test-context.js +83 -5
  97. package/dist/runtime/test-context.js.map +1 -1
  98. package/dist/runtime/worker.d.ts.map +1 -1
  99. package/dist/runtime/worker.js +85 -28
  100. package/dist/runtime/worker.js.map +1 -1
  101. package/index.darwin-arm64.node +0 -0
  102. package/index.darwin-x64.node +0 -0
  103. package/index.linux-arm64-gnu.node +0 -0
  104. package/index.linux-x64-gnu.node +0 -0
  105. package/index.win32-x64-msvc.node +0 -0
  106. package/package.json +8 -1
@@ -0,0 +1,47 @@
1
+ /**
2
+ * `tests/bootstrap.ts` — the AdonisJS bootstrap module.
3
+ *
4
+ * Adonis puts the run's plugins, runner hooks and suite hooks in one file that
5
+ * `bin/test.ts` imports before anything else:
6
+ *
7
+ * // tests/bootstrap.ts
8
+ * export const plugins = [assert(), apiClient()]
9
+ * export const runnerHooks = { setup: [() => …], teardown: [() => …] }
10
+ * export const configureSuite = (suite) => {
11
+ * if (["functional", "e2e"].includes(suite.name)) {
12
+ * return suite.setup(() => testUtils.httpServer().start())
13
+ * }
14
+ * }
15
+ *
16
+ * helix loads the same file with the same three exports — plus `filters` and
17
+ * `importer`, the two Japa `Config` fields Adonis sets in `bin/test.ts`, which
18
+ * helix has no equivalent of — so an Adonis `tests/bootstrap.ts` ports over
19
+ * unchanged. The CLI resolves it once and
20
+ * forwards the absolute path as `HELIX_BOOTSTRAP`, so it reaches the worker
21
+ * through BOTH orchestrators (the Rust engine and the TS pool spawn children
22
+ * that inherit the CLI's env).
23
+ *
24
+ * `runnerHooks` run ONCE for the whole run, in the process that spawns the
25
+ * workers — Japa's semantics. See `global-hooks.ts`. Everything else here is
26
+ * per worker because it has to be: a context macro, a filter, an importer only
27
+ * mean anything in the process that loads the test file.
28
+ */
29
+ /** File names probed under the project root when none is configured. */
30
+ export declare const BOOTSTRAP_FILENAMES: string[];
31
+ /**
32
+ * Resolve the bootstrap file for `root`: an explicit path (from
33
+ * `helix.config`), else the conventional `tests/bootstrap.*`. Returns
34
+ * `undefined` when the project has none — having no bootstrap is the norm, not
35
+ * an error.
36
+ */
37
+ export declare function resolveBootstrap(root: string, configured?: string): string | undefined;
38
+ /**
39
+ * Import the bootstrap module named by `HELIX_BOOTSTRAP` and hand its exports
40
+ * to {@link configure}. A no-op when the variable is unset — which is what
41
+ * every project without a bootstrap file, and every direct `runTestFile`
42
+ * caller, sees.
43
+ */
44
+ export declare function loadBootstrap(suite: string): Promise<void>;
45
+ /** Test seam: forget that a bootstrap was loaded in this process. */
46
+ export declare function resetBootstrap(): void;
47
+ //# sourceMappingURL=bootstrap.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/runtime/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAeH,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,UAI/B,CAAC;AAuEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAYpB;AAKD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAShE;AAgCD,qEAAqE;AACrE,wBAAgB,cAAc,IAAI,IAAI,CAGrC"}
@@ -0,0 +1,166 @@
1
+ /**
2
+ * `tests/bootstrap.ts` — the AdonisJS bootstrap module.
3
+ *
4
+ * Adonis puts the run's plugins, runner hooks and suite hooks in one file that
5
+ * `bin/test.ts` imports before anything else:
6
+ *
7
+ * // tests/bootstrap.ts
8
+ * export const plugins = [assert(), apiClient()]
9
+ * export const runnerHooks = { setup: [() => …], teardown: [() => …] }
10
+ * export const configureSuite = (suite) => {
11
+ * if (["functional", "e2e"].includes(suite.name)) {
12
+ * return suite.setup(() => testUtils.httpServer().start())
13
+ * }
14
+ * }
15
+ *
16
+ * helix loads the same file with the same three exports — plus `filters` and
17
+ * `importer`, the two Japa `Config` fields Adonis sets in `bin/test.ts`, which
18
+ * helix has no equivalent of — so an Adonis `tests/bootstrap.ts` ports over
19
+ * unchanged. The CLI resolves it once and
20
+ * forwards the absolute path as `HELIX_BOOTSTRAP`, so it reaches the worker
21
+ * through BOTH orchestrators (the Rust engine and the TS pool spawn children
22
+ * that inherit the CLI's env).
23
+ *
24
+ * `runnerHooks` run ONCE for the whole run, in the process that spawns the
25
+ * workers — Japa's semantics. See `global-hooks.ts`. Everything else here is
26
+ * per worker because it has to be: a context macro, a filter, an importer only
27
+ * mean anything in the process that loads the test file.
28
+ */
29
+ import { existsSync } from "node:fs";
30
+ import path from "node:path";
31
+ import { pathToFileURL } from "node:url";
32
+ import { configure, } from "./configure.js";
33
+ import { globalHooksHandledByParent } from "./global-hooks.js";
34
+ import { applySuiteConfigure } from "./suite-config.js";
35
+ import { resetTaps } from "./suite-taps.js";
36
+ /** File names probed under the project root when none is configured. */
37
+ export const BOOTSTRAP_FILENAMES = [
38
+ "tests/bootstrap.ts",
39
+ "tests/bootstrap.js",
40
+ "tests/bootstrap.mjs",
41
+ ];
42
+ /** `filters` as exported — every field optional, so read each defensively. */
43
+ function readFilters(imported) {
44
+ const source = Reflect.get(Object(imported), "filters");
45
+ if (source === null || typeof source !== "object")
46
+ return undefined;
47
+ const matchAll = Reflect.get(source, "matchAll");
48
+ return {
49
+ tags: stringList(source, "tags"),
50
+ groups: stringList(source, "groups"),
51
+ tests: stringList(source, "tests"),
52
+ matchAll: typeof matchAll === "boolean" ? matchAll : undefined,
53
+ };
54
+ }
55
+ function stringList(source, key) {
56
+ const value = Reflect.get(source, key);
57
+ if (!Array.isArray(value))
58
+ return undefined;
59
+ return value.filter((v) => typeof v === "string");
60
+ }
61
+ /** Everything about the module is optional — read defensively, never cast. */
62
+ function readModule(imported) {
63
+ if (imported === null || typeof imported !== "object")
64
+ return {};
65
+ const plugins = Reflect.get(imported, "plugins");
66
+ const hooks = Reflect.get(imported, "runnerHooks");
67
+ const configureSuite = Reflect.get(imported, "configureSuite");
68
+ const importer = Reflect.get(imported, "importer");
69
+ return {
70
+ filters: readFilters(imported),
71
+ importer: typeof importer === "function"
72
+ ? (file) => importer(file)
73
+ : undefined,
74
+ plugins: Array.isArray(plugins)
75
+ ? plugins.filter((p) => typeof p === "function")
76
+ : undefined,
77
+ runnerHooks: hooks !== null && typeof hooks === "object"
78
+ ? {
79
+ setup: hookList(hooks, "setup"),
80
+ teardown: hookList(hooks, "teardown"),
81
+ }
82
+ : undefined,
83
+ configureSuite: typeof configureSuite === "function"
84
+ ? (suite) => configureSuite(suite)
85
+ : undefined,
86
+ };
87
+ }
88
+ function hookList(source, key) {
89
+ const value = Reflect.get(source, key);
90
+ if (!Array.isArray(value))
91
+ return undefined;
92
+ return value.filter((fn) => typeof fn === "function");
93
+ }
94
+ /**
95
+ * Resolve the bootstrap file for `root`: an explicit path (from
96
+ * `helix.config`), else the conventional `tests/bootstrap.*`. Returns
97
+ * `undefined` when the project has none — having no bootstrap is the norm, not
98
+ * an error.
99
+ */
100
+ export function resolveBootstrap(root, configured) {
101
+ if (configured !== undefined && configured !== "") {
102
+ const absolute = path.isAbsolute(configured)
103
+ ? configured
104
+ : path.resolve(root, configured);
105
+ return existsSync(absolute) ? absolute : undefined;
106
+ }
107
+ for (const name of BOOTSTRAP_FILENAMES) {
108
+ const candidate = path.resolve(root, name);
109
+ if (existsSync(candidate))
110
+ return candidate;
111
+ }
112
+ return undefined;
113
+ }
114
+ /** Memoised so a worker that runs several files bootstraps exactly once. */
115
+ let loaded;
116
+ /**
117
+ * Import the bootstrap module named by `HELIX_BOOTSTRAP` and hand its exports
118
+ * to {@link configure}. A no-op when the variable is unset — which is what
119
+ * every project without a bootstrap file, and every direct `runTestFile`
120
+ * caller, sees.
121
+ */
122
+ export async function loadBootstrap(suite) {
123
+ const file = process.env.HELIX_BOOTSTRAP;
124
+ const hasSuiteConfig = (process.env.HELIX_SUITE_CONFIG ?? "") !== "";
125
+ // The suite's own `configure` is applied here too, so it reaches the same
126
+ // hook arrays before `configure()` drains them. That means this runs even
127
+ // with no bootstrap file — a project may declare one without the other.
128
+ if ((file === undefined || file === "") && !hasSuiteConfig)
129
+ return;
130
+ loaded ??= applyBootstrap(file ?? "", suite);
131
+ return loaded;
132
+ }
133
+ async function applyBootstrap(file, suite) {
134
+ const module = file === "" ? {} : readModule(await import(pathToFileURL(file).href));
135
+ // `runnerHooks` belong to the run, not to this file. When the parent ran
136
+ // them — which it does whenever a bootstrap exists — the worker must not run
137
+ // them again: that is the difference between migrating once and migrating
138
+ // once per test file.
139
+ const parentRanThem = globalHooksHandledByParent();
140
+ const setup = parentRanThem ? [] : [...(module.runnerHooks?.setup ?? [])];
141
+ const teardown = parentRanThem
142
+ ? []
143
+ : [...(module.runnerHooks?.teardown ?? [])];
144
+ // `configureSuite` is handed to `configure()` rather than called here, so it
145
+ // runs where Japa runs it: after the plugins, which is what lets a plugin
146
+ // read it or replace it. The per-suite callback chains onto it — both get
147
+ // the same handle, so hooks either registers reach the arrays below.
148
+ await configure({
149
+ plugins: module.plugins,
150
+ filters: module.filters,
151
+ importer: module.importer,
152
+ configureSuite: async (handle) => {
153
+ module.configureSuite?.(handle);
154
+ await applySuiteConfigure(suite, handle);
155
+ },
156
+ setup,
157
+ teardown,
158
+ suite,
159
+ });
160
+ }
161
+ /** Test seam: forget that a bootstrap was loaded in this process. */
162
+ export function resetBootstrap() {
163
+ loaded = undefined;
164
+ resetTaps();
165
+ }
166
+ //# sourceMappingURL=bootstrap.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/runtime/bootstrap.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,77 @@
1
+ /**
2
+ * The run's command-line arguments, as seen from inside a worker.
3
+ *
4
+ * `bin/helix.js` parses the flags in the CLI process and forwards them to every
5
+ * worker through the environment (`HELIX_TAGS`, `HELIX_TESTS`, …), because a
6
+ * worker is spawned by either orchestrator (Node pool or the Rust engine) with
7
+ * a fixed instruction shape. Reading them back here is what lets both the
8
+ * runtime and a plugin (`api.cliArgs`, Japa parity) see the same filters.
9
+ *
10
+ * One named deviation from Japa's `CLIArgs`: values are parsed (`string[]`,
11
+ * `number`, `boolean`) rather than kept as raw CLI strings. They have been
12
+ * through the parser once already, on the CLI side, and handing a plugin
13
+ * `"500"` to re-parse would be worse — Japa's own raw form exists because its
14
+ * CLI hands the config manager unparsed argv, which helix's does not.
15
+ */
16
+ /** Parsed CLI flags for the current run. */
17
+ export interface CLIArgs {
18
+ /** Positionals — the paths or suite names typed on the command line. */
19
+ _?: string[];
20
+ /** `--list-pinned` — collect and print the pinned tests, run nothing. */
21
+ listPinned?: boolean;
22
+ /** `--tags` — `~@tag`/`!@tag` entries exclude. */
23
+ tags?: string[];
24
+ /** `--tests` — exact test titles. */
25
+ tests?: string[];
26
+ /** `--groups` — exact group titles. */
27
+ groups?: string[];
28
+ /** `--match-all` — require every `--tags` entry instead of any. */
29
+ matchAll?: boolean;
30
+ /** `--timeout`, in ms. */
31
+ timeout?: number;
32
+ /** `--retries` — extra attempts on failure. */
33
+ retries?: number;
34
+ /** `--grep` — helix extra: regex/substring over the full test name. */
35
+ grep?: string;
36
+ /** `--suite` — the suite name these files belong to. */
37
+ suite?: string;
38
+ /** `--files` — substrings matched against the test file path (Japa `--files`). */
39
+ files?: string[];
40
+ /** `--reporters` — the reporters activated for this run. */
41
+ reporters?: string[];
42
+ /** `--bail` — stop at the first failure. */
43
+ bail?: boolean;
44
+ /** `--bail-layer` — how far a bail reaches. */
45
+ bailLayer?: string;
46
+ /** `--failed` — this run replays the previous run's failures. */
47
+ failed?: boolean;
48
+ /** `--force-exit` — the CLI will `process.exit()` once the run ends. */
49
+ forceExit?: boolean;
50
+ /**
51
+ * `--help`. Always absent in a worker: the CLI prints its help and exits
52
+ * before spawning anything, so nothing here could ever have seen it. Declared
53
+ * for the same reason Japa declares it — a plugin reading `cliArgs.help`
54
+ * should get `undefined`, not a type error.
55
+ */
56
+ help?: boolean;
57
+ /**
58
+ * Japa's open record. A host that forwards its own `HELIX_*` variable, or a
59
+ * plugin that stashes something for another, has somewhere to put it without
60
+ * the type standing in the way.
61
+ */
62
+ [flag: string]: string | string[] | number | boolean | undefined;
63
+ }
64
+ /** Comma-separated env list → trimmed non-empty entries, or undefined. */
65
+ export declare function envList(name: string): string[] | undefined;
66
+ /** A non-negative integer env var, or undefined when unset/invalid. */
67
+ export declare function envCount(name: string): number | undefined;
68
+ /** `--tags` as forwarded by the CLI. */
69
+ export declare function envTags(): string[] | undefined;
70
+ /** `--match-all` as forwarded by the CLI. */
71
+ export declare function envMatchAll(): boolean | undefined;
72
+ export declare function cliArgs(): CLIArgs;
73
+ /** Test seam: rebuild from the environment on the next access. */
74
+ export declare function resetCLIArgs(): void;
75
+ /** Every CLI flag the current worker can see, read fresh from the environment. */
76
+ export declare function readCLIArgs(): CLIArgs;
77
+ //# sourceMappingURL=cli-args.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../../src/runtime/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,OAAO;IACvB,wEAAwE;IACxE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IACb,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACjE;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAQ1D;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKzD;AAED,wCAAwC;AACxC,wBAAgB,OAAO,IAAI,MAAM,EAAE,GAAG,SAAS,CAE9C;AAED,6CAA6C;AAC7C,wBAAgB,WAAW,IAAI,OAAO,GAAG,SAAS,CAEjD;AAiBD,wBAAgB,OAAO,IAAI,OAAO,CAGjC;AAED,kEAAkE;AAClE,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED,kFAAkF;AAClF,wBAAgB,WAAW,IAAI,OAAO,CAmBrC"}
@@ -0,0 +1,85 @@
1
+ /**
2
+ * The run's command-line arguments, as seen from inside a worker.
3
+ *
4
+ * `bin/helix.js` parses the flags in the CLI process and forwards them to every
5
+ * worker through the environment (`HELIX_TAGS`, `HELIX_TESTS`, …), because a
6
+ * worker is spawned by either orchestrator (Node pool or the Rust engine) with
7
+ * a fixed instruction shape. Reading them back here is what lets both the
8
+ * runtime and a plugin (`api.cliArgs`, Japa parity) see the same filters.
9
+ *
10
+ * One named deviation from Japa's `CLIArgs`: values are parsed (`string[]`,
11
+ * `number`, `boolean`) rather than kept as raw CLI strings. They have been
12
+ * through the parser once already, on the CLI side, and handing a plugin
13
+ * `"500"` to re-parse would be worse — Japa's own raw form exists because its
14
+ * CLI hands the config manager unparsed argv, which helix's does not.
15
+ */
16
+ /** Comma-separated env list → trimmed non-empty entries, or undefined. */
17
+ export function envList(name) {
18
+ const raw = process.env[name];
19
+ if (raw === undefined || raw === "")
20
+ return undefined;
21
+ const items = raw
22
+ .split(",")
23
+ .map((t) => t.trim())
24
+ .filter((t) => t.length > 0);
25
+ return items.length > 0 ? items : undefined;
26
+ }
27
+ /** A non-negative integer env var, or undefined when unset/invalid. */
28
+ export function envCount(name) {
29
+ const raw = process.env[name];
30
+ if (raw === undefined || raw === "")
31
+ return undefined;
32
+ const n = Number.parseInt(raw, 10);
33
+ return Number.isFinite(n) && n >= 0 ? n : undefined;
34
+ }
35
+ /** `--tags` as forwarded by the CLI. */
36
+ export function envTags() {
37
+ return envList("HELIX_TAGS");
38
+ }
39
+ /** `--match-all` as forwarded by the CLI. */
40
+ export function envMatchAll() {
41
+ return process.env.HELIX_MATCH_ALL === "1" ? true : undefined;
42
+ }
43
+ /** A boolean flag as forwarded by the CLI — absent stays `undefined`, as in Japa. */
44
+ function envFlag(name) {
45
+ return process.env[name] === "1" ? true : undefined;
46
+ }
47
+ /**
48
+ * The run's flags, as ONE object.
49
+ *
50
+ * Japa hands its plugins a `cliArgs` they may edit — that is a documented way
51
+ * to steer a run from a plugin. Rebuilding it from the environment on every
52
+ * access would silently drop those edits, so it is built once and every reader
53
+ * (the plugin API, and the runtime's own filter resolution) shares it.
54
+ */
55
+ let materialised;
56
+ export function cliArgs() {
57
+ materialised ??= readCLIArgs();
58
+ return materialised;
59
+ }
60
+ /** Test seam: rebuild from the environment on the next access. */
61
+ export function resetCLIArgs() {
62
+ materialised = undefined;
63
+ }
64
+ /** Every CLI flag the current worker can see, read fresh from the environment. */
65
+ export function readCLIArgs() {
66
+ return {
67
+ tags: envTags(),
68
+ tests: envList("HELIX_TESTS"),
69
+ groups: envList("HELIX_GROUPS"),
70
+ matchAll: envMatchAll(),
71
+ timeout: envCount("HELIX_TIMEOUT"),
72
+ retries: envCount("HELIX_RETRIES"),
73
+ grep: process.env.HELIX_GREP,
74
+ suite: process.env.HELIX_SUITE,
75
+ files: envList("HELIX_FILES"),
76
+ reporters: envList("HELIX_REPORTERS"),
77
+ bail: envFlag("HELIX_BAIL"),
78
+ bailLayer: process.env.HELIX_BAIL_LAYER,
79
+ failed: envFlag("HELIX_FAILED"),
80
+ forceExit: envFlag("HELIX_FORCE_EXIT"),
81
+ listPinned: envFlag("HELIX_LIST_PINNED"),
82
+ _: envList("HELIX_POSITIONALS"),
83
+ };
84
+ }
85
+ //# sourceMappingURL=cli-args.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../src/runtime/cli-args.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,214 @@
1
+ /**
2
+ * `configure({ plugins })` — the Japa/AdonisJS bootstrap entry.
3
+ *
4
+ * Following Japa precisely: the runtime core is plugin-agnostic, and every
5
+ * capability (HTTP `client`, `db`, fakes, …) ships as a PLUGIN that extends the
6
+ * injected test context. A plugin is a function handed a {@link PluginApi};
7
+ * it registers context properties via `api.context.macro` / `.getter` (the
8
+ * `TestContext.macro`/`getter` of Japa) and pairs that with a `declare module`
9
+ * augmentation for the types.
10
+ *
11
+ * // tests/bootstrap.ts
12
+ * import { configure } from "@c9up/helix";
13
+ * import { apiClient } from "@c9up/ream/testing";
14
+ * await configure({ plugins: [apiClient({ baseUrl })] });
15
+ *
16
+ * This keeps `@c9up/helix` (the core) free of any ecosystem dependency: the
17
+ * plugins live in each package's `/testing` subpath and depend on helix, never
18
+ * the other way round — the Japa "runner + plugins" topology.
19
+ */
20
+ import { type CLIArgs } from "./cli-args.js";
21
+ import { type TestContext } from "./context.js";
22
+ import { type Emitter } from "./emitter.js";
23
+ import { Runner } from "./runner.js";
24
+ import { type SuiteHandle, type SuiteHook, type SuiteHookCleanup } from "./suite-taps.js";
25
+ /**
26
+ * What a plugin uses to extend the test context. Mirrors Japa's
27
+ * `TestContext.macro(name, value)` / `TestContext.getter(name, fn)`.
28
+ */
29
+ export interface PluginContext {
30
+ /** Add a shared property present on every test context. */
31
+ macro(name: string, value: unknown): void;
32
+ /** Add a lazily-computed, per-context property (cached per context). */
33
+ getter(name: string, fn: (ctx: TestContext) => unknown): void;
34
+ }
35
+ /** A runner-level hook — Japa's shape, defined once in `suite-taps.ts`. */
36
+ export type RunnerHook = SuiteHook;
37
+ export type RunnerHookCleanup = SuiteHookCleanup;
38
+ /**
39
+ * The API handed to each plugin at {@link configure} time.
40
+ *
41
+ * Japa hands its plugins `{ config, cliArgs, runner, emitter }`; helix passes
42
+ * the same four, so a Japa plugin's body ports over unchanged, plus two helix
43
+ * additions — `context` (Japa reaches the same registry through the imported
44
+ * `TestContext` class) and `cleanup` (Japa uses `config.teardown`).
45
+ */
46
+ export interface PluginApi {
47
+ /**
48
+ * The options this run was configured with (Japa `config`). Mutable: Japa
49
+ * plugins edit it, and helix reads it back once every plugin has run.
50
+ */
51
+ config: ConfigureOptions;
52
+ /** The flags the CLI forwarded to this worker (Japa `cliArgs`). */
53
+ cliArgs: CLIArgs;
54
+ /** Run-level counters, readable once the run ends (Japa `runner`). */
55
+ runner: Runner;
56
+ /** Lifecycle events — `test:start`, `group:end`, … (Japa `emitter`). */
57
+ emitter: Emitter;
58
+ /** Extend the injected test context. */
59
+ context: PluginContext;
60
+ /**
61
+ * Register a teardown that runs ONCE after all tests in the run finish
62
+ * (reverse registration order) — the place to close a booted server, a DB
63
+ * pool, etc. (Japa runner-teardown parity). Without this, a plugin that boots
64
+ * a resource at `configure()` has no clean shutdown point.
65
+ */
66
+ cleanup(fn: RunnerHook): void;
67
+ }
68
+ /**
69
+ * A helix plugin — the Japa plugin shape adapted to helix. Runs once at
70
+ * bootstrap; may be async (e.g. to boot a server before registering `client`).
71
+ */
72
+ export type Plugin = (api: PluginApi) => void | Promise<void>;
73
+ /**
74
+ * Filters applied to the tests a file declares (Japa `config.filters`).
75
+ *
76
+ * `files` and `suites` are reported, not honoured: they select which FILES run,
77
+ * and helix settles that list in the CLI process before any worker — and
78
+ * therefore any bootstrap — exists. Setting them here cannot un-spawn a worker
79
+ * that is already running, so they carry what the CLI decided and the CLI-side
80
+ * flags (`--files`, a suite positional) remain the way to decide it.
81
+ */
82
+ export interface ConfigureFilters {
83
+ /**
84
+ * Path fragments the CLI matched files against (Japa `filters.files`).
85
+ * Read-only here: helix settles the file list before a worker exists, so
86
+ * this reports what was selected rather than selecting.
87
+ */
88
+ files?: string[];
89
+ /** Suite names the run was limited to (Japa `filters.suites`). Read-only. */
90
+ suites?: string[];
91
+ /** Only tests carrying one of these tags (`~@tag`/`!@tag` excludes). */
92
+ tags?: string[];
93
+ /** Only groups with these exact titles. */
94
+ groups?: string[];
95
+ /** Only tests with these exact titles. */
96
+ tests?: string[];
97
+ /** Require EVERY tag in `tags` instead of any (Japa `--match-all`). */
98
+ matchAll?: boolean;
99
+ }
100
+ /**
101
+ * Japa's `Refiner`, as much of it as means anything here: a handle that ADDS
102
+ * filters. It writes straight into {@link ConfigureOptions.filters}, so a
103
+ * plugin calling `refiner.add("tags", [...])` steers the run exactly as setting
104
+ * the filter would — the object is a different door to the same room, not a
105
+ * second mechanism.
106
+ */
107
+ export interface Refiner {
108
+ /** Add filter values for a layer (Japa `refiner.add`). */
109
+ add(layer: "tests" | "groups" | "tags", values: string[]): void;
110
+ /** Require every tag instead of any (Japa `refiner.matchAllTags`). */
111
+ matchAllTags(toggle?: boolean): void;
112
+ }
113
+ /** Runtime configuration passed to {@link configure}. */
114
+ export interface ConfigureOptions {
115
+ /** Plugins to install — each extends the test context (Japa parity). */
116
+ plugins?: Plugin[];
117
+ /**
118
+ * The directory the run was launched from (Japa `cwd`). Filled in by the
119
+ * runtime, so a plugin resolving a path against the project reads the same
120
+ * root the CLI discovered from.
121
+ */
122
+ cwd?: string;
123
+ /**
124
+ * Configure the suite before it runs (Japa `configureSuite`). Applied AFTER
125
+ * the plugins, which is both Japa's order and what lets a plugin read it or
126
+ * put its own in place.
127
+ *
128
+ * May return a promise — Japa's is synchronous, but helix's per-suite
129
+ * `configure` has to re-import the config module, and hooks it registers must
130
+ * exist before the setup hooks are drained.
131
+ */
132
+ configureSuite?: (suite: SuiteHandle) => void | Promise<void>;
133
+ /**
134
+ * The reporters this run activated (Japa `reporters.activated`). Read-only
135
+ * truth: reporters live in the CLI process, so naming one here would not
136
+ * make it run.
137
+ */
138
+ reporters?: {
139
+ activated: string[];
140
+ };
141
+ /** `process.exit()` once the run ends (Japa `forceExit`). */
142
+ forceExit?: boolean;
143
+ /** Directories discovery skipped (Japa `exclude`). */
144
+ exclude?: string[];
145
+ /**
146
+ * The filter object (Japa `refiner`). Writes through to
147
+ * {@link ConfigureOptions.filters}, so `refiner.add("tags", [...])` from a
148
+ * plugin steers the run exactly as setting the filter would.
149
+ */
150
+ refiner?: Refiner;
151
+ /**
152
+ * Filters to apply to this file's tests (Japa `config.filters`). The CLI
153
+ * flags win: a filter typed at the prompt overrides the configured one.
154
+ */
155
+ filters?: ConfigureFilters;
156
+ /**
157
+ * How a test file is imported (Japa `config.importer`). Defaults to
158
+ * `import(file.href)`. Receives the URL helix would have imported —
159
+ * cache-busting query included, so repeated runs still re-evaluate.
160
+ */
161
+ importer?: (file: URL) => void | Promise<void>;
162
+ /** Run once before the tests (Japa runner `setup`). */
163
+ setup?: RunnerHook[];
164
+ /** Run once after the tests, reverse order (Japa runner `teardown`). */
165
+ teardown?: RunnerHook[];
166
+ /**
167
+ * Default per-test timeout in ms for this file's tests (Japa `configure({
168
+ * timeout })`). `0` disables. Overridden by `--timeout` and by a per-test
169
+ * `test.timeout(ms)` / `{ timeout }`.
170
+ */
171
+ timeout?: number;
172
+ /**
173
+ * Default extra attempts on failure for this file's tests (Japa `configure({
174
+ * retries })`). Overridden by `--retries` and by a per-test `test.retry(n)`.
175
+ */
176
+ retries?: number;
177
+ /**
178
+ * The name of the suite these tests belong to — surfaced as
179
+ * `ctx.test.options.meta.suite.name` and on the `suite:*` events. Defaults to
180
+ * `"default"`, the name Japa gives its implicit suite. Overridden by
181
+ * `--suite`.
182
+ */
183
+ suite?: string;
184
+ }
185
+ /** Run-level defaults from `configure({ timeout, retries, suite, filters })`. */
186
+ interface ConfiguredDefaults {
187
+ timeout?: number;
188
+ retries?: number;
189
+ suite?: string;
190
+ filters?: ConfigureFilters;
191
+ importer?: (file: URL) => void | Promise<void>;
192
+ }
193
+ /** The defaults set by {@link configure}, if any. */
194
+ export declare function getConfiguredDefaults(): Readonly<ConfiguredDefaults>;
195
+ /**
196
+ * Install plugins + runner hooks. Call once from a bootstrap file
197
+ * (Japa/AdonisJS `bin/test.ts` / `tests/bootstrap.ts`).
198
+ *
199
+ * Order follows Japa: PLUGINS first, then the run's `setup` hooks, then the
200
+ * `teardown` hooks are parked for after the run (see {@link
201
+ * drainRunnerTeardowns}). That ordering is what makes a plugin's edits count —
202
+ * it can raise `config.timeout`, push a `setup` hook, or reach for
203
+ * `runner.onSuite`, and the run picks all of it up because nothing has been
204
+ * read yet.
205
+ */
206
+ export declare function configure(options: ConfigureOptions): Promise<void>;
207
+ /**
208
+ * Run every registered runner teardown (reverse order), then clear them — called
209
+ * by the runtime after a file's tests finish. Failures are logged, not thrown,
210
+ * so one bad teardown can't hide the test results.
211
+ */
212
+ export declare function drainRunnerTeardowns(): Promise<void>;
213
+ export {};
214
+ //# sourceMappingURL=configure.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../../src/runtime/configure.ts"],"names":[],"mappings":"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"}