hypotes 0.2.0 → 0.3.1

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/README.md CHANGED
@@ -92,7 +92,8 @@ which aren't the ones that Vitest runs:
92
92
  `*.spec.ts` there.
93
93
  - It doesn't run `*.spec.ts` outside a `test` directory, which Vitest does.
94
94
 
95
- To run other files, name them, as in `node --test "**/*.spec.ts"`.
95
+ To run other files, name them, as in `node --test "**/*.spec.ts"`. Or run
96
+ [the `hypotes` command](#test-files), which runs the files that Vitest does.
96
97
 
97
98
  ## Mocking modules
98
99
 
@@ -373,9 +374,10 @@ in another form. Of `vi`, hypotes has only the members that
373
374
  process. node:test runs each file in a process of its own, so that means
374
375
  the file's tests, as in Vitest. With `--test-isolation=none`, the files
375
376
  share one process, and the hook runs for the tests of them all.
376
- - **Timeouts.** A test or a hook has no timeout unless it's given one. Vitest
377
- fails a test after 5 seconds, and a hook after 10. Node's `--test-timeout`
378
- sets one for every test.
377
+ - **Timeouts.** Under `node --test`, a test or a hook has no timeout unless
378
+ it's given one. Vitest fails a test after 5 seconds, and a hook after 10.
379
+ Node's `--test-timeout` sets one for every test and hook, and
380
+ [the `hypotes` command](#timeout) passes Vitest's 5 seconds.
379
381
 
380
382
  ### Equality
381
383
 
@@ -470,22 +472,116 @@ Messages have colours only where Node prints them: to a terminal, or with
470
472
 
471
473
  ## The `hypotes` command
472
474
 
473
- `hypotes` runs `node --test` with hypotes' preload and reporter, and passes
474
- its other arguments on. These two commands do the same:
475
+ `hypotes` runs `node --test` with hypotes' preload and reporter, and with
476
+ Vitest's defaults for the test files, the timeout, and how a test file
477
+ ends. It passes its other arguments on. These two commands do the same:
475
478
 
476
479
  ```bash
477
480
  npx hypotes
478
481
  ```
479
482
 
480
483
  ```bash
481
- node --import hypotes/register --test --test-reporter=hypotes/reporter
484
+ node --import hypotes/register --test --test-reporter=hypotes/reporter --test-timeout=5000 --test-force-exit "**/*.{test,spec}.?(c|m)[jt]s?(x)"
482
485
  ```
483
486
 
484
487
  node:test's flags work as they do with `node --test`, as in
485
- `npx hypotes --watch` or `npx hypotes "**/*.spec.ts"`. With
486
- `--test-reporter`, node:test uses that reporter rather than
487
- [hypotes' own](#reporter). The command exits as Node does: with 1 if a test
488
- fails.
488
+ `npx hypotes --watch`. With `--test-reporter`, node:test uses that reporter
489
+ rather than [hypotes' own](#reporter). The command exits as Node does: with
490
+ 1 if a test fails.
491
+
492
+ A flag takes its value after `=`. Write `--test-name-pattern=adds`, not
493
+ `--test-name-pattern adds`: the command takes an argument without a leading
494
+ `-` for a file or a pattern of files. Node then fails, as the flag has no
495
+ value, with `--test-name-pattern requires an argument`.
496
+
497
+ After a `--`, each argument is a file or a pattern, as in Node.
498
+
499
+ ### Test files
500
+
501
+ Named no files, the command runs those that match Vitest's default
502
+ [`include`](https://vitest.dev/config/include), outside `node_modules`:
503
+
504
+ ```text
505
+ **/*.{test,spec}.?(c|m)[jt]s?(x)
506
+ ```
507
+
508
+ So it runs `sum.test.ts` and `sum.spec.js`, in any directory. It doesn't run
509
+ the other files of a `test` directory, such as helpers, which `node --test`
510
+ does. In `package.json`, the script is the command alone:
511
+
512
+ ```json
513
+ {
514
+ "scripts": {
515
+ "test": "hypotes"
516
+ }
517
+ }
518
+ ```
519
+
520
+ A file or a pattern takes the place of the default, so
521
+ `npm test -- test/sum.test.ts` runs that file alone.
522
+
523
+ - **`.jsx` and `.tsx`.** The pattern has them, as Vitest's does, but Node
524
+ doesn't run them by itself. They need a preload of your own that does,
525
+ passed with `--import`.
526
+ - **`--no-strip-types`.** The pattern has `.ts`, `.mts` and `.cts` then
527
+ too, which Node can't run without stripping types, so those files fail.
528
+ Name a pattern of your own, such as `"**/*.test.js"`.
529
+ - **No test files.** If nothing matches, node:test runs no tests and the
530
+ command exits with 0. Vitest fails.
531
+
532
+ ### Timeout
533
+
534
+ The command passes `--test-timeout=5000`, Vitest's default of 5 seconds.
535
+ Without it, a test that never ends holds a CI job until the job's own limit.
536
+ A `--test-timeout` of your own takes its place, as in
537
+ `npx hypotes --test-timeout=30000`.
538
+
539
+ - **Hooks have the same timeout.** node:test gives the timeout to hooks too,
540
+ so a hook fails after 5 seconds. In Vitest, a hook has 10. Give a slow
541
+ hook its own, as in `beforeAll(fn, 10_000)`.
542
+ - **A timeout fails the test, but doesn't end what it started.** A timer or
543
+ a server that the test left running goes on. The command ends the file's
544
+ process anyway, as [the next section](#what-a-test-leaves-running) says.
545
+
546
+ ### What a test leaves running
547
+
548
+ The command passes Node's
549
+ [`--test-force-exit`](https://nodejs.org/api/cli.html#--test-force-exit).
550
+ node:test then ends each file's process once its tests and hooks are done,
551
+ as Vitest ends a file's worker. Without it, a timer, a server, or an open
552
+ connection that a test left behind keeps the process alive, and holds a CI
553
+ job until the job's own limit, even after the test has timed out.
554
+
555
+ - **A leak passes unseen.** A test that leaves something running passes,
556
+ and nothing says so. To find such tests, run
557
+ `npx hypotes --no-test-force-exit`: the run then waits for them.
558
+ - **Work that isn't awaited is cut off.** What a test starts and doesn't
559
+ wait for, such as a write to a file, may not finish. Await it in the test
560
+ or in a hook.
561
+ - **`--watch`.** Node refuses `--test-force-exit` together with `--watch`,
562
+ so the command leaves it out under `--watch`.
563
+ It doesn't see a `watch` in
564
+ [Node's configuration file](#nodes-configuration-file), so pass
565
+ `--watch` to the command instead.
566
+
567
+ ### Node's configuration file
568
+
569
+ Node reads a `node.config.json` when it's given `--config-file`, which the
570
+ command passes on, as in `npx hypotes --config-file`. Before Node 26.12, the
571
+ flag is `--experimental-config-file`. Node's
572
+ [documentation](https://nodejs.org/api/cli.html) has what the file takes.
573
+
574
+ The file's settings reach node:test as they do under `node --test`, but for
575
+ three, which the command passes flags of its own for:
576
+
577
+ - **`test-timeout`.** The command's 5 seconds take its place, since a flag
578
+ overrides the file. Pass `--test-timeout` to the command instead.
579
+ - **`test-reporter`.** Node adds the file's reporter to the command's, and
580
+ fails: it then wants a `--test-reporter-destination` for each. Leave the
581
+ reporter out of the file, and pass `--test-reporter` to the command
582
+ instead.
583
+ - **`test-force-exit`.** The command's flag takes its place. Pass
584
+ `--no-test-force-exit` to the command instead.
489
585
 
490
586
  ### Running one project
491
587
 
@@ -517,14 +613,11 @@ nearest `package.json` above it that has a `name`.
517
613
 
518
614
  node:test can't select files by their package, so with `--project` the
519
615
  command names each selected project's directory to node:test, as a pattern.
520
- node:test then finds the test files in it, as it does without `--project`.
616
+ node:test then finds the test files in it, by the same
617
+ [pattern](#test-files) as without `--project`.
521
618
 
522
619
  - **Names match in any case.** `--project "@SHOP/web"` selects
523
620
  `@shop/web`, as it does in Vitest.
524
- - **Flags take their values after `=`.** Write
525
- `--test-name-pattern=adds`, not `--test-name-pattern adds`: with
526
- `--project`, the command takes an argument without a leading `-` for a
527
- pattern of files.
528
621
  - **No project matches.** The command fails, and lists the projects that it
529
622
  found.
530
623
 
@@ -676,7 +769,7 @@ Rules for mocks:
676
769
  | Rule | What it checks |
677
770
  | ------------------------------ | ----------------------------------------------------------------------------------------- |
678
771
  | `hoisted-apis-on-top` | `vi.mock()`, `vi.unmock()` and `vi.hoisted()` are top-level statements, where they hoist. |
679
- | `require-mock-type-parameters` | `vi.fn()` is given the type of the function that it mocks, in TypeScript. |
772
+ | `require-mock-type-parameters` | `vi.fn()` without an implementation is given the type that it mocks, in TypeScript. |
680
773
 
681
774
  ## License
682
775
 
package/dist/cli.js CHANGED
@@ -51,13 +51,12 @@ function escapeGlob(path) {
51
51
  return escaped.startsWith("!") ? `./${escaped}` : escaped;
52
52
  }
53
53
  /**
54
- * The pattern of the files that node:test runs when it's given none, which
55
- * its documentation lists. It takes TypeScript's extensions unless Node is
56
- * told not to strip types.
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.
57
58
  */
58
- function defaultPattern(stripsTypes) {
59
- return `**/{test,test/**/*,test-*,*[._-]test}.{${stripsTypes ? "js,mjs,cjs,ts,mts,cts" : "js,mjs,cjs"}}`;
60
- }
59
+ const DEFAULT_PATTERN = "**/*.{test,spec}.?(c|m)[jt]s?(x)";
61
60
  function isInside(directory, ancestor) {
62
61
  return directory !== ancestor && (ancestor === "" || directory.startsWith(`${ancestor}/`));
63
62
  }
@@ -156,7 +155,14 @@ const USAGE = `Usage: hypotes [--project <name>]... [node's flags] [files or pat
156
155
 
157
156
  Runs tests with node --test, with the preload hypotes/register and the
158
157
  reporter hypotes/reporter. Other flags are node's, such as --watch,
159
- --test-name-pattern=<pattern> and --test-reporter=<reporter>.
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.
160
166
 
161
167
  --project <name> Runs only the test files of the package with the name in
162
168
  its package.json. Can be repeated. A * matches any
@@ -165,6 +171,10 @@ reporter hypotes/reporter. Other flags are node's, such as --watch,
165
171
  `;
166
172
  /** Node's exit code for an invalid argument */
167
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 = "--";
168
178
  /** The signals that end a process, which the launcher passes on to Node */
169
179
  const SIGNALS = [
170
180
  "SIGINT",
@@ -202,32 +212,62 @@ function parseArguments(args) {
202
212
  help
203
213
  };
204
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
+ }
205
236
  /**
206
- * Node's flags among the arguments, and what names the test files of the
207
- * selected projects in place of the patterns
237
+ * What names the test files of the selected projects, in place of the
238
+ * patterns
208
239
  */
209
- function selectFiles(projects, rest, cwd) {
210
- const flags = rest.filter((argument) => argument.startsWith("-"));
211
- const patterns = rest.filter((argument) => !argument.startsWith("-"));
212
- const stripsTypes = !flags.some((flag) => /^--no-(?:experimental-)?strip-types$/u.test(flag));
240
+ function selectFiles(projects, patterns, cwd) {
213
241
  const testFiles = new TestFiles(cwd, new ProjectFilter(projects));
214
- const named = patterns.length === 0 ? testFiles.ofProjects(defaultPattern(stripsTypes)) : testFiles.matching(patterns);
242
+ const named = patterns.length === 0 ? testFiles.ofProjects(DEFAULT_PATTERN) : testFiles.matching(patterns);
215
243
  if (named.length === 0) {
216
244
  const known = testFiles.projectNames().join(", ");
217
245
  throw new UsageError(`found no test files of --project ${projects.join(", ")}, among the projects ${known}`, 1);
218
246
  }
219
- return [...flags, ...named];
247
+ return named;
220
248
  }
221
- /** The arguments that Node runs the tests with */
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
+ */
222
258
  function nodeArguments({ projects, rest }, cwd) {
223
- const passed = projects.length === 0 ? rest : selectFiles(projects, rest, cwd);
224
- const hasReporter = rest.some((argument) => /^--test-reporter(?:=|$)/u.test(argument));
259
+ const { flags, patterns } = separate(rest);
260
+ const files = filesToRun(projects, patterns, cwd);
225
261
  return [
226
262
  "--import",
227
263
  import.meta.resolve("hypotes/register"),
228
264
  "--test",
229
- ...hasReporter ? [] : [`--test-reporter=${import.meta.resolve("hypotes/reporter")}`],
230
- ...passed
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
231
271
  ];
232
272
  }
233
273
  /**
@@ -812,13 +812,14 @@ const plugin = {
812
812
  "require-mock-type-parameters": {
813
813
  meta: {
814
814
  type: "problem",
815
- docs: { description: "Requires vi.fn() to be given the type of the function that it mocks, in TypeScript" }
815
+ docs: { description: "Requires a vi.fn() without an implementation to be given the type of the function that it mocks, in TypeScript" }
816
816
  },
817
817
  create(context) {
818
818
  if (!TYPESCRIPT.test(context.filename)) return {};
819
819
  return { CallExpression(call) {
820
820
  const method = viMethodOf(context, call);
821
821
  if (method?.property.name !== "fn" || call.typeArguments) return;
822
+ if (call.arguments.length > 0) return;
822
823
  context.report({
823
824
  node: method.property,
824
825
  message: "Expected vi.fn() to be given the type of the function that it mocks, as in vi.fn<() => void>()"
@@ -1,10 +1,11 @@
1
1
  import type { ProjectFilter } from './project-filter.ts';
2
2
  /**
3
- * The pattern of the files that node:test runs when it's given none, which
4
- * its documentation lists. It takes TypeScript's extensions unless Node is
5
- * told not to strip types.
3
+ * The pattern of the files that the command runs when it's given none:
4
+ * Vitest's default `include`, as it's written there. It has the extensions
5
+ * that Node doesn't run by itself, such as `.tsx`, which a preload of the
6
+ * caller's may.
6
7
  */
7
- export declare function defaultPattern(stripsTypes: boolean): string;
8
+ export declare const DEFAULT_PATTERN = "**/*.{test,spec}.?(c|m)[jt]s?(x)";
8
9
  /** The test files of projects under a working directory */
9
10
  export declare class TestFiles {
10
11
  #private;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hypotes",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "description": "Vitest's API on node:test. Same tests, no Vite.",
5
5
  "keywords": [
6
6
  "expect",