hypotes 0.1.1 → 0.3.0

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.
package/dist/cli.js ADDED
@@ -0,0 +1,329 @@
1
+ #!/usr/bin/env node
2
+ import { t as Projects } from "./project-Cf9C54In.js";
3
+ import { spawn } from "node:child_process";
4
+ import process from "node:process";
5
+ import { globSync } from "node:fs";
6
+ import { dirname, join, resolve, sep } from "node:path";
7
+ // source/project-filter.ts
8
+ /** A pattern as a regular expression of a whole name, in which `*` is any characters */
9
+ function toRegExp(pattern) {
10
+ const literals = pattern.split("*").map((literal) => RegExp.escape(literal));
11
+ return new RegExp(`^${literals.join(".*")}$`, "iu");
12
+ }
13
+ /** Selects projects by the patterns of `--project` */
14
+ var ProjectFilter = class {
15
+ #included;
16
+ #excluded;
17
+ /**
18
+ * Of patterns such as `@acme/api`, `@acme/*` and `!@acme/web`. A
19
+ * pattern that is empty, or only `!`, matches no project.
20
+ */
21
+ constructor(patterns) {
22
+ const excluded = patterns.filter((pattern) => pattern.startsWith("!"));
23
+ const included = patterns.filter((pattern) => !pattern.startsWith("!"));
24
+ this.#included = included.map((pattern) => toRegExp(pattern));
25
+ this.#excluded = excluded.map((pattern) => toRegExp(pattern.slice(1)));
26
+ }
27
+ /**
28
+ * Whether a project of the name is selected: no pattern with `!` matches
29
+ * it, and one of the others does, if there are others
30
+ */
31
+ matches(name) {
32
+ if (this.#excluded.some((pattern) => pattern.test(name))) return false;
33
+ return this.#included.length === 0 || this.#included.some((pattern) => pattern.test(name));
34
+ }
35
+ };
36
+ // source/test-files.ts
37
+ /** The directories that node:test doesn't look for test files in */
38
+ const EXCLUDED = ["**/node_modules/**"];
39
+ /** The characters of a path that mean something else in a glob pattern */
40
+ const GLOB_SYNTAX = /[()*?[\]{}]/gu;
41
+ /**
42
+ * A path as a glob pattern of itself, which node:test takes each of its
43
+ * arguments for: `[id]` would otherwise be either letter. A character that
44
+ * means something in a pattern goes in a class of its own, which no
45
+ * platform's paths read otherwise, as they do a backslash. A leading `!`
46
+ * would leave the pattern's files out. A name with a comma between braces
47
+ * is still read as its alternatives.
48
+ */
49
+ function escapeGlob(path) {
50
+ const escaped = path.replaceAll(sep, "/").replaceAll(GLOB_SYNTAX, "[$&]");
51
+ return escaped.startsWith("!") ? `./${escaped}` : escaped;
52
+ }
53
+ /**
54
+ * The pattern of the files that the command runs when it's given none:
55
+ * Vitest's default `include`, as it's written there. It has the extensions
56
+ * that Node doesn't run by itself, such as `.tsx`, which a preload of the
57
+ * caller's may.
58
+ */
59
+ const DEFAULT_PATTERN = "**/*.{test,spec}.?(c|m)[jt]s?(x)";
60
+ function isInside(directory, ancestor) {
61
+ return directory !== ancestor && (ancestor === "" || directory.startsWith(`${ancestor}/`));
62
+ }
63
+ /** The test files of projects under a working directory */
64
+ var TestFiles = class {
65
+ #cwd;
66
+ #filter;
67
+ #projects = new Projects();
68
+ /** Of the projects that the filter selects, under `cwd` */
69
+ constructor(cwd, filter) {
70
+ this.#cwd = cwd;
71
+ this.#filter = filter;
72
+ }
73
+ /**
74
+ * The names of the projects under the working directory, and of the one
75
+ * that it's in, in order
76
+ */
77
+ projectNames() {
78
+ return [...new Set(this.#scopes().map((scope) => scope.name))].toSorted();
79
+ }
80
+ /**
81
+ * The files that match the glob patterns and are in a selected project,
82
+ * as patterns of their paths from the working directory, in order. A
83
+ * file that no package with a name is above is in no project.
84
+ */
85
+ matching(patterns) {
86
+ return globSync([...patterns], {
87
+ cwd: this.#cwd,
88
+ exclude: EXCLUDED
89
+ }).filter((file) => {
90
+ const project = this.#projects.of(resolve(this.#cwd, file));
91
+ return project !== void 0 && this.#filter.matches(project.name);
92
+ }).toSorted().map((file) => escapeGlob(file));
93
+ }
94
+ /**
95
+ * What names the test files of the selected projects to node:test: a
96
+ * pattern for a project's directory, or its files, as the header says.
97
+ * Nothing, if no project is selected, or none of the listed has a test
98
+ * file.
99
+ */
100
+ ofProjects(pattern) {
101
+ const scopes = this.#scopes();
102
+ const selected = scopes.filter((scope) => this.#filter.matches(scope.name));
103
+ const whole = selected.filter((scope) => this.#isWhole(scope, scopes));
104
+ const patterns = whole.filter((scope) => !whole.some((other) => isInside(scope.directory, other.directory))).map(({ directory }) => directory === "" ? pattern : `${escapeGlob(directory)}/${pattern}`);
105
+ const files = selected.filter((scope) => !whole.includes(scope)).flatMap((scope) => this.#filesOf(scope, pattern));
106
+ return [...patterns, ...files];
107
+ }
108
+ /**
109
+ * The project that the working directory is in, and those in the
110
+ * directories under it
111
+ */
112
+ #scopes() {
113
+ const scopes = [];
114
+ const around = this.#projects.of(join(this.#cwd, "package.json"));
115
+ if (around !== void 0 && around.directory !== this.#cwd) scopes.push({
116
+ name: around.name,
117
+ directory: "",
118
+ root: around.directory
119
+ });
120
+ for (const file of globSync("**/package.json", {
121
+ cwd: this.#cwd,
122
+ exclude: EXCLUDED
123
+ })) {
124
+ const directory = resolve(this.#cwd, dirname(file));
125
+ const project = this.#projects.of(join(directory, "package.json"));
126
+ if (project?.directory === directory) {
127
+ const path = dirname(file).replaceAll(sep, "/");
128
+ scopes.push({
129
+ name: project.name,
130
+ directory: path === "." ? "" : path,
131
+ root: directory
132
+ });
133
+ }
134
+ }
135
+ return scopes;
136
+ }
137
+ /**
138
+ * Whether a pattern of the project's directory names its files, and no
139
+ * others: each project inside it is selected too
140
+ */
141
+ #isWhole({ directory }, scopes) {
142
+ return scopes.filter((scope) => isInside(scope.directory, directory)).every((scope) => this.#filter.matches(scope.name));
143
+ }
144
+ /** The project's own files that match the pattern, not those of projects inside it */
145
+ #filesOf({ directory, root }, pattern) {
146
+ const from = resolve(this.#cwd, directory);
147
+ return globSync(pattern, {
148
+ cwd: from,
149
+ exclude: EXCLUDED
150
+ }).filter((file) => this.#projects.of(resolve(from, file))?.directory === root).map((file) => directory === "" ? file : join(directory, file)).toSorted().map((file) => escapeGlob(file));
151
+ }
152
+ };
153
+ // source/cli.ts
154
+ const USAGE = `Usage: hypotes [--project <name>]... [node's flags] [files or patterns]
155
+
156
+ Runs tests with node --test, with the preload hypotes/register and the
157
+ reporter hypotes/reporter. Other flags are node's, such as --watch,
158
+ --test-name-pattern=<pattern> and --test-reporter=<reporter>. A flag's value
159
+ follows a =, or it's taken for a pattern of files, and node fails the flag.
160
+
161
+ Without files or patterns, it runs the files that match
162
+ ${DEFAULT_PATTERN}
163
+ and without --test-timeout, a test or a hook fails after 5 seconds. It ends
164
+ each file once its tests are done, whatever they left running, unless it's
165
+ given --no-test-force-exit or --watch.
166
+
167
+ --project <name> Runs only the test files of the package with the name in
168
+ its package.json. Can be repeated. A * matches any
169
+ characters, and a leading ! leaves projects out.
170
+ -h, --help Prints this.
171
+ `;
172
+ /** Node's exit code for an invalid argument */
173
+ const INVALID_ARGUMENT = 9;
174
+ /** Vitest's default `testTimeout`, in milliseconds */
175
+ const DEFAULT_TIMEOUT = 5e3;
176
+ /** The argument after which Node takes each one for a file, not a flag */
177
+ const SEPARATOR = "--";
178
+ /** The signals that end a process, which the launcher passes on to Node */
179
+ const SIGNALS = [
180
+ "SIGINT",
181
+ "SIGTERM",
182
+ "SIGHUP"
183
+ ];
184
+ /** An error in how the command was called, which it prints without a stack */
185
+ var UsageError = class extends Error {
186
+ #exitCode;
187
+ constructor(message, exitCode) {
188
+ super(message);
189
+ this.#exitCode = exitCode;
190
+ }
191
+ exitCode() {
192
+ return this.#exitCode;
193
+ }
194
+ };
195
+ function parseArguments(args) {
196
+ const projects = [];
197
+ const rest = [];
198
+ let help = false;
199
+ for (let index = 0; index < args.length; index++) {
200
+ const argument = args[index];
201
+ if (argument === "--project") {
202
+ index++;
203
+ if (index === args.length) throw new UsageError("--project needs the name of a project", INVALID_ARGUMENT);
204
+ projects.push(args[index]);
205
+ } else if (argument.startsWith("--project=")) projects.push(argument.slice(10));
206
+ else if (argument === "--help" || argument === "-h") help = true;
207
+ else rest.push(argument);
208
+ }
209
+ return {
210
+ projects,
211
+ rest,
212
+ help
213
+ };
214
+ }
215
+ /** Whether an argument names files, rather than being one of node's flags */
216
+ function isPattern(argument) {
217
+ return !argument.startsWith("-");
218
+ }
219
+ /** Whether the arguments have the flag, with a value or without */
220
+ function hasFlag(args, flag) {
221
+ return args.some((argument) => argument === flag || argument.startsWith(`${flag}=`));
222
+ }
223
+ /**
224
+ * Node's flags among the arguments, apart from what names files: the
225
+ * arguments without a leading `-`, and each one after a `--`, as in Node
226
+ */
227
+ function separate(rest) {
228
+ const end = rest.indexOf(SEPARATOR);
229
+ const before = end === -1 ? rest : rest.slice(0, end);
230
+ const after = end === -1 ? [] : rest.slice(end + 1);
231
+ return {
232
+ flags: before.filter((argument) => !isPattern(argument)),
233
+ patterns: [...before.filter(isPattern), ...after]
234
+ };
235
+ }
236
+ /**
237
+ * What names the test files of the selected projects, in place of the
238
+ * patterns
239
+ */
240
+ function selectFiles(projects, patterns, cwd) {
241
+ const testFiles = new TestFiles(cwd, new ProjectFilter(projects));
242
+ const named = patterns.length === 0 ? testFiles.ofProjects(DEFAULT_PATTERN) : testFiles.matching(patterns);
243
+ if (named.length === 0) {
244
+ const known = testFiles.projectNames().join(", ");
245
+ throw new UsageError(`found no test files of --project ${projects.join(", ")}, among the projects ${known}`, 1);
246
+ }
247
+ return named;
248
+ }
249
+ /** The files and patterns that Node runs: the default pattern, if none is named */
250
+ function filesToRun(projects, patterns, cwd) {
251
+ if (projects.length > 0) return selectFiles(projects, patterns, cwd);
252
+ return patterns.length === 0 ? [DEFAULT_PATTERN] : patterns;
253
+ }
254
+ /**
255
+ * The arguments that Node runs the tests with: the flags, then the files
256
+ * after a `--`, as the header says
257
+ */
258
+ function nodeArguments({ projects, rest }, cwd) {
259
+ const { flags, patterns } = separate(rest);
260
+ const files = filesToRun(projects, patterns, cwd);
261
+ return [
262
+ "--import",
263
+ import.meta.resolve("hypotes/register"),
264
+ "--test",
265
+ ...hasFlag(flags, "--test-reporter") ? [] : [`--test-reporter=${import.meta.resolve("hypotes/reporter")}`],
266
+ ...hasFlag(flags, "--test-timeout") ? [] : [`--test-timeout=${DEFAULT_TIMEOUT}`],
267
+ ...hasFlag(flags, "--watch") ? [] : ["--test-force-exit"],
268
+ ...flags,
269
+ SEPARATOR,
270
+ ...files
271
+ ];
272
+ }
273
+ /**
274
+ * Ends this process as Node ended: with its exit code, or by its signal.
275
+ * Node gets the signals that this process does, or it would outlive a
276
+ * launcher that another process ends, as it would under `--watch`.
277
+ */
278
+ function follow(node) {
279
+ const forwards = SIGNALS.map((signal) => {
280
+ const forward = () => {
281
+ node.kill(signal);
282
+ };
283
+ process.on(signal, forward);
284
+ return {
285
+ signal,
286
+ forward
287
+ };
288
+ });
289
+ node.on("exit", (code, signal) => {
290
+ for (const { signal: forwarded, forward } of forwards) process.off(forwarded, forward);
291
+ if (signal === null) process.exitCode = code ?? 1;
292
+ else process.kill(process.pid, signal);
293
+ });
294
+ }
295
+ function startFailure(error, args) {
296
+ const code = error.code;
297
+ return code === "E2BIG" || code === "ENAMETOOLONG" ? `the command that names the test files to Node is too long, with ${args.length} arguments. Select fewer files with --project or a pattern.` : `couldn't start Node: ${String(error)}`;
298
+ }
299
+ /**
300
+ * Starts Node. A command can only be so long, which the test files of a
301
+ * project that are named one by one can exceed: the system then refuses to
302
+ * start it.
303
+ */
304
+ function start(args) {
305
+ try {
306
+ return spawn(process.execPath, args, { stdio: "inherit" }).on("error", (error) => {
307
+ process.stderr.write(`hypotes: ${startFailure(error, args)}\n`);
308
+ process.exitCode = 1;
309
+ });
310
+ } catch (error) {
311
+ throw new UsageError(startFailure(error, args), 1);
312
+ }
313
+ }
314
+ function main() {
315
+ const parsed = parseArguments(process.argv.slice(2));
316
+ if (parsed.help) {
317
+ process.stdout.write(USAGE);
318
+ return;
319
+ }
320
+ follow(start(nodeArguments(parsed, process.cwd())));
321
+ }
322
+ try {
323
+ main();
324
+ } catch (error) {
325
+ if (!(error instanceof UsageError)) throw error;
326
+ process.stderr.write(`hypotes: ${error.message}\n`);
327
+ process.exitCode = error.exitCode();
328
+ }
329
+ export {};
package/dist/index.d.ts CHANGED
@@ -1,9 +1,13 @@
1
- import { clearAllMocks, fn, isMockFunction, resetAllMocks, restoreAllMocks, spyOn, type MaybeMocked, type MaybeMockedDeep, type MaybePartiallyMocked, type MaybePartiallyMockedDeep } from '@vitest/spy';
1
+ import { fn, isMockFunction, spyOn, type MaybeMocked, type MaybeMockedDeep, type MaybePartiallyMocked, type MaybePartiallyMockedDeep } from '@vitest/spy';
2
2
  import { doMock, doUnmock, hoisted, importActual, mock, unmock } from './mocks.ts';
3
+ import { type StubsAPI } from './stubs.ts';
4
+ import { type TimersAPI } from './timers.ts';
5
+ import { type WaitAPI } from './wait.ts';
3
6
  export { expect, type Expect } from './expect.ts';
4
7
  export { afterAll, afterEach, beforeAll, beforeEach, type AfterHook, type Hook } from './hooks.ts';
5
8
  export { describe, it, suite, test, type Declare, type Each, type For, type Modifiers, type SuiteAPI, type SuiteContext, type SuiteFunction, type TestAPI, type TestContext, type TestFunction, type TestOptions } from './tests.ts';
6
9
  export type { MockFactoryWithHelper } from './mocks.ts';
10
+ export type { FakeTimersConfig } from './timers.ts';
7
11
  export type { Mock, MockInstance } from '@vitest/spy';
8
12
  /**
9
13
  * Returns the value, typed as its mock: a type helper, for what `vi.mock()`
@@ -29,13 +33,8 @@ declare function mocked<T>(item: T, options: {
29
33
  partial: true;
30
34
  deep: true;
31
35
  }): MaybePartiallyMockedDeep<T>;
32
- /**
33
- * Vitest's spies, which its matchers, such as `toHaveBeenCalledWith`, check,
34
- * and its module mocks, which node preloads with `--import hypotes/register`.
35
- * node:test's `mock` mocks timers.
36
- */
37
- export declare const vi: {
38
- clearAllMocks: typeof clearAllMocks;
36
+ /** The members of `vi` that mock functions, objects' methods, and modules */
37
+ declare const mocks: {
39
38
  doMock: typeof doMock;
40
39
  doUnmock: typeof doUnmock;
41
40
  fn: typeof fn;
@@ -44,8 +43,22 @@ export declare const vi: {
44
43
  isMockFunction: typeof isMockFunction;
45
44
  mock: typeof mock;
46
45
  mocked: typeof mocked;
47
- resetAllMocks: typeof resetAllMocks;
48
- restoreAllMocks: typeof restoreAllMocks;
49
46
  spyOn: typeof spyOn;
50
47
  unmock: typeof unmock;
51
48
  };
49
+ /** `vi`, which the members that Vitest's return `vi` from return */
50
+ export interface Vi extends Readonly<typeof mocks>, StubsAPI<Vi>, TimersAPI<Vi>, WaitAPI {
51
+ /** Clears the calls and results of every mock */
52
+ clearAllMocks(): Vi;
53
+ /** Clears every mock, and resets its implementation to its original */
54
+ resetAllMocks(): Vi;
55
+ /** Restores what every `vi.spyOn()` replaced */
56
+ restoreAllMocks(): Vi;
57
+ }
58
+ /**
59
+ * Vitest's spies, which its matchers, such as `toHaveBeenCalledWith`, check,
60
+ * its module mocks, which node preloads with `--import hypotes/register`,
61
+ * its fake timers, its stubs of globals and environment variables, and its
62
+ * waits.
63
+ */
64
+ export declare const vi: Vi;