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/README.md CHANGED
@@ -3,17 +3,19 @@
3
3
  Vitest's API on Node's test runner. Same tests, no Vite.
4
4
 
5
5
  Tests written with `describe`, `it`, `expect` and `vi` from hypotes run with
6
- `node --test`. There is no bundler, no config file and no second runner: Node
7
- runs the test files as they are, and node:test's reporters, watch mode and
8
- coverage apply to them. It runs TypeScript by
9
- [stripping its types](https://nodejs.org/api/typescript.html#type-stripping),
10
- so a test file, and what it imports, has to run on Node as it's written.
11
-
12
- Use hypotes when you want Vitest's matchers, spies and module mocks, but
13
- node:test as the runner. A test file that uses what both have moves between
14
- Vitest and hypotes by changing its imports. If you need what only Vitest
15
- has, such as snapshots, browser mode or Vite's transforms, use Vitest:
16
- [Left out](#left-out) lists what hypotes doesn't have.
6
+ `node --test`. There is no bundler and no config file, and node:test stays
7
+ the runner: Node runs the test files as they are, and node:test's reporters,
8
+ watch mode and coverage apply to them. The
9
+ [`hypotes` command](#the-hypotes-command) is a shorter way to call it. It runs
10
+ TypeScript by [stripping its
11
+ types](https://nodejs.org/api/typescript.html#type-stripping), so a test file,
12
+ and what it imports, has to run on Node as it's written.
13
+
14
+ Use hypotes when you want Vitest's matchers, spies, module mocks and fake
15
+ timers, but node:test as the runner. A test file that uses what both have
16
+ moves between Vitest and hypotes by changing its imports. If you need what
17
+ only Vitest has, such as snapshots, browser mode or Vite's transforms, use
18
+ Vitest: [Left out](#left-out) lists what hypotes doesn't have.
17
19
 
18
20
  hypotes needs Node 24.13.1 or later.
19
21
 
@@ -90,7 +92,8 @@ which aren't the ones that Vitest runs:
90
92
  `*.spec.ts` there.
91
93
  - It doesn't run `*.spec.ts` outside a `test` directory, which Vitest does.
92
94
 
93
- 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.
94
97
 
95
98
  ## Mocking modules
96
99
 
@@ -271,9 +274,21 @@ it, apart from the differences below.
271
274
  - `beforeAll`, `afterAll`, `beforeEach` and `afterEach`.
272
275
  - `expect`, with Vitest's matchers and asymmetric matchers,
273
276
  `expect.extend()`, `expect.addEqualityTesters()` and `expect.fail()`.
274
- - `vi`, with these members: `fn`, `spyOn`, `mocked`, `isMockFunction`,
275
- `clearAllMocks`, `resetAllMocks`, `restoreAllMocks`, `mock`, `unmock`,
276
- `doMock`, `doUnmock`, `hoisted` and `importActual`.
277
+ - `vi`, with these members:
278
+ - For spies: `fn`, `spyOn`, `mocked`, `isMockFunction`, `clearAllMocks`,
279
+ `resetAllMocks` and `restoreAllMocks`.
280
+ - For module mocks: `mock`, `unmock`, `doMock`, `doUnmock`, `hoisted` and
281
+ `importActual`.
282
+ - For fake timers: `useFakeTimers`, `useRealTimers`, `isFakeTimers`,
283
+ `advanceTimersByTime`, `advanceTimersByTimeAsync`,
284
+ `advanceTimersToNextTimer`, `advanceTimersToNextTimerAsync`,
285
+ `advanceTimersToNextFrame`, `runAllTimers`, `runAllTimersAsync`,
286
+ `runOnlyPendingTimers`, `runOnlyPendingTimersAsync`, `runAllTicks`,
287
+ `getTimerCount`, `clearAllTimers`, `setSystemTime`,
288
+ `getMockedSystemTime`, `getRealSystemTime` and `setTimerTickMode`.
289
+ - For globals and environment variables: `stubGlobal`, `unstubAllGlobals`,
290
+ `stubEnv` and `unstubAllEnvs`.
291
+ - For waiting: `waitFor` and `waitUntil`.
277
292
 
278
293
  ### `hypotes/fast-check`
279
294
 
@@ -309,6 +324,16 @@ Lint rules for tests, as an oxlint JS plugin, which
309
324
  The preload that module mocks need, which [Mocking modules](#mocking-modules)
310
325
  describes.
311
326
 
327
+ ### `hypotes/cli`
328
+
329
+ The module of [the `hypotes` command](#the-hypotes-command), which runs as
330
+ it's imported. Run the command instead.
331
+
332
+ ### `hypotes/reporter`
333
+
334
+ A reporter for node:test that prints a row for each test file, with the name
335
+ of its package, which [Reporter](#reporter) describes.
336
+
312
337
  ## Left out
313
338
 
314
339
  hypotes leaves out these members of Vitest's API. node:test has some of them
@@ -328,9 +353,7 @@ in another form. Of `vi`, hypotes has only the members that
328
353
  | `toMatchSnapshot` and the other snapshot matchers, `expect.addSnapshotSerializer` | node:test's `t.assert.snapshot()` |
329
354
  | `expectTypeOf`, `assertType` | The `expect-type` package, which Vitest's `expectTypeOf` comes from |
330
355
  | `assert`, `chai`, `should` | The `chai` package, which Vitest's come from |
331
- | `vi.useFakeTimers`, `vi.setSystemTime` and the other members for timers | node:test's `mock.timers` |
332
- | `vi.stubGlobal` | node:test's `mock.property()`, for a global that exists |
333
- | `vi.stubEnv`, `vi.resetModules`, `vi.waitFor`, `vi.waitUntil` | None |
356
+ | `vi.resetModules` | None |
334
357
  | `vi.importMock`, `vi.mockObject`, automocking, `__mocks__` directories | A factory, as in `vi.mock(path, factory)` |
335
358
 
336
359
  ## Differences from Vitest
@@ -351,9 +374,10 @@ in another form. Of `vi`, hypotes has only the members that
351
374
  process. node:test runs each file in a process of its own, so that means
352
375
  the file's tests, as in Vitest. With `--test-isolation=none`, the files
353
376
  share one process, and the hook runs for the tests of them all.
354
- - **Timeouts.** A test or a hook has no timeout unless it's given one. Vitest
355
- fails a test after 5 seconds, and a hook after 10. Node's `--test-timeout`
356
- 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.
357
381
 
358
382
  ### Equality
359
383
 
@@ -363,6 +387,39 @@ compare as `toEqual` does, such as `toContainEqual`, `toHaveProperty` and
363
387
  `toHaveBeenCalledWith`. Two things that make values differ in Vitest are
364
388
  ignored: properties set on an array besides its elements, and symbol keys.
365
389
 
390
+ ### Fake timers, stubs and waits
391
+
392
+ The timers are Vitest's, on the version of
393
+ [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers) that Vitest
394
+ has, and take the options of
395
+ [`vi.useFakeTimers()`](https://vitest.dev/api/vi#vi-usefaketimers).
396
+ node:test's `mock.timers` is another clock, so a test fakes the timers with
397
+ one of the two.
398
+
399
+ - **Options.** Vitest reads the default options from `fakeTimers` in its
400
+ configuration. hypotes has no configuration, so each call of
401
+ `vi.useFakeTimers()` passes the options that it changes.
402
+ - **Nothing is undone between tests.** Vitest's `unstubGlobals` and
403
+ `unstubEnvs` options undo the stubs after each test. Here an `afterEach`
404
+ calls `vi.unstubAllGlobals()` and `vi.unstubAllEnvs()`, and
405
+ `vi.useRealTimers()` as in Vitest. With `--test-isolation=none`, test
406
+ files share a process, so fake timers and stubs that a file leaves stay
407
+ for the files that run after it.
408
+ - **A clock that moves by itself keeps a test file running.** With
409
+ `shouldAdvanceTime`, or a tick mode besides `manual`, the fake clock moves
410
+ on a real timer. node:test waits for it, so a file that leaves such a
411
+ clock on never ends. Call `vi.useRealTimers()` in an `afterEach` or an
412
+ `afterAll`. Vitest ends the file's worker instead, so the file ends there
413
+ without it.
414
+ - **`process.nextTick`.** `toFake: ['nextTick']` fakes it. Vitest throws
415
+ instead in its default pool, `forks`.
416
+ - **`import.meta.env`.** `vi.stubEnv()` changes `process.env`. Vitest changes
417
+ `import.meta.env` too, which Vite defines and Node doesn't.
418
+ - **A wait ends when it settles.** In Vitest, a `vi.waitUntil()` whose
419
+ function throws on its first call keeps calling the function until its
420
+ timeout, and moves fake timers forward each time, in later tests too.
421
+ hypotes stops calling it.
422
+
366
423
  ### Module mocks
367
424
 
368
425
  `hypotes/register` hoists the mocks of each ES module outside `node_modules`
@@ -413,6 +470,241 @@ report starts with:
413
470
  Messages have colours only where Node prints them: to a terminal, or with
414
471
  `FORCE_COLOR`, but not to a file or a pipe.
415
472
 
473
+ ## The `hypotes` command
474
+
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:
478
+
479
+ ```bash
480
+ npx hypotes
481
+ ```
482
+
483
+ ```bash
484
+ node --import hypotes/register --test --test-reporter=hypotes/reporter --test-timeout=5000 --test-force-exit "**/*.{test,spec}.?(c|m)[jt]s?(x)"
485
+ ```
486
+
487
+ node:test's flags work as they do with `node --test`, as in
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.
585
+
586
+ ### Running one project
587
+
588
+ In a repository of several packages, `--project` runs the test files of one
589
+ of them, by the `name` in its `package.json`, as Vitest's `--project` does:
590
+
591
+ ```bash
592
+ npx hypotes --project @shop/web
593
+ ```
594
+
595
+ ```text
596
+ ✓ |@shop/web| test/cart.test.js (1 test) 1ms
597
+
598
+ Test Files 1 passed (1)
599
+ Tests 1 passed (1)
600
+ Duration 131ms
601
+ ```
602
+
603
+ A file is in the project that [the reporter](#reporter) prints for it: the
604
+ nearest `package.json` above it that has a `name`.
605
+
606
+ | Command | Runs the test files of |
607
+ | --------------------------------------------------- | ------------------------------------- |
608
+ | `hypotes --project @shop/web` | `@shop/web` |
609
+ | `hypotes --project @shop/web --project @shop/api` | Both |
610
+ | `hypotes --project "@shop/*"` | Each project whose name starts so |
611
+ | `hypotes --project "!@shop/web"` | Each project but `@shop/web` |
612
+ | `hypotes --project @shop/web "**/*.spec.js"` | `@shop/web`, among those of a pattern |
613
+
614
+ node:test can't select files by their package, so with `--project` the
615
+ command names each selected project's directory to node:test, as a pattern.
616
+ node:test then finds the test files in it, by the same
617
+ [pattern](#test-files) as without `--project`.
618
+
619
+ - **Names match in any case.** `--project "@SHOP/web"` selects
620
+ `@shop/web`, as it does in Vitest.
621
+ - **No project matches.** The command fails, and lists the projects that it
622
+ found.
623
+
624
+ In two cases a directory's pattern would take in files of other projects,
625
+ so the command finds the project's files itself and names them one by one:
626
+
627
+ - with a pattern of your own, as in the last row of the table;
628
+ - for a project with another package inside its directory that isn't
629
+ selected, such as the root package of a repository.
630
+
631
+ That has costs:
632
+
633
+ - **`--watch` watches the files that it found.** A test file added later
634
+ runs after a restart.
635
+ - **A command can only be so long.** Each file is an argument to Node.
636
+ macOS and Linux take about a megabyte of them, and Windows 32,767
637
+ characters, which a few hundred files can exceed. The command then fails,
638
+ and says so. Select fewer files, or select the packages inside the
639
+ project too.
640
+
641
+ ## Reporter
642
+
643
+ node:test's `spec` reporter prints each test, but not the file or the package
644
+ that it is in. In a repository of several packages, that makes a result hard
645
+ to place. `hypotes/reporter` prints a row for each test file instead, with
646
+ its project, as Vitest's default reporter does.
647
+
648
+ Pass it to node:test, from the root of the repository:
649
+
650
+ ```bash
651
+ node --test --test-reporter=hypotes/reporter
652
+ ```
653
+
654
+ With a test file in each of two packages, `@shop/api` and `@shop/web`, it
655
+ prints:
656
+
657
+ ```text
658
+ ✓ |@shop/api| test/price.test.js (2 tests) 1ms
659
+ ✓ |@shop/web| test/cart.test.js (1 test) 1ms
660
+
661
+ Test Files 2 passed (2)
662
+ Tests 3 passed (3)
663
+ Duration 138ms
664
+ ```
665
+
666
+ A file's project is the nearest `package.json` above it that has a `name`.
667
+ The file's path is from that package's directory. A file with no such
668
+ package above it has no project, and its path is from the working directory.
669
+
670
+ A file with a failure lists its failed tests. Their errors follow the files,
671
+ each under its file and the titles of its suites:
672
+
673
+ ```text
674
+ ❯ |@shop/api| test/price.test.js (2 tests | 1 failed) 2ms
675
+ × price > rounds up 1ms
676
+ ✓ |@shop/web| test/cart.test.js (1 test) 1ms
677
+
678
+ Failed Tests 1
679
+
680
+ FAIL |@shop/api| test/price.test.js > price > rounds up
681
+ Error [AssertionError]: expected 3 to be 2 // Object.is equality
682
+ ```
683
+
684
+ A file that fails as it loads, and a suite whose hook fails, aren't tests.
685
+ Their errors come first, under `Failed Suites`.
686
+
687
+ The error is printed as node:test's reporters print it, with its stack.
688
+
689
+ - **Colours.** Where Node prints colours, a project's name is on a coloured
690
+ background rather than between bars.
691
+ - **Other output.** What tests write to stdout and stderr, their
692
+ diagnostics, and the coverage report are printed as `spec` prints them.
693
+ The totals take the place of node:test's own.
694
+ - **Any node:test tests.** The reporter reads node:test's results, so it
695
+ reports tests declared with `node:test` too. It doesn't need
696
+ `hypotes/register`, and works with it.
697
+ - **When a row appears.** node:test reports a file's results in the order
698
+ that the files were found. A file's row is printed once the next file's
699
+ results start, so the row of a slow file holds back those after it.
700
+ - **Tests that a helper declares.** With `--test-isolation=none`, node:test
701
+ doesn't say which test file a test is from, only where it was declared.
702
+ Node 24.13.1 doesn't say it with any isolation. A test that a helper in
703
+ another module declares, as a rule tester does, is then reported under
704
+ that module, in a row of its own, which counts as a file in the totals.
705
+ - **No `--project`.** The reporter names projects, but doesn't select them.
706
+ [The `hypotes` command](#running-one-project) does.
707
+
416
708
  ## Lint rules
417
709
 
418
710
  `hypotes/oxlint` has lint rules for tests, as an
@@ -0,0 +1,4 @@
1
+ /** A member of `vi` that runs, and returns `vi` */
2
+ export declare function chained<Vi, Args extends unknown[]>(vi: () => Vi, run: (...args: Args) => void): (...args: Args) => Vi;
3
+ /** A member of `vi` that runs, and returns a promise of `vi` */
4
+ export declare function chainedAsync<Vi, Args extends unknown[]>(vi: () => Vi, run: (...args: Args) => Promise<void>): (...args: Args) => Promise<Vi>;
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};