hypotes 0.0.0-stage → 0.0.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/LICENSE +21 -0
- package/README.md +407 -2
- package/dist/equals.d.ts +9 -0
- package/dist/expect.d.ts +14 -0
- package/dist/fast-check.d.ts +26 -0
- package/dist/fast-check.js +32 -0
- package/dist/hoist.d.ts +6 -0
- package/dist/hooks.d.ts +16 -0
- package/dist/index.d.ts +51 -0
- package/dist/index.js +274 -0
- package/dist/mocks-ciQvBYVw.js +281 -0
- package/dist/mocks.d.ts +83 -0
- package/dist/oxlint/index.d.ts +9 -0
- package/dist/oxlint/index.js +831 -0
- package/dist/oxlint/rules.d.ts +16 -0
- package/dist/oxlint/types.d.ts +8 -0
- package/dist/register.d.ts +1 -0
- package/dist/register.js +309 -0
- package/dist/site.d.ts +20 -0
- package/dist/table.d.ts +5 -0
- package/dist/tests-D4v1ZaoR.js +266 -0
- package/dist/tests.d.ts +113 -0
- package/dist/title.d.ts +8 -0
- package/package.json +125 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 snovader
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
+
THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,408 @@
|
|
|
1
|
-
#
|
|
1
|
+
# hypotes
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Vitest's API on Node's test runner. Same tests, no Vite.
|
|
4
|
+
|
|
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.
|
|
17
|
+
|
|
18
|
+
hypotes needs Node 24.13.1 or later.
|
|
19
|
+
|
|
20
|
+
## Quick start
|
|
21
|
+
|
|
22
|
+
Install it:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install --save-dev hypotes
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The examples are ES modules, so the project's `package.json` needs
|
|
29
|
+
`"type": "module"`. With `"type": "commonjs"`, which npm 11's `npm init`
|
|
30
|
+
writes, Node rejects their `import` statements. Without a `type`, it runs
|
|
31
|
+
them, but warns about each test file.
|
|
32
|
+
|
|
33
|
+
Write a test, as `test/sum.test.ts`:
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { describe, expect, it, vi } from 'hypotes';
|
|
37
|
+
|
|
38
|
+
describe('sum', () => {
|
|
39
|
+
it('adds numbers', () => {
|
|
40
|
+
expect(1 + 2).toBe(3);
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
it.each([
|
|
44
|
+
[1, 1, 2],
|
|
45
|
+
[2, 3, 5]
|
|
46
|
+
])('%i + %i = %i', (a, b, sum) => {
|
|
47
|
+
expect(a + b).toBe(sum);
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
it('calls back', () => {
|
|
51
|
+
const callback = vi.fn<(value: number) => void>();
|
|
52
|
+
[1, 2].forEach(callback);
|
|
53
|
+
expect(callback).toHaveBeenCalledTimes(2);
|
|
54
|
+
});
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Run it:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
node --test
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
▶ sum
|
|
66
|
+
✔ adds numbers (0.451ms)
|
|
67
|
+
✔ 1 + 1 = 2 (0.072875ms)
|
|
68
|
+
✔ 2 + 3 = 5 (0.047792ms)
|
|
69
|
+
✔ calls back (0.352ms)
|
|
70
|
+
✔ sum (1.49425ms)
|
|
71
|
+
ℹ tests 4
|
|
72
|
+
ℹ suites 1
|
|
73
|
+
ℹ pass 4
|
|
74
|
+
ℹ fail 0
|
|
75
|
+
ℹ cancelled 0
|
|
76
|
+
ℹ skipped 0
|
|
77
|
+
ℹ todo 0
|
|
78
|
+
ℹ duration_ms 181.809417
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
That is all that tests without module mocks need. `node --test` takes
|
|
82
|
+
[its own options](https://nodejs.org/api/test.html), such as `--watch`.
|
|
83
|
+
|
|
84
|
+
It runs the files that
|
|
85
|
+
[node:test looks for](https://nodejs.org/api/test.html#running-tests-from-the-command-line),
|
|
86
|
+
which aren't the ones that Vitest runs:
|
|
87
|
+
|
|
88
|
+
- It runs `*.test.ts`, and every `.ts` and `.js` file in a `test` directory,
|
|
89
|
+
helpers and fixtures included. Vitest runs only `*.test.ts` and
|
|
90
|
+
`*.spec.ts` there.
|
|
91
|
+
- It doesn't run `*.spec.ts` outside a `test` directory, which Vitest does.
|
|
92
|
+
|
|
93
|
+
To run other files, name them, as in `node --test "**/*.spec.ts"`.
|
|
94
|
+
|
|
95
|
+
## Mocking modules
|
|
96
|
+
|
|
97
|
+
`vi.mock()` needs two more things: a preload, and two packages that the
|
|
98
|
+
preload uses to hoist the mocks.
|
|
99
|
+
|
|
100
|
+
Install the packages:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
npm install --save-dev oxc-parser magic-string
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Run the tests with the preload, `hypotes/register`:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
node --import hypotes/register --test
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
node:test passes the preload on to the process of each test file. It can
|
|
113
|
+
come from `NODE_OPTIONS` instead:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
NODE_OPTIONS='--import hypotes/register' node --test
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Only test files that mock modules need the preload, and it does no harm to
|
|
120
|
+
the others. Without it, `vi.mock()` and `vi.doMock()` throw an error that
|
|
121
|
+
names it.
|
|
122
|
+
|
|
123
|
+
A mock is written as for Vitest, here with `vi.hoisted()` and
|
|
124
|
+
`importOriginal`:
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
// src/greet.ts
|
|
128
|
+
import { readFileSync } from 'node:fs';
|
|
129
|
+
|
|
130
|
+
export function greeting(): string {
|
|
131
|
+
return `Hello, ${readFileSync('name.txt', 'utf8').trim()}!`;
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
// test/greet.test.ts
|
|
137
|
+
import { expect, it, vi } from 'hypotes';
|
|
138
|
+
import { greeting } from '../src/greet.ts';
|
|
139
|
+
|
|
140
|
+
const { readFileSync } = vi.hoisted(() => ({
|
|
141
|
+
readFileSync: vi.fn<(path: string, encoding: string) => string>(
|
|
142
|
+
() => 'Ada\n'
|
|
143
|
+
)
|
|
144
|
+
}));
|
|
145
|
+
|
|
146
|
+
vi.mock('node:fs', async importOriginal => ({
|
|
147
|
+
...(await importOriginal<typeof import('node:fs')>()),
|
|
148
|
+
readFileSync
|
|
149
|
+
}));
|
|
150
|
+
|
|
151
|
+
it('greets the name in the file', () => {
|
|
152
|
+
expect(greeting()).toBe('Hello, Ada!');
|
|
153
|
+
expect(readFileSync).toHaveBeenCalledWith('name.txt', 'utf8');
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Module mocks differ from Vitest's in a few ways, which
|
|
158
|
+
[Module mocks](#module-mocks) under the differences lists.
|
|
159
|
+
|
|
160
|
+
## Moving a test file from Vitest
|
|
161
|
+
|
|
162
|
+
1. Import from `hypotes` what the file imports from `vitest`, and from
|
|
163
|
+
`hypotes/fast-check` what it imports from `@fast-check/vitest`. hypotes
|
|
164
|
+
defines no globals, so a file that relied on Vitest's `globals` option
|
|
165
|
+
imports what it uses.
|
|
166
|
+
2. Check that Node runs the file, and what it imports, without Vite. Imports
|
|
167
|
+
name their files with the extension, as `./sum.ts`. Enums, path aliases
|
|
168
|
+
and JSX don't run, and neither does what Vite's plugins add.
|
|
169
|
+
[Type stripping](https://nodejs.org/api/typescript.html#type-stripping),
|
|
170
|
+
in Node's documentation, says what does.
|
|
171
|
+
3. Run it with `node --test`, which
|
|
172
|
+
[runs other files](#quick-start) than Vitest does. If it mocks modules,
|
|
173
|
+
set up [the preload](#mocking-modules) first.
|
|
174
|
+
4. Replace what [Left out](#left-out) lists. The table names what node:test
|
|
175
|
+
has instead.
|
|
176
|
+
5. Read [Differences from Vitest](#differences-from-vitest) for behaviour that
|
|
177
|
+
changes without an error, such as the order of after hooks, and tests
|
|
178
|
+
that have no timeout.
|
|
179
|
+
6. If the project lints its tests with oxlint's vitest rules, switch to
|
|
180
|
+
[`hypotes/oxlint`](#lint-rules).
|
|
181
|
+
|
|
182
|
+
## Entry points
|
|
183
|
+
|
|
184
|
+
What hypotes has works as [Vitest's API](https://vitest.dev/api/) documents
|
|
185
|
+
it, apart from the differences below.
|
|
186
|
+
|
|
187
|
+
### `hypotes`
|
|
188
|
+
|
|
189
|
+
- `describe` and `suite`, and `it` and `test`, with `.skip`, `.only`,
|
|
190
|
+
`.todo`, `.skipIf()`, `.runIf()`, `.each()` and `.for()`.
|
|
191
|
+
- Options for a test or a suite: `timeout`, `skip`, `todo`, `only`, and
|
|
192
|
+
node:test's `concurrency`. They come before the function, as in
|
|
193
|
+
`it('name', { timeout: 100 }, fn)`. A timeout alone can follow it, as in
|
|
194
|
+
`it('name', fn, 100)`.
|
|
195
|
+
- `beforeAll`, `afterAll`, `beforeEach` and `afterEach`.
|
|
196
|
+
- `expect`, with Vitest's matchers and asymmetric matchers,
|
|
197
|
+
`expect.extend()`, `expect.addEqualityTesters()` and `expect.fail()`.
|
|
198
|
+
- `vi`, with these members: `fn`, `spyOn`, `mocked`, `isMockFunction`,
|
|
199
|
+
`clearAllMocks`, `resetAllMocks`, `restoreAllMocks`, `mock`, `unmock`,
|
|
200
|
+
`doMock`, `doUnmock`, `hoisted` and `importActual`.
|
|
201
|
+
|
|
202
|
+
### `hypotes/fast-check`
|
|
203
|
+
|
|
204
|
+
Property tests, declared with `it.prop()` as `@fast-check/vitest` declares
|
|
205
|
+
them. It exports `it`, `test`, and fast-check's `fc`. A failure reports the
|
|
206
|
+
shrunk counterexample, with the seed and path that replay it.
|
|
207
|
+
|
|
208
|
+
It needs fast-check:
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
npm install --save-dev fast-check
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
import { expect } from 'hypotes';
|
|
216
|
+
import { fc, it } from 'hypotes/fast-check';
|
|
217
|
+
|
|
218
|
+
it.prop([fc.array(fc.integer())])('sorts in order', values => {
|
|
219
|
+
const sorted = values.toSorted((a, b) => a - b);
|
|
220
|
+
for (let index = 1; index < sorted.length; index++) {
|
|
221
|
+
expect(sorted[index - 1]).toBeLessThanOrEqual(sorted[index]);
|
|
222
|
+
}
|
|
223
|
+
});
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### `hypotes/oxlint`
|
|
227
|
+
|
|
228
|
+
Lint rules for tests, as an oxlint JS plugin, which
|
|
229
|
+
[Lint rules](#lint-rules) describes.
|
|
230
|
+
|
|
231
|
+
### `hypotes/register`
|
|
232
|
+
|
|
233
|
+
The preload that module mocks need, which [Mocking modules](#mocking-modules)
|
|
234
|
+
describes.
|
|
235
|
+
|
|
236
|
+
## Left out
|
|
237
|
+
|
|
238
|
+
hypotes leaves out these members of Vitest's API. node:test has some of them
|
|
239
|
+
in another form. Of `vi`, hypotes has only the members that
|
|
240
|
+
[`hypotes`](#hypotes) lists.
|
|
241
|
+
|
|
242
|
+
| Left out | Instead |
|
|
243
|
+
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
244
|
+
| `it.concurrent`, `describe.concurrent` | The `concurrency` option, as in `describe('name', { concurrency: true }, fn)` |
|
|
245
|
+
| `it.sequential`, `describe.sequential` | None: a file's tests run one at a time, unless `concurrency` says otherwise |
|
|
246
|
+
| `it.fails`, `it.extend`, `describe.shuffle` | None |
|
|
247
|
+
| The `retry`, `repeats` and `tags` options | None |
|
|
248
|
+
| `onTestFinished` | `t.after()`, on node:test's context |
|
|
249
|
+
| `onTestFailed`, `aroundEach`, `aroundAll`, `inject` | None |
|
|
250
|
+
| `expect.soft`, `expect.poll`, `expect.assertions`, `expect.hasAssertions` | None |
|
|
251
|
+
| `expect.unreachable` | `expect.fail()` |
|
|
252
|
+
| `toMatchSnapshot` and the other snapshot matchers, `expect.addSnapshotSerializer` | node:test's `t.assert.snapshot()` |
|
|
253
|
+
| `expectTypeOf`, `assertType` | The `expect-type` package, which Vitest's `expectTypeOf` comes from |
|
|
254
|
+
| `assert`, `chai`, `should` | The `chai` package, which Vitest's come from |
|
|
255
|
+
| `vi.useFakeTimers`, `vi.setSystemTime` and the other members for timers | node:test's `mock.timers` |
|
|
256
|
+
| `vi.stubGlobal` | node:test's `mock.property()`, for a global that exists |
|
|
257
|
+
| `vi.stubEnv`, `vi.resetModules`, `vi.waitFor`, `vi.waitUntil` | None |
|
|
258
|
+
| `vi.importMock`, `vi.mockObject`, automocking, `__mocks__` directories | A factory, as in `vi.mock(path, factory)` |
|
|
259
|
+
|
|
260
|
+
## Differences from Vitest
|
|
261
|
+
|
|
262
|
+
### Tests and hooks
|
|
263
|
+
|
|
264
|
+
- **Context.** A test's function gets node:test's context, with `t.mock` and
|
|
265
|
+
`t.assert`. Vitest's has `expect` and `task`.
|
|
266
|
+
- **`.only`.** Under `node --test`, `.only` does nothing unless `--test-only`
|
|
267
|
+
is passed too. It does apply when a file is run by itself, as
|
|
268
|
+
`node file.test.ts`.
|
|
269
|
+
- **`.todo`.** A `.todo` test that has a function runs. Its failure is
|
|
270
|
+
reported, but doesn't fail the run. Vitest doesn't run it.
|
|
271
|
+
- **Order of after hooks.** After hooks run in the order that they were
|
|
272
|
+
declared. So do the cleanups that `beforeAll` and `beforeEach` return.
|
|
273
|
+
Vitest runs both in reverse.
|
|
274
|
+
- **Hooks at the top of a file.** Such a hook runs for every test in the
|
|
275
|
+
process. node:test runs each file in a process of its own, so that means
|
|
276
|
+
the file's tests, as in Vitest. With `--test-isolation=none`, the files
|
|
277
|
+
share one process, and the hook runs for the tests of them all.
|
|
278
|
+
- **Timeouts.** A test or a hook has no timeout unless it's given one. Vitest
|
|
279
|
+
fails a test after 5 seconds, and a hook after 10. Node's `--test-timeout`
|
|
280
|
+
sets one for every test.
|
|
281
|
+
|
|
282
|
+
### Equality
|
|
283
|
+
|
|
284
|
+
`toEqual` and `toStrictEqual` compare arrays and typed arrays by their
|
|
285
|
+
elements alone, and objects by their string keys. So do the matchers that
|
|
286
|
+
compare as `toEqual` does, such as `toContainEqual`, `toHaveProperty` and
|
|
287
|
+
`toHaveBeenCalledWith`. Two things that make values differ in Vitest are
|
|
288
|
+
ignored: properties set on an array besides its elements, and symbol keys.
|
|
289
|
+
|
|
290
|
+
### Module mocks
|
|
291
|
+
|
|
292
|
+
`hypotes/register` hoists the mocks of each ES module outside `node_modules`
|
|
293
|
+
that calls `vi.mock()`, as Vitest's transform does. It differs in these ways:
|
|
294
|
+
|
|
295
|
+
- **Imports aren't live.** The module's imports become constants. If the
|
|
296
|
+
module that exports a binding reassigns it, the importer keeps the value
|
|
297
|
+
from when it was imported.
|
|
298
|
+
- **Factories run early.** All of a module's mock factories run before its
|
|
299
|
+
imports and dynamic imports, even for modules that are never imported.
|
|
300
|
+
Vitest runs each as its mocked module loads.
|
|
301
|
+
- **No `export * from`.** A module that calls `vi.mock()` can't
|
|
302
|
+
`export * from` another module, which would load before the mocks. It can
|
|
303
|
+
export by name, or with `export * as`.
|
|
304
|
+
- **Top-level statements.** `vi.mock()`, `vi.unmock()` and `vi.hoisted()`
|
|
305
|
+
must each be a statement of its own, at the top level of the module. The
|
|
306
|
+
statement can declare what `vi.hoisted()` returns, but nothing else.
|
|
307
|
+
- **`vi` by name.** `vi` must be imported from `hypotes`, as `vi`.
|
|
308
|
+
- **No CommonJS.** A CommonJS module can't call `vi.mock()`.
|
|
309
|
+
- **Mocks last.** A mock lasts for the rest of the process. `vi.doUnmock()`
|
|
310
|
+
ends it, and so does disposing what `vi.doMock()` returns. With
|
|
311
|
+
`--test-isolation=none`, test files share a process, so a mock leaks into
|
|
312
|
+
the files that run after the one that made it.
|
|
313
|
+
- **`require()` and dependencies.** A mock applies wherever the module is
|
|
314
|
+
loaded in the process: by `require()` too, and by the packages in
|
|
315
|
+
`node_modules`, when they import it. Vitest's mocks reach neither. Mocking
|
|
316
|
+
`node:fs` changes what a CommonJS dependency gets from
|
|
317
|
+
`require('node:fs')`. `require()` of a mocked CommonJS package returns the
|
|
318
|
+
mock's namespace, `{ default }`, rather than its default export.
|
|
319
|
+
|
|
320
|
+
## Failure output
|
|
321
|
+
|
|
322
|
+
node:test's reporters print an error's message, its stack, and its `actual`
|
|
323
|
+
and `expected` values, but not the diff that Vitest's does. So a failed
|
|
324
|
+
matcher that compares values carries the diff in its message, which the
|
|
325
|
+
report starts with:
|
|
326
|
+
|
|
327
|
+
```text
|
|
328
|
+
✖ compares a user (1.534167ms)
|
|
329
|
+
Error [AssertionError]: expected { name: 'Ada', …(2) } to deeply equal { name: 'Ada', …(2) }
|
|
330
|
+
|
|
331
|
+
+ actual - expected
|
|
332
|
+
|
|
333
|
+
+ { age: 36, name: 'Ada', roles: [ 'admin', 'dev' ] }
|
|
334
|
+
- { age: 36, name: 'Ada', roles: [ 'admin' ] }
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
Messages have colours only where Node prints them: to a terminal, or with
|
|
338
|
+
`FORCE_COLOR`, but not to a file or a pipe.
|
|
339
|
+
|
|
340
|
+
## Lint rules
|
|
341
|
+
|
|
342
|
+
`hypotes/oxlint` has lint rules for tests, as an
|
|
343
|
+
[oxlint](https://oxc.rs/docs/guide/usage/linter) JS plugin. oxlint's own
|
|
344
|
+
vitest rules see only what a file imports from `vitest`, so these take their
|
|
345
|
+
place. They see the tests and suites declared through `hypotes`,
|
|
346
|
+
`hypotes/fast-check` and `node:test`, the assertions of hypotes' `expect`,
|
|
347
|
+
and hypotes' `vi`.
|
|
348
|
+
|
|
349
|
+
Load them in `.oxlintrc.json`, with the rules that you want:
|
|
350
|
+
|
|
351
|
+
```json
|
|
352
|
+
{
|
|
353
|
+
"jsPlugins": ["hypotes/oxlint"],
|
|
354
|
+
"rules": {
|
|
355
|
+
"hypotes/no-focused-tests": "error",
|
|
356
|
+
"hypotes/no-disabled-tests": "warn",
|
|
357
|
+
"hypotes/warn-todo": "warn",
|
|
358
|
+
"hypotes/no-conditional-tests": "error",
|
|
359
|
+
"hypotes/valid-title": "error",
|
|
360
|
+
"hypotes/valid-describe-callback": "error",
|
|
361
|
+
"hypotes/expect-expect": "error",
|
|
362
|
+
"hypotes/no-standalone-expect": "error",
|
|
363
|
+
"hypotes/valid-expect": "error",
|
|
364
|
+
"hypotes/valid-expect-in-promise": "error",
|
|
365
|
+
"hypotes/require-to-throw-message": "error",
|
|
366
|
+
"hypotes/prefer-to-be": "error",
|
|
367
|
+
"hypotes/prefer-to-have-length": "error",
|
|
368
|
+
"hypotes/hoisted-apis-on-top": "error",
|
|
369
|
+
"hypotes/require-mock-type-parameters": "error"
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
The rules take no options. Those marked "fix" are fixed by `--fix`.
|
|
375
|
+
|
|
376
|
+
Rules for how tests are declared:
|
|
377
|
+
|
|
378
|
+
| Rule | What it checks |
|
|
379
|
+
| ------------------------- | -------------------------------------------------------------------------------------- |
|
|
380
|
+
| `no-focused-tests` | No `.only`, and no `only` option. |
|
|
381
|
+
| `no-disabled-tests` | No `.skip`, no `skip` option, and no test without a function. |
|
|
382
|
+
| `warn-todo` | No `.todo`, and no `todo` option. |
|
|
383
|
+
| `no-conditional-tests` | No test or suite declared in an `if` statement. `skipIf()` and `runIf()` do that. |
|
|
384
|
+
| `valid-title` | A title has text, no spaces around it, and doesn't start with `it` or `describe`. Fix. |
|
|
385
|
+
| `valid-describe-callback` | A suite's function is written in place, and returns nothing. It takes no parameters. |
|
|
386
|
+
|
|
387
|
+
Rules for assertions:
|
|
388
|
+
|
|
389
|
+
| Rule | What it checks |
|
|
390
|
+
| -------------------------- | ----------------------------------------------------------------------------------------- |
|
|
391
|
+
| `expect-expect` | Each test calls `expect()`, or a function whose name starts with `expect`. |
|
|
392
|
+
| `no-standalone-expect` | `expect()` runs in a test or in a function, not in a suite or at the top of a module. |
|
|
393
|
+
| `valid-expect` | A matcher is called on `expect()`, and `.resolves` or `.rejects` is awaited or returned. |
|
|
394
|
+
| `valid-expect-in-promise` | A promise whose callback calls `expect()`, as in `.then()`, is awaited or returned. |
|
|
395
|
+
| `require-to-throw-message` | `toThrow()` and `toThrowError()` say what the error should be, unless they follow `.not`. |
|
|
396
|
+
| `prefer-to-be` | `toBe()` for a primitive, and `toBeNull()` and its like, rather than `toEqual()`. Fix. |
|
|
397
|
+
| `prefer-to-have-length` | `expect(values).toHaveLength(n)`, rather than comparing `values.length` with `n`. Fix. |
|
|
398
|
+
|
|
399
|
+
Rules for mocks:
|
|
400
|
+
|
|
401
|
+
| Rule | What it checks |
|
|
402
|
+
| ------------------------------ | ----------------------------------------------------------------------------------------- |
|
|
403
|
+
| `hoisted-apis-on-top` | `vi.mock()`, `vi.unmock()` and `vi.hoisted()` are top-level statements, where they hoist. |
|
|
404
|
+
| `require-mock-type-parameters` | `vi.fn()` is given the type of the function that it mocks, in TypeScript. |
|
|
405
|
+
|
|
406
|
+
## License
|
|
407
|
+
|
|
408
|
+
[MIT](LICENSE)
|
package/dist/equals.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { type Tester } from '@vitest/expect';
|
|
2
|
+
/**
|
|
3
|
+
* Whether `a` and `b` are equal as `equals` compares them with the testers
|
|
4
|
+
* of `toEqual` or of `toStrictEqual`, strictly or not, or undefined to leave
|
|
5
|
+
* them to `equals`. It leaves them all to it with testers of other matchers,
|
|
6
|
+
* such as `toMatchObject`, or other custom testers, whose results it couldn't
|
|
7
|
+
* know.
|
|
8
|
+
*/
|
|
9
|
+
export declare const fastEquality: Tester;
|
package/dist/expect.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { type Assertion, type AsymmetricMatchersContaining, type ExpectStatic, type Tester } from '@vitest/expect';
|
|
2
|
+
/**
|
|
3
|
+
* Vitest's `expect`, with its matchers, such as `toStrictEqual`, its
|
|
4
|
+
* asymmetric matchers, such as `expect.any`, `extend` and
|
|
5
|
+
* `addEqualityTesters`, and `fail`, which it has from chai's. The members
|
|
6
|
+
* that need Vitest's runner, such as `expect.soft` and `expect.assertions`,
|
|
7
|
+
* aren't here.
|
|
8
|
+
*/
|
|
9
|
+
export interface Expect extends AsymmetricMatchersContaining, Pick<ExpectStatic, 'any' | 'anything' | 'extend' | 'fail' | 'not'> {
|
|
10
|
+
<T>(actual: T, message?: string): Assertion<void, T>;
|
|
11
|
+
/** Adds testers, which `toEqual` and other matchers try first */
|
|
12
|
+
addEqualityTesters: (testers: Tester[]) => void;
|
|
13
|
+
}
|
|
14
|
+
export declare const expect: Expect;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import * as fc from 'fast-check';
|
|
2
|
+
import { type Declare, type TestAPI } from './tests.ts';
|
|
3
|
+
export { fc };
|
|
4
|
+
type Awaitable<T> = PromiseLike<T> | T;
|
|
5
|
+
/** A property's predicate, which fails it by throwing or returning false */
|
|
6
|
+
type Predicate<Values extends unknown[]> = (...values: Values) => Awaitable<boolean | void>;
|
|
7
|
+
export interface PropAPI {
|
|
8
|
+
/**
|
|
9
|
+
* Declares a test of a property, which checks the predicate against the
|
|
10
|
+
* values of the arbitraries, in a tuple or a record. A failure reports
|
|
11
|
+
* the counterexample, shrunk, with the seed and path that replay it. An
|
|
12
|
+
* async predicate runs as an async property.
|
|
13
|
+
*
|
|
14
|
+
* it.prop([fc.nat(), fc.string()])('should ...', (count, text) => { ... });
|
|
15
|
+
* it.prop({ count: fc.nat() })('should ...', ({ count }) => { ... });
|
|
16
|
+
*/
|
|
17
|
+
prop<Values extends [unknown, ...unknown[]]>(arbitraries: {
|
|
18
|
+
[K in keyof Values]: fc.Arbitrary<Values[K]>;
|
|
19
|
+
}, parameters?: fc.Parameters<Values>): Declare<Predicate<Values>>;
|
|
20
|
+
prop<Values extends Record<string, unknown>>(arbitraries: {
|
|
21
|
+
[K in keyof Values]: fc.Arbitrary<Values[K]>;
|
|
22
|
+
}, parameters?: fc.Parameters<[Values]>): Declare<Predicate<[Values]>>;
|
|
23
|
+
}
|
|
24
|
+
/** `it` and `test`, whose modifiers, such as `skip`, have `prop` too */
|
|
25
|
+
export declare const it: TestAPI<PropAPI> & PropAPI;
|
|
26
|
+
export declare const test: TestAPI<PropAPI> & PropAPI;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { i as parseArguments, s as callerSite, t as createTestAPI } from "./tests-D4v1ZaoR.js";
|
|
2
|
+
import * as fc from "fast-check";
|
|
3
|
+
// source/fast-check.ts
|
|
4
|
+
/** `it` and `test`, whose modifiers, such as `skip`, have `prop` too */
|
|
5
|
+
const it = createTestAPI((define) => ({ prop: (arbitraries, parameters) => (name, first, second) => {
|
|
6
|
+
const site = callerSite();
|
|
7
|
+
const { fn: predicate, options } = parseArguments(first, second);
|
|
8
|
+
define(name, options, predicate && (() => assertProperty(name, arbitraries, parameters, predicate)), site);
|
|
9
|
+
} }));
|
|
10
|
+
const test = it;
|
|
11
|
+
/**
|
|
12
|
+
* Runs the property, async if its predicate is an async function, which
|
|
13
|
+
* fast-check has to await
|
|
14
|
+
*/
|
|
15
|
+
function assertProperty(name, arbitraries, parameters, predicate) {
|
|
16
|
+
const values = Array.isArray(arbitraries) ? arbitraries : [fc.record(arbitraries)];
|
|
17
|
+
if (Object.prototype.toString.call(predicate) === "[object AsyncFunction]") {
|
|
18
|
+
const property = fc.asyncProperty(...values, predicate);
|
|
19
|
+
return fc.assert(property, parameters);
|
|
20
|
+
}
|
|
21
|
+
const property = fc.property(...values, (...args) => checkSync(name, predicate(...args)));
|
|
22
|
+
fc.assert(property, parameters);
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* A synchronous property's result, which a promise isn't: fast-check would
|
|
26
|
+
* take it as passing without awaiting it
|
|
27
|
+
*/
|
|
28
|
+
function checkSync(name, result) {
|
|
29
|
+
if (typeof result?.then === "function") throw new TypeError(`The predicate of "${name}" returned a promise, which only an async function's is awaited`);
|
|
30
|
+
return result;
|
|
31
|
+
}
|
|
32
|
+
export { fc, it, test };
|
package/dist/hoist.d.ts
ADDED
package/dist/hooks.d.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import * as nodeTest from 'node:test';
|
|
2
|
+
type Awaitable<T> = PromiseLike<T> | T;
|
|
3
|
+
/** A hook, which can return a function that cleans up after it */
|
|
4
|
+
export type Hook<Context> = (context: Context) => Awaitable<(() => Awaitable<unknown>) | void>;
|
|
5
|
+
/** A hook, which runs after the tests or each test */
|
|
6
|
+
export type AfterHook<Context> = (context: Context) => Awaitable<unknown>;
|
|
7
|
+
type HookContext = nodeTest.SuiteContext | nodeTest.TestContext;
|
|
8
|
+
/** Runs the hook before the suite's tests, and its cleanup after them */
|
|
9
|
+
export declare function beforeAll(fn: Hook<HookContext>, timeout?: number): void;
|
|
10
|
+
/** Runs the hook after the suite's tests */
|
|
11
|
+
export declare function afterAll(fn: AfterHook<HookContext>, timeout?: number): void;
|
|
12
|
+
/** Runs the hook before each of the suite's tests, and its cleanup after it */
|
|
13
|
+
export declare function beforeEach(fn: Hook<nodeTest.TestContext>, timeout?: number): void;
|
|
14
|
+
/** Runs the hook after each of the suite's tests */
|
|
15
|
+
export declare function afterEach(fn: AfterHook<nodeTest.TestContext>, timeout?: number): void;
|
|
16
|
+
export {};
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { clearAllMocks, fn, isMockFunction, resetAllMocks, restoreAllMocks, spyOn, type MaybeMocked, type MaybeMockedDeep, type MaybePartiallyMocked, type MaybePartiallyMockedDeep } from '@vitest/spy';
|
|
2
|
+
import { doMock, doUnmock, hoisted, importActual, mock, unmock } from './mocks.ts';
|
|
3
|
+
export { expect, type Expect } from './expect.ts';
|
|
4
|
+
export { afterAll, afterEach, beforeAll, beforeEach, type AfterHook, type Hook } from './hooks.ts';
|
|
5
|
+
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
|
+
export type { MockFactoryWithHelper } from './mocks.ts';
|
|
7
|
+
export type { Mock, MockInstance } from '@vitest/spy';
|
|
8
|
+
/**
|
|
9
|
+
* Returns the value, typed as its mock: a type helper, for what `vi.mock()`
|
|
10
|
+
* or `vi.spyOn()` mocked, as in `vi.mocked(module.fn).mockReturnValue(1)`.
|
|
11
|
+
* With `deep`, its nested functions are typed as mocks too, and with
|
|
12
|
+
* `partial`, their implementations can return part of what they would.
|
|
13
|
+
*/
|
|
14
|
+
declare function mocked<T>(item: T, deep?: false): MaybeMocked<T>;
|
|
15
|
+
declare function mocked<T>(item: T, deep: true): MaybeMockedDeep<T>;
|
|
16
|
+
declare function mocked<T>(item: T, options: {
|
|
17
|
+
partial?: false;
|
|
18
|
+
deep?: false;
|
|
19
|
+
}): MaybeMocked<T>;
|
|
20
|
+
declare function mocked<T>(item: T, options: {
|
|
21
|
+
partial?: false;
|
|
22
|
+
deep: true;
|
|
23
|
+
}): MaybeMockedDeep<T>;
|
|
24
|
+
declare function mocked<T>(item: T, options: {
|
|
25
|
+
partial: true;
|
|
26
|
+
deep?: false;
|
|
27
|
+
}): MaybePartiallyMocked<T>;
|
|
28
|
+
declare function mocked<T>(item: T, options: {
|
|
29
|
+
partial: true;
|
|
30
|
+
deep: true;
|
|
31
|
+
}): 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;
|
|
39
|
+
doMock: typeof doMock;
|
|
40
|
+
doUnmock: typeof doUnmock;
|
|
41
|
+
fn: typeof fn;
|
|
42
|
+
hoisted: typeof hoisted;
|
|
43
|
+
importActual: typeof importActual;
|
|
44
|
+
isMockFunction: typeof isMockFunction;
|
|
45
|
+
mock: typeof mock;
|
|
46
|
+
mocked: typeof mocked;
|
|
47
|
+
resetAllMocks: typeof resetAllMocks;
|
|
48
|
+
restoreAllMocks: typeof restoreAllMocks;
|
|
49
|
+
spyOn: typeof spyOn;
|
|
50
|
+
unmock: typeof unmock;
|
|
51
|
+
};
|