Skip to content

Commit 0ea7123

Browse files
hi-ogawahi-ogawa
authored
Merge branch 'main' into 02-04-fix_fix_ssr_environment_runner_in_project
2 parents 8dfc5ea + da85a32 commit 0ea7123

File tree

98 files changed

+5515
-1902
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

98 files changed

+5515
-1902
lines changed

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ Vitest is a next-generation testing framework powered by Vite. This is a monorep
3535
- **Core directory test**: `CI=true pnpm test <test-file>` (for `test/core`)
3636
- **Browser tests**: `CI=true pnpm test:browser:playwright` or `CI=true pnpm test:browser:webdriverio`
3737

38+
When writing tests, AVOID using `toContain` for validation. Prefer using `toMatchInlineSnapshot` to include the test error and its stack. If snapshot is failing, update the snapshot instead of reverting it to `toContain`.
39+
40+
If you need to typecheck tests, run `pnpm typecheck` from the root of the workspace.
41+
3842
### Testing Utilities
3943
- **`runInlineTests`** from `test/test-utils/index.ts` - You must use this for complex file system setups (>1 file)
4044
- **`runVitest`** from `test/test-utils/index.ts` - You can use this to run Vitest programmatically

‎docs/api/expect.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -779,7 +779,7 @@ test('the number of elements must match exactly', () => {
779779

780780
## toThrowError
781781

782-
- **Type:** `(received: any) => Awaitable<void>`
782+
- **Type:** `(expected?: any) => Awaitable<void>`
783783

784784
- **Alias:** `toThrow`
785785

@@ -789,7 +789,7 @@ You can provide an optional argument to test that a specific error is thrown:
789789

790790
- `RegExp`: error message matches the pattern
791791
- `string`: error message includes the substring
792-
- `Error`, `AsymmetricMatcher`: compare with a received object similar to `toEqual(received)`
792+
- any other value: compare with thrown value using deep equality (similar to `toEqual`)
793793

794794
:::tip
795795
You must wrap the code in a function, otherwise the error will not be caught, and test will fail.
@@ -849,6 +849,17 @@ test('throws on pineapples', async () => {
849849
```
850850
:::
851851

852+
:::tip
853+
You can also test non-Error values that are thrown:
854+
855+
```ts
856+
test('throws non-Error values', () => {
857+
expect(() => { throw 42 }).toThrowError(42)
858+
expect(() => { throw { message: 'error' } }).toThrowError({ message: 'error' })
859+
})
860+
```
861+
:::
862+
852863
## toMatchSnapshot
853864

854865
- **Type:** `<T>(shape?: Partial<T> | string, hint?: string) => void`

‎docs/api/hooks.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Test hooks are called in a stack order ("after" hooks are reversed) by default,
1212

1313
```ts
1414
function beforeEach(
15-
body: () => unknown,
15+
body: (context: TestContext) => unknown,
1616
timeout?: number,
1717
): void
1818
```
@@ -54,7 +54,7 @@ beforeEach(async () => {
5454

5555
```ts
5656
function afterEach(
57-
body: () => unknown,
57+
body: (context: TestContext) => unknown,
5858
timeout?: number,
5959
): void
6060
```
@@ -82,7 +82,7 @@ You can also use [`onTestFinished`](#ontestfinished) during the test execution t
8282

8383
```ts
8484
function beforeAll(
85-
body: () => unknown,
85+
body: (context: ModuleContext) => unknown,
8686
timeout?: number,
8787
): void
8888
```
@@ -122,7 +122,7 @@ beforeAll(async () => {
122122

123123
```ts
124124
function afterAll(
125-
body: () => unknown,
125+
body: (context: ModuleContext) => unknown,
126126
timeout?: number,
127127
): void
128128
```
@@ -146,7 +146,10 @@ Here the `afterAll` ensures that `stopMocking` method is called after all tests
146146

147147
```ts
148148
function aroundEach(
149-
body: (runTest: () => Promise<void>, context: TestContext) => Promise<void>,
149+
body: (
150+
runTest: () => Promise<void>,
151+
context: TestContext,
152+
) => Promise<void>,
150153
timeout?: number,
151154
): void
152155
```
@@ -253,7 +256,10 @@ test('insert user', async ({ db, user }) => {
253256

254257
```ts
255258
function aroundAll(
256-
body: (runSuite: () => Promise<void>) => Promise<void>,
259+
body: (
260+
runSuite: () => Promise<void>,
261+
context: ModuleContext,
262+
) => Promise<void>,
257263
timeout?: number,
258264
): void
259265
```

‎docs/api/test.md‎

Lines changed: 38 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -261,47 +261,42 @@ Whether the test is expected to fail. If it does, the test will pass, otherwise
261261

262262
- **Alias:** `it.extend`
263263

264-
Use `test.extend` to extend the test context with custom fixtures. This will return a new `test` and it's also extendable, so you can compose more fixtures or override existing ones by extending it as you need. See [Extend Test Context](/guide/test-context.html#test-extend) for more information.
264+
Use `test.extend` to extend the test context with custom fixtures. This will return a new `test` and it's also extendable, so you can compose more fixtures or override existing ones by extending it as you need. See [Extend Test Context](/guide/test-context#extend-test-context) for more information.
265265

266266
```ts
267267
import { test as baseTest, expect } from 'vitest'
268268
269-
const todos = []
270-
const archive = []
271-
272-
const test = baseTest.extend({
273-
todos: async ({ task }, use) => {
274-
todos.push(1, 2, 3)
275-
await use(todos)
276-
todos.length = 0
277-
},
278-
archive,
279-
})
280-
281-
test('add item', ({ todos }) => {
282-
expect(todos.length).toBe(3)
269+
export const test = baseTest
270+
// Simple value - type is inferred as { port: number; host: string }
271+
.extend('config', { port: 3000, host: 'localhost' })
272+
// Function fixture - type is inferred from return value
273+
.extend('server', async ({ config }) => {
274+
// TypeScript knows config is { port: number; host: string }
275+
return `http://${config.host}:${config.port}`
276+
})
283277

284-
todos.push(4)
285-
expect(todos.length).toBe(4)
278+
test('server uses correct port', ({ config, server }) => {
279+
// TypeScript knows the types:
280+
// - config is { port: number; host: string }
281+
// - server is string
282+
expect(server).toBe('http://localhost:3000')
283+
expect(config.port).toBe(3000)
286284
})
287285
```
288286

289-
## test.scoped <Version>3.1.0</Version> {#test-scoped}
290-
291-
- **Alias:** `it.scoped`
287+
## test.override <Version>4.1.0</Version> {#test-override}
292288

293-
Use `test.scoped` to override fixture values for all tests within the current suite and its nested suites. This must be called at the top level of a `describe` block. See [Scoping Values to Suite](/guide/test-context.html#scoping-values-to-suite) for more information.
289+
Use `test.override` to override fixture values for all tests within the current suite and its nested suites. This must be called at the top level of a `describe` block. See [Overriding Fixture Values](/guide/test-context.html#overriding-fixture-values) for more information.
294290

295291
```ts
296292
import { test as baseTest, describe, expect } from 'vitest'
297293

298-
const test = baseTest.extend({
299-
dependency: 'default',
300-
dependant: ({ dependency }, use) => use({ dependency }),
301-
})
294+
const test = baseTest
295+
.extend('dependency', 'default')
296+
.extend('dependant', ({ dependency }) => dependency)
302297

303298
describe('use scoped values', () => {
304-
test.scoped({ dependency: 'new' })
299+
test.override({ dependency: 'new' })
305300

306301
test('uses scoped value', ({ dependant }) => {
307302
// `dependant` uses the new overridden value that is scoped
@@ -311,6 +306,16 @@ describe('use scoped values', () => {
311306
})
312307
```
313308

309+
## test.scoped <Version>3.1.0</Version> <Deprecated /> {#test-scoped}
310+
311+
- **Alias:** `it.scoped`
312+
313+
::: danger DEPRECATED
314+
`test.scoped` is deprecated in favor of [`test.override`](#test-override) and will be removed in a future major version.
315+
:::
316+
317+
Alias of [`test.override`](#test-override)
318+
314319
## test.skip
315320

316321
- **Alias:** `it.skip`
@@ -661,6 +666,10 @@ test.concurrent.for([
661666

662667
Scoped `describe`. See [describe](/api/describe) for more information.
663668

669+
## test.suite <Version>4.1.0</Version> {#test-suite}
670+
671+
Alias for `suite`. See [describe](/api/describe) for more information.
672+
664673
## test.beforeEach
665674

666675
Scoped `beforeEach` hook that inherits types from [`test.extend`](#test-extend). See [beforeEach](/api/hooks#beforeeach) for more information.
@@ -671,19 +680,19 @@ Scoped `afterEach` hook that inherits types from [`test.extend`](#test-extend).
671680

672681
## test.beforeAll
673682

674-
Scoped `beforeAll` hook. See [beforeAll](/api/hooks#beforeall) for more information.
683+
Scoped `beforeAll` hook that inherits types from [`test.extend`](#test-extend). See [beforeAll](/api/hooks#beforeall) for more information.
675684

676685
## test.afterAll
677686

678-
Scoped `afterAll` hook. See [afterAll](/api/hooks#afterall) for more information.
687+
Scoped `afterAll` hook that inherits types from [`test.extend`](#test-extend). See [afterAll](/api/hooks#afterall) for more information.
679688

680689
## test.aroundEach <Version>4.1.0</Version> {#test-aroundeach}
681690

682691
Scoped `aroundEach` hook that inherits types from [`test.extend`](#test-extend). See [aroundEach](/api/hooks#aroundeach) for more information.
683692

684693
## test.aroundAll <Version>4.1.0</Version> {#test-aroundall}
685694

686-
Scoped `aroundAll` hook. See [aroundAll](/api/hooks#aroundall) for more information.
695+
Scoped `aroundAll` hook that inherits types from [`test.extend`](#test-extend). See [aroundAll](/api/hooks#aroundall) for more information.
687696

688697
## bench <Experimental /> {#bench}
689698

‎docs/config/include.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,16 @@ export default defineConfig({
4040
test: {
4141
projects: [
4242
{
43-
name: 'unit',
44-
include: ['./test/unit/*.test.js'],
43+
test: {
44+
name: 'unit',
45+
include: ['./test/unit/*.test.js'],
46+
},
4547
},
4648
{
47-
name: 'e2e',
48-
include: ['./test/e2e/*.test.js'],
49+
test: {
50+
name: 'e2e',
51+
include: ['./test/e2e/*.test.js'],
52+
},
4953
},
5054
],
5155
},

‎docs/guide/advanced/reporters.md‎

Lines changed: 13 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
This is an advanced API. If you just want to configure built-in reporters, read the ["Reporters"](/guide/reporters) guide.
55
:::
66

7-
You can import reporters from `vitest/reporters` and extend them to create your custom reporters.
7+
You can import reporters from `vitest/node` and extend them to create your custom reporters.
88

99
## Extending Built-in Reporters
1010

@@ -18,29 +18,24 @@ export default class MyDefaultReporter extends DefaultReporter {
1818
}
1919
```
2020

21-
Of course, you can create your reporter from scratch. Just extend the `BaseReporter` class and implement the methods you need.
22-
23-
And here is an example of a custom reporter:
21+
::: warning
22+
However, note that exposed reports are not considered stable and can change the shape of their API within a minor version.
23+
:::
2424

25-
```ts [custom-reporter.js]
26-
import { BaseReporter } from 'vitest/node'
25+
Of course, you can create your reporter from scratch. Just implement the [`Reporter`](/api/advanced/reporters) interface:
2726

28-
export default class CustomReporter extends BaseReporter {
29-
onTestModuleCollected() {
30-
const files = this.ctx.state.getFiles(this.watchFilters)
31-
this.reportTestSummary(files)
32-
}
33-
}
34-
```
35-
36-
Or implement the `Reporter` interface:
27+
And here is an example of a custom reporter:
3728

3829
```ts [custom-reporter.js]
3930
import type { Reporter } from 'vitest/node'
4031

4132
export default class CustomReporter implements Reporter {
42-
onTestModuleCollected() {
43-
// print something
33+
onTestModuleCollected(testModule) {
34+
console.log(testModule.moduleId, 'is finished')
35+
36+
for (const test of testModule.children.allTests()) {
37+
console.log(test.name, test.result().state)
38+
}
4439
}
4540
}
4641
```
@@ -60,9 +55,7 @@ export default defineConfig({
6055

6156
## Reported Tasks
6257

63-
Instead of using the tasks that reporters receive, it is recommended to use the Reported Tasks API instead.
64-
65-
You can get access to this API by calling `vitest.state.getReportedEntity(runnerTask)`:
58+
Reported [events](/api/advanced/reporters) receive tasks for [tests](/api/advanced/test-case), [suites](/api/advanced/test-suite) and [modules](/api/advanced/test-module):
6659

6760
```ts twoslash
6861
import type { Reporter, TestModule } from 'vitest/node'
@@ -95,10 +88,6 @@ class MyReporter implements Reporter {
9588
8. `HangingProcessReporter`
9689
9. `TreeReporter`
9790

98-
### Base Abstract reporters:
99-
100-
1. `BaseReporter`
101-
10291
### Interface reporters:
10392

10493
1. `Reporter`

‎docs/guide/common-errors.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ title: Common Errors | Guide
88

99
If you receive an error that module cannot be found, it might mean several different things:
1010

11-
- 1. You misspelled the path. Make sure the path is correct.
11+
1. You misspelled the path. Make sure the path is correct.
1212

13-
- 2. It's possible that you rely on `baseUrl` in your `tsconfig.json`. Vite doesn't take into account `tsconfig.json` by default, so you might need to install [`vite-tsconfig-paths`](https://www.npmjs.com/package/vite-tsconfig-paths) yourself, if you rely on this behaviour.
13+
2. It's possible that you rely on `baseUrl` in your `tsconfig.json`. Vite doesn't take into account `tsconfig.json` by default, so you might need to install [`vite-tsconfig-paths`](https://www.npmjs.com/package/vite-tsconfig-paths) yourself, if you rely on this behavior.
1414

1515
```ts
1616
import { defineConfig } from 'vitest/config'
@@ -28,7 +28,7 @@ Or rewrite your path to not be relative to root:
2828
+ import helpers from '../src/helpers'
2929
```
3030

31-
- 3. Make sure you don't have relative [aliases](/config/#alias). Vite treats them as relative to the file where the import is instead of the root.
31+
3. Make sure you don't have relative [aliases](/config/#alias). Vite treats them as relative to the file where the import is instead of the root.
3232

3333
```ts
3434
import { defineConfig } from 'vitest/config'
@@ -47,7 +47,7 @@ export default defineConfig({
4747

4848
This error can happen when NodeJS's `fetch` is used with default [`pool: 'threads'`](/config/#threads). This issue is tracked on issue [Timeout abort can leave process(es) running in the background #3077](https://github.com/vitest-dev/vitest/issues/3077).
4949

50-
As work-around you can switch to [`pool: 'forks'`](/config/#forks) or [`pool: 'vmForks'`](/config/#vmforks).
50+
As a workaround, you can switch to [`pool: 'forks'`](/config/#forks) or [`pool: 'vmForks'`](/config/#vmforks).
5151

5252
::: code-group
5353
```ts [vitest.config.js]
@@ -120,7 +120,7 @@ Running [native NodeJS modules](https://nodejs.org/api/addons.html) in `pool: 't
120120
- `Abort trap: 6`
121121
- `internal error: entered unreachable code`
122122

123-
In these cases the native module is likely not built to be multi-thread safe. As work-around, you can switch to `pool: 'forks'` which runs the test cases in multiple `node:child_process` instead of multiple `node:worker_threads`.
123+
In these cases the native module is likely not built to be multi-thread safe. As a workaround, you can switch to `pool: 'forks'` which runs the test cases in multiple `node:child_process` instead of multiple `node:worker_threads`.
124124

125125
::: code-group
126126
```ts [vitest.config.js]

‎docs/guide/migration.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -442,7 +442,7 @@ export default defineConfig({
442442
In Vitest 4.0 snapshots that include custom elements will print the shadow root contents. To restore the previous behavior, set the [`printShadowRoot` option](/config/#snapshotformat) to `false`.
443443

444444
```js{15-22}
445-
// before Vite 4.0
445+
// before Vitest 4.0
446446
exports[`custom element with shadow root 1`] = `
447447
"<body>
448448
<div>
@@ -451,7 +451,7 @@ exports[`custom element with shadow root 1`] = `
451451
</body>"
452452
`
453453
454-
// after Vite 4.0
454+
// after Vitest 4.0
455455
exports[`custom element with shadow root 1`] = `
456456
"<body>
457457
<div>

0 commit comments

Comments
 (0)