@aljazmc/testero 0.4.2 → 0.5.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 +109 -91
- package/bin/main.js +1427 -472
- package/bin/types/arguments.d.ts +5 -1
- package/bin/types/coverage.d.ts +63 -0
- package/bin/types/expect/assertion.d.ts +5 -2
- package/bin/types/expect/equality.d.ts +2 -0
- package/bin/types/expect/matchers.d.ts +1 -1
- package/bin/types/reporter.d.ts +3 -0
- package/bin/types/rules.d.ts +9 -0
- package/bin/types/runner.d.ts +5 -0
- package/bin/types/transformer.d.ts +9 -1
- package/bin/types/watcher.d.ts +52 -0
- package/package.json +2 -3
package/README.md
CHANGED
|
@@ -1,35 +1,72 @@
|
|
|
1
1
|
    
|
|
2
2
|
|
|
3
|
-
# testero
|
|
3
|
+
# > testero
|
|
4
4
|
|
|
5
|
-
A simple, [Jest](https://jestjs.io)-like test runner for JavaScript,
|
|
6
|
-
|
|
7
|
-
Easy to understand, easy to customize and easy to
|
|
5
|
+
A simple, [Jest](https://jestjs.io)-like test runner for JavaScript, JSX
|
|
6
|
+
and TypeScript, compiling tests with [esbuild](https://esbuild.github.io),
|
|
7
|
+
its only dependency. Easy to understand, easy to customize and easy to
|
|
8
|
+
extend.
|
|
8
9
|
|
|
9
|
-
##
|
|
10
|
+
## > Features
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
| Feature | Description |
|
|
13
|
+
| ------------------ | ----------------------------------------------------------------------- |
|
|
14
|
+
| Async tests | Tests and hooks may return promises or take a `done` callback. |
|
|
15
|
+
| Coverage | Lines and functions the tests ran, from V8, as a table and `lcov.info`. |
|
|
16
|
+
| Isolation | Each file is bundled on its own, with fresh imports and restored spies. |
|
|
17
|
+
| Jest compatibility | Same globals, matchers and config names, `@jest/globals` imports work. |
|
|
18
|
+
| Mocks | `fn`, `spyOn` and clearing, resetting and restoring of all mocks. |
|
|
19
|
+
| Readable failures | Message, diff of expected and received values, and the failing code. |
|
|
20
|
+
| TypeScript types | `@aljazmc/testero/globals` replaces `@types/jest`. |
|
|
21
|
+
| Watch mode | Reruns the tests of changed files, or all of them, as files change. |
|
|
16
22
|
|
|
17
|
-
##
|
|
23
|
+
## > Install
|
|
18
24
|
|
|
19
25
|
```sh
|
|
20
|
-
|
|
21
|
-
testero math unit/ # run the test files whose path matches a pattern
|
|
22
|
-
testero -t "adds numbers" # run the tests whose full name matches
|
|
23
|
-
testero --verbose --bail # list every test, stop at the first failing file
|
|
24
|
-
testero --listTests # print the test files instead of running them
|
|
25
|
-
testero --config # write the defaults to testero.config.ts, --config js to testero.config.js
|
|
26
|
-
testero --help # show every option
|
|
26
|
+
npm install --save-dev @aljazmc/testero
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
Requires Node.js 22.18+, 24.2+, 25 or 26.
|
|
30
|
+
|
|
31
|
+
## > Usage
|
|
32
|
+
|
|
33
|
+
| Command | Description |
|
|
34
|
+
| ----------------------- | --------------------------------------------------- |
|
|
35
|
+
| `testero` | Runs every test file. |
|
|
36
|
+
| `testero <pattern>…` | Runs the test files whose path matches a pattern. |
|
|
37
|
+
| `testero --bail` | Stops at the first failing file. |
|
|
38
|
+
| `testero --config [js]` | Writes the defaults to `testero.config.ts` (`.js`). |
|
|
39
|
+
| `testero --coverage` | Also reports the coverage of the sources. |
|
|
40
|
+
| `testero --help` | Shows every option. |
|
|
41
|
+
| `testero --listTests` | Prints the test files instead of running them. |
|
|
42
|
+
| `testero --verbose` | Lists every test. |
|
|
43
|
+
| `testero -t <name>` | Runs the tests whose full name matches. |
|
|
44
|
+
| `testero --watch` | Reruns the tests a changed file concerns. |
|
|
45
|
+
| `testero --watchAll` | Reruns all tests when a file changes. |
|
|
46
|
+
|
|
47
|
+
`--watch` reruns a changed test file, and the ones that import a changed
|
|
48
|
+
file, directly or not; `--watchAll` reruns every test file. Both run all
|
|
49
|
+
of them first, then on changes to sources and JSON files that are not
|
|
50
|
+
ignored. Each run is a process of its own, a change during a run restarts
|
|
51
|
+
it. Press `a` to run all tests, Enter to run the last ones again and `q`
|
|
52
|
+
to quit.
|
|
53
|
+
|
|
54
|
+
`--coverage` prints the lines and functions of each source the tests ran,
|
|
55
|
+
and writes them to `lcov.info` in `coverageDirectory`. Test files and
|
|
56
|
+
installed packages are left out; `collectCoverageFrom` limits the sources
|
|
57
|
+
and adds the ones no test loads.
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
---------------|---------|---------|------------------
|
|
61
|
+
File | % Funcs | % Lines | Uncovered Line #s
|
|
62
|
+
---------------|---------|---------|------------------
|
|
63
|
+
All files | 66.66 | 50 |
|
|
64
|
+
src/branch.ts | 50 | 44.44 | 3-4,7-9
|
|
65
|
+
src/math.ts | 100 | 100 |
|
|
66
|
+
---------------|---------|---------|------------------
|
|
67
|
+
```
|
|
30
68
|
|
|
31
|
-
|
|
32
|
-
globals as Jest:
|
|
69
|
+
## > Writing tests
|
|
33
70
|
|
|
34
71
|
```ts
|
|
35
72
|
import { add } from "../src/math.ts";
|
|
@@ -37,10 +74,6 @@ import { add } from "../src/math.ts";
|
|
|
37
74
|
describe("add", () => {
|
|
38
75
|
beforeEach(() => testero.clearAllMocks()); // `jest` works too
|
|
39
76
|
|
|
40
|
-
test("adds numbers", () => {
|
|
41
|
-
expect(add(1, 2)).toBe(3);
|
|
42
|
-
});
|
|
43
|
-
|
|
44
77
|
test.each([
|
|
45
78
|
[1, 1, 2],
|
|
46
79
|
[2, 2, 4],
|
|
@@ -56,89 +89,74 @@ describe("add", () => {
|
|
|
56
89
|
});
|
|
57
90
|
```
|
|
58
91
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `expect`
|
|
64
|
-
| `expect.any`, `expect.
|
|
65
|
-
| `
|
|
92
|
+
| Global | Description |
|
|
93
|
+
| -------------------------------------------------- | --------------------------------------------------------------------- |
|
|
94
|
+
| `beforeAll`, `afterAll`, `beforeEach`, `afterEach` | Run code around the tests of a suite. |
|
|
95
|
+
| `describe`, `test`, `it` | Suites and tests, with `.each`, `.only`, `.skip` and `test.todo`. |
|
|
96
|
+
| `expect` | Jest's matchers, `.not`, `.resolves`, `.rejects` and `expect.extend`. |
|
|
97
|
+
| `expect.any`, `expect.objectContaining`, … | Asymmetric matchers, also as `expect.not.*`. |
|
|
98
|
+
| `fdescribe`, `fit`, `xdescribe`, `xit`, `xtest` | Focused and skipped aliases. |
|
|
99
|
+
| `testero`, `jest` | Mocks, and `setTimeout` for the tests of a file. |
|
|
66
100
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
Imports from `@jest/globals` get the same functions.
|
|
101
|
+
For the types, add `"@aljazmc/testero/globals"` to `compilerOptions.types`
|
|
102
|
+
in `tsconfig.json`.
|
|
70
103
|
|
|
71
|
-
|
|
72
|
-
received values, and the code where it happened.
|
|
104
|
+
## > Configuration
|
|
73
105
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
`types` of your `tsconfig.json`, instead of `@types/jest`:
|
|
78
|
-
|
|
79
|
-
```json
|
|
80
|
-
{
|
|
81
|
-
"compilerOptions": {
|
|
82
|
-
"types": ["node", "@aljazmc/testero/globals"]
|
|
83
|
-
}
|
|
84
|
-
}
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
## Configuration
|
|
88
|
-
|
|
89
|
-
testero reads `testero.config.ts` or `testero.config.js` from the
|
|
90
|
-
current directory, with Jest's names and defaults. Objects are merged
|
|
91
|
-
deeply into the defaults, and anything else, like `ignore`, replaces
|
|
92
|
-
them:
|
|
106
|
+
`testero.config.ts` (or `.js`) in the current directory overrides the
|
|
107
|
+
defaults, using Jest's names: objects are merged deeply, anything else,
|
|
108
|
+
like `ignore`, is replaced.
|
|
93
109
|
|
|
94
110
|
```js
|
|
95
111
|
export default {
|
|
96
112
|
ignore: [".git", "node_modules"],
|
|
97
|
-
rules: {
|
|
98
|
-
testMatch: ["**/tests/**/*.test.ts"],
|
|
99
|
-
clearMocks: true,
|
|
100
|
-
},
|
|
113
|
+
rules: { clearMocks: true, testMatch: ["**/tests/**/*.test.ts"] },
|
|
101
114
|
};
|
|
102
115
|
```
|
|
103
116
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
|
108
|
-
|
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
|
|
118
|
-
## How it works
|
|
117
|
+
| Option | Default | Description |
|
|
118
|
+
| --------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
119
|
+
| `bail` | `false` | Stops after the first failing test file. |
|
|
120
|
+
| `clearMocks` | `false` | Clears the calls of every mock before each test. |
|
|
121
|
+
| `collectCoverage` | `false` | Reports coverage, like `--coverage`. |
|
|
122
|
+
| `collectCoverageFrom` | `[]` | Globs of the sources coverage is reported for, "!" excludes; empty takes the ones the tests load. |
|
|
123
|
+
| `coverageDirectory` | `"coverage"` | Where `lcov.info` goes. |
|
|
124
|
+
| `passWithNoTests` | `false` | Succeeds when there are no test files. |
|
|
125
|
+
| `resetMocks` | `false` | Also removes mock implementations. |
|
|
126
|
+
| `restoreMocks` | `false` | Also restores the original functions of spies. |
|
|
127
|
+
| `testMatch` | `__tests__` and `*.{spec,test}.*` | Globs of test files, the last match decides. |
|
|
128
|
+
| `testTimeout` | `5000` | Milliseconds a test or hook may take. |
|
|
129
|
+
| `verbose` | `false` | Lists every test, not only the failing ones. |
|
|
130
|
+
|
|
131
|
+
## > How it works
|
|
119
132
|
|
|
120
133
|
```
|
|
121
134
|
test file
|
|
122
135
|
├─> src/transformer.ts bundles it with esbuild, injecting the globals
|
|
123
136
|
├─> src/collector.ts collects its suites and tests into a tree
|
|
124
137
|
├─> src/runner.ts runs them, with hooks, timeouts and done callbacks
|
|
125
|
-
|
|
138
|
+
├─> src/reporter.ts prints the results like Jest does
|
|
139
|
+
└─> src/coverage.ts maps V8's counts back to the sources, with --coverage
|
|
126
140
|
```
|
|
127
141
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
142
|
+
| Module | Description |
|
|
143
|
+
| -------------------- | --------------------------------------------------------------- |
|
|
144
|
+
| `@aljazmc/config` | Loads `testero.config.ts`, finds files and matches `testMatch`. |
|
|
145
|
+
| `src/collector.ts` | Collects `describe`, `test` and hooks into a suite tree. |
|
|
146
|
+
| `src/coverage.ts` | V8 coverage of the bundles, by their source maps, and lcov. |
|
|
147
|
+
| `src/expect` | `expect`, matchers, deep equality and value diffs. |
|
|
148
|
+
| `src/mock.ts` | Mock functions and spies. |
|
|
149
|
+
| `src/reporter.ts` | Prints results like Jest's default reporter. |
|
|
150
|
+
| `src/runner.ts` | Runs tests with focus, skips, hooks and timeouts. |
|
|
151
|
+
| `src/testero.ts` | Finds test files and runs them one after another. |
|
|
152
|
+
| `src/transformer.ts` | Bundles test files with esbuild, packages stay external. |
|
|
153
|
+
| `src/watcher.ts` | Reruns tests on changes, finding the ones a change concerns. |
|
|
154
|
+
|
|
155
|
+
Test files run sequentially in one process. There are no workers, module
|
|
156
|
+
mocks, fake timers or snapshots. Coverage counts lines and functions, not
|
|
157
|
+
statements or branches; functions inside one that never ran are not
|
|
158
|
+
counted, as V8 does not know them yet.
|
|
159
|
+
|
|
160
|
+
## > License
|
|
143
161
|
|
|
144
162
|
MIT, see [LICENSE](LICENSE).
|