From b21f3a9858e7aa1ef2081a9adce23fc2461a2c06 Mon Sep 17 00:00:00 2001 From: Vladimir Date: Mon, 1 Jul 2024 16:19:38 +0200 Subject: [PATCH] docs: add more migration steps (#6008) --- docs/guide/migration.md | 89 ++++++++++++++++++++++++++++------------- 1 file changed, 62 insertions(+), 27 deletions(-) diff --git a/docs/guide/migration.md b/docs/guide/migration.md index 3196c577a..bc9766069 100644 --- a/docs/guide/migration.md +++ b/docs/guide/migration.md @@ -7,7 +7,7 @@ outline: deep ## Migrating to Vitest 2.0 -### Default pool is `forks` +### Default Pool is `forks` Vitest 2.0 changes the default configuration for `pool` to `'forks'` for better stability. You can read the full motivation in [PR](https://github.com/vitest-dev/vitest/pull/5047). @@ -28,11 +28,11 @@ export default defineConfig({ }) ``` -### Hooks are running in a stack +### Hooks are Running in a Stack -Before Vitest 2.0, all hooks were running in parallel. In 2.0, all hooks run serially. In addition to this, `afterAll`/`afterEach` are running in a reverse order. +Before Vitest 2.0, all hooks ran in parallel. In 2.0, all hooks run serially. Additionally, `afterAll`/`afterEach` hooks run in reverse order. -You can revert to the previous behaviour by changing [`sequence.hooks`](/config/#sequence-hooks) to `'parallel'`: +To revert to the parallel execution of hooks, change [`sequence.hooks`](/config/#sequence-hooks) to `'parallel'`: ```ts export default defineConfig({ @@ -44,17 +44,17 @@ export default defineConfig({ }) ``` -### `suite.concurrent` runs all its tests concurrently +### `suite.concurrent` Runs All Tests Concurrently -Previously, specifying `concurrent` on a suite would still group concurrent tests by suites and run them together one by one. Now, it follows jest's behaviour and runs all of them at once (still limited by [`maxConcurrency`](/config/#maxConcurrency)) +Previously, specifying `concurrent` on a suite would group concurrent tests by suites, running them sequentially. Now, following Jest's behavior, all tests run concurrently (subject to [`maxConcurrency`](/config/#maxconcurrency) limits). -### enable V8 coverage's `coverage.ignoreEmptyLines` by default +### V8 Coverage's `coverage.ignoreEmptyLines` is Enabled by Default -Changes default value of `coverage.ignoreEmptyLines` to `true`. This change will have major impact on users' code coverage reports. It is likely that projects using coverage thresholds need to adjust those values after this. This change affects only the default `coverage.provider: 'v8'`. +The default value of `coverage.ignoreEmptyLines` is now true. This significant change may affect code coverage reports, requiring adjustments to coverage thresholds for some projects. This adjustment only affects the default setting when `coverage.provider` is `'v8'`. -### No more `watchExclude` option +### Removal of the `watchExclude` Option -Vitest uses Vite's watcher. You can add your excludes to `server.watch.ignored` instead: +Vitest uses Vite's watcher. Exclude files or directories by adding them to `server.watch.ignored`: ```ts export default defineConfig({ @@ -66,11 +66,11 @@ export default defineConfig({ }) ``` -### `--segfault-retry` removed +### `--segfault-retry` Removed With the changes to default pool, this option is no longer needed. If you experience segfault errors, try switching to `'forks'` pool. If the problem persists, please open a new issue with a reproduction. -### Empty task in suite tasks removed +### Empty Task In Suite Tasks Removed This is the change to the advanced [task API](/advanced/runner#your-task-function). Previously, traversing `.suite` would eventually lead to the empty internal suite that was used instead of a file task. @@ -78,9 +78,13 @@ This makes `.suite` optional; if the task is defined at the top level, it will n This change also removes the file from `expect.getState().currentTestName` and makes `expect.getState().testPath` required. -### Simplified generic types of mock functions (e.g. `vi.fn`, `Mock`) +### `task.meta` is Added to the JSON Reporter -Previously `vi.fn` accepted two generic types separately for arguemnts and return value. This is changed to directly accept a function type `vi.fn` to simplify the usage. +JSON reporter now prints `task.meta` for every assertion result. + +### Simplified Generic Types of Mock Functions (e.g. `vi.fn`, `Mock`) + +Previously `vi.fn` accepted two generic types separately for arguments and return value. This is changed to directly accept a function type `vi.fn` to simplify the usage. ```ts import { type Mock, vi } from 'vitest' @@ -96,9 +100,50 @@ const mockAdd: Mock, ReturnType> = vi.fn() // const mockAdd: Mock = vi.fn() // [!code ++] ``` -## Migrating to Vitest 1.0 +### Accessing Resolved `mock.results` + +Previously Vitest resolved `mock.results` values if the function returned a Promise. Now there is a separate [`mock.settledResults`](/api/mock#mock-settledresults) property that populates only when the returned Promise is resolved or rejected. + +```ts +const fn = vi.fn().mockResolvedValueOnce('result') +await fn() + +const result = fn.mock.results[0] // 'result' // [!code --] +const result = fn.mock.results[0] // 'Promise' // [!code ++] + +const settledResult = fn.mock.settledResults[0] // 'result' +``` + +With this change, we also introduce new [`toHaveResolved*`](/api/expect#tohaveresolved) matchers similar to `toHaveReturned` to make migration easier if you used `toHaveReturned` before: + +```ts +const fn = vi.fn().mockResolvedValueOnce('result') +await fn() + +expect(fn).toHaveReturned('result') // [!code --] +expect(fn).toHaveResolved('result') // [!code ++] +``` - +### Browser Mode + +Vitest Browser Mode had a lot of changes during the beta cycle. You can read about our philosophy on the Browser Mode in the [GitHub discussion page](https://github.com/vitest-dev/vitest/discussions/5828). + +Most of the changes were additive, but there were some small breaking changes: + +- `none` provider was renamed to `preview` [#5842](https://github.com/vitest-dev/vitest/pull/5826) +- `preview` provider is now a default [#5842](https://github.com/vitest-dev/vitest/pull/5826) +- `indexScripts` is renamed to `orchestratorScripts` [#5842](https://github.com/vitest-dev/vitest/pull/5842) + +### Deprecated Options Removed + +Some deprecated options were removed: + +- `vitest typecheck` command - use `vitest --typecheck` instead +- `VITEST_JUNIT_CLASSNAME` and `VITEST_JUNIT_SUITE_NAME` env variables (use reporter options instead) +- check for `c8` coverage (use coverage-v8 instead) +- export of `SnapshotEnvironment` from `vitest` - import it from `vitest/snapshot` instead + +## Migrating to Vitest 1.0 ### Minimum Requirements @@ -237,7 +282,7 @@ A few types were removed in favor of Jest-style "Mock" naming. ### Timer mocks [#3925](https://github.com/vitest-dev/vitest/pull/3925) `vi.useFakeTimers()` no longer automatically mocks [`process.nextTick`](https://nodejs.org/api/process.html#processnexttickcallback-args). -It's still possible to mock `process.nextTick` by explicitly specifying it by using `vi.useFakeTimers({ toFake: ['nextTick'] })`. +It is still possible to mock `process.nextTick` by explicitly specifying it by using `vi.useFakeTimers({ toFake: ['nextTick'] })`. However, mocking `process.nextTick` is not possible when using `--pool=forks`. Use a different `--pool` option if you need `process.nextTick` mocking. @@ -285,16 +330,6 @@ Where Jest does it by default, when mocking a module and wanting this mocking to server.deps.inline: ["lib-name"] ``` -### Accessing the Return Values of a Mocked Promise - -Both Jest and Vitest store the results of all mock calls in the [`mock.results`](/api/mock.html#mock-results) array, where the return values of each call are stored in the `value` property. -However, when mocking or spying on a promise (e.g. using `mockResolvedValue`), in Jest the `value` property will be a promise, while in Vitest, it will become a resolved value when a promise is resolved. - -```ts -await expect(spy.mock.results[0].value).resolves.toBe(123) // [!code --] -expect(spy.mock.results[0].value).toBe(123) // [!code ++] -``` - ### Envs Just like Jest, Vitest sets `NODE_ENV` to `test`, if it wasn't set before. Vitest also has a counterpart for `JEST_WORKER_ID` called `VITEST_POOL_ID` (always less than or equal to `maxThreads`), so if you rely on it, don't forget to rename it. Vitest also exposes `VITEST_WORKER_ID` which is a unique ID of a running worker - this number is not affected by `maxThreads`, and will increase with each created worker. -- 2.51.2