diff --git a/.vitepress/config.ts b/.vitepress/config.ts index a7f5075c..8cedcbf1 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -78,6 +78,9 @@ export default ({ mode }: { mode: string }) => { }, }) as any, ], + define: { + __VITEST_VERSION__: JSON.stringify(version), + }, }, markdown: { config(md) { @@ -229,6 +232,10 @@ export default ({ mode }: { mode: string }) => { text: '团队', link: '/team', }, + { + text: 'Releases', + link: '/releases', + }, ], }, { diff --git a/.vitepress/theme/SupportedVersions.vue b/.vitepress/theme/SupportedVersions.vue new file mode 100644 index 00000000..dcb948bf --- /dev/null +++ b/.vitepress/theme/SupportedVersions.vue @@ -0,0 +1,174 @@ + + + + + diff --git a/api/browser/svelte.md b/api/browser/svelte.md index 63b9172d..e6db3af6 100644 --- a/api/browser/svelte.md +++ b/api/browser/svelte.md @@ -39,20 +39,11 @@ export function render( Component: ComponentImport, options?: ComponentOptions, renderOptions?: SetupOptions -): RenderResult & PromiseLike> +): Promise> ``` `render` 函数会记录一个 `svelte.render` 追踪标记,该标记可在 [Trace View](/guide/browser/trace-view) 中查看。 -::: warning -同步调用 `render` 的方式已被弃用,并将在下一个主要版本中移除。请始终使用 `await` 处理其返回结果: - -```ts -const screen = render(Component) // [!code --] -const screen = await render(Component) // [!code ++] -``` -::: - ### 选项 {#options} `render` 函数支持两种传参方式,一种是向 [`mount`](https://svelte.dev/docs/svelte/imperative-component-api#mount) 传入配置选项,另一种则是直接向组件传入属性: @@ -174,10 +165,6 @@ function unmount(): Promise 卸载并销毁 Svelte 组件。同时会在 [Trace View](/guide/browser/trace-view) 中记录一个 `svelte.unmount` 追踪标记。此功能适用于测试组件从页面中移除时的行为(例如测试是否未遗留事件监听器导致内存泄漏)。 -::: warning -同步调用 `unmount` 的方式已被弃用,并将在下一个主要版本中移除。请始终使用 `await` 处理其返回结果: -::: - ```ts import { render } from 'vitest-browser-svelte' diff --git a/api/browser/vue.md b/api/browser/vue.md index eb245376..b03eb1a5 100644 --- a/api/browser/vue.md +++ b/api/browser/vue.md @@ -40,20 +40,11 @@ test('counter button increments the count', async () => { export function render( component: Component, options?: ComponentRenderOptions, -): RenderResult & PromiseLike +): Promise ``` `render` 函数会记录一个 `vue.render` 追踪标记,该标记可在 [Trace View](/guide/browser/trace-view) 中查看。 -::: warning -同步调用 `render` 的方式已被弃用,并将在下一个主要版本中移除。请始终使用 `await` 处理其返回结果: - -```ts -const screen = render(Component) // [!code --] -const screen = await render(Component) // [!code ++] -``` -::: - ### 选项 {#options} `render` 函数支持 `@vue/test-utils` 中 [`mount` 选项](https://test-utils.vuejs.org/api/#mount) 的全部参数(除 `attachTo` 外,需改用 `container`)。此外还额外支持 `container` 和 `baseElement` 参数。 @@ -136,16 +127,12 @@ function debug( #### rerender ```ts -function rerender(props: Partial): void & PromiseLike +function rerender(props: Partial): Promise ``` 同时还会在 [Trace View](/guide/browser/trace-view) 中记录一个 `vue.rerender` 追踪标记。 为了更好地确保组件正确地更新属性,建议测试负责属性更新的组件本身,以避免在测试中依赖实现细节。尽管如此,如果你更倾向于在测试中更新已渲染组件的属性,可以使用此函数来实现。 -::: warning -同步调用 `render` 的方式已被弃用,并将在下一个主要版本中移除。请始终使用 `await` 处理其返回结果: -::: - ```js import { render } from 'vitest-browser-vue' @@ -158,15 +145,11 @@ rerender({ number: 2 }) #### unmount ```ts -function unmount(): void & PromiseLike +function unmount(): Promise ``` 该操作会触发组件卸载,同时在 [跟踪视图](/guide/browser/trace-view) 中记录 `vue.unmount` 标记点。此功能特别适用于测试组件从页面移除时的行为(例如验证是否残留事件处理器导致内存泄漏)。 -::: warning -同步调用 `unmount` 的方式已被弃用,将在下一主要版本中移除。请使用 `await` 进行异步调用。 -::: - #### emitted ```ts diff --git a/config/browser/locators.md b/config/browser/locators.md index f5db1394..42028721 100644 --- a/config/browser/locators.md +++ b/config/browser/locators.md @@ -14,16 +14,16 @@ outline: deep 用于通过 `getByTestId` 定位器查找元素的属性。 -## browser.locators.exact 4.1.3 {#browser-locators-exact} +## browser.locators.exact - **类型:** `boolean` -- **默认值:** `false` +- **默认值:** `true` 当设置为 `true` 时,[定位器](/api/browser/locators) 默认会执行精确文本匹配,要求完全且区分大小写的匹配。单个定位器调用可通过自身的 `exact` 选项覆盖此默认行为。 ```ts -// 当 exact: false(默认值)时,会匹配 "Hello, World!"、"Say Hello, World" 等文本 -// 当 exact: true 时,仅精确匹配字符串 "Hello, World" +// 当 exact: true(默认值)时,仅精确匹配字符串 "Hello, World" +// 当 exact: false 时,会匹配 "Hello, World!"、"Say Hello, World" 等文本 const locator = page.getByText('Hello, World', { exact: true }) await locator.click() ``` diff --git a/config/forcereruntriggers.md b/config/forcereruntriggers.md index 7a104366..a31878e8 100644 --- a/config/forcereruntriggers.md +++ b/config/forcereruntriggers.md @@ -6,7 +6,7 @@ outline: deep # forceRerunTriggers - **类型:** `string[]` -- **默认值:** `['**/package.json/**', '**/vitest.config.*/**', '**/vite.config.*/**']` +- **默认值:** `['**/package.json', '**/vitest.config.*', '**/vite.config.*']` 将触发整个测试套件重新运行的文件路径(glob 模式)。当与 `--changed` 参数配合使用时,如果在 git diff 中发现触发文件,就会运行整个测试套件。 diff --git a/guide/browser/index.md b/guide/browser/index.md index bb94b4b5..7de24e3f 100644 --- a/guide/browser/index.md +++ b/guide/browser/index.md @@ -426,7 +426,7 @@ import { render } from 'vitest-browser-vue' import Component from './Component.vue' test('properly handles v-model', async () => { - const screen = render(Component) + const screen = await render(Component) // 断言初始状态。 await expect.element(screen.getByText('Hi, my name is Alice')).toBeInTheDocument() @@ -448,7 +448,7 @@ import { render } from 'vitest-browser-svelte' import Greeter from './greeter.svelte' test('greeting appears on click', async () => { - const screen = render(Greeter, { name: 'World' }) + const screen = await render(Greeter, { name: 'World' }) const button = screen.getByRole('button') await button.click() diff --git a/guide/cli-generated.md b/guide/cli-generated.md index 0241955d..b3690888 100644 --- a/guide/cli-generated.md +++ b/guide/cli-generated.md @@ -462,7 +462,7 @@ UI 模式和 HTML 报告器中提供的 HTML 覆盖率输出目录。 - **命令行终端:** `--browser.locators.exact` - **配置:** [browser.locators.exact](/config/browser/locators#locators-exact) -定位器是否默认需完全匹配文本内容(默认值:`false`) +定位器是否默认需完全匹配文本内容(默认值:`true`) ### pool diff --git a/guide/migration.md b/guide/migration.md index a07ce24d..cea5dae6 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -5,7 +5,7 @@ outline: deep # 迁移指南 {#migration-guide} -[迁移至 Vitest 3.0](https://v3.vitest.dev/guide/migration) | [迁移至 Vitest 2.0](https://v2.vitest.dev/guide/migration) +[迁移至 Vitest 4.0](https://v4.vitest.dev/guide/migration) | [迁移至 Vitest 3.0](https://v3.vitest.dev/guide/migration) ## 迁移至 Vitest 5.0 {#vitest-5} @@ -55,6 +55,17 @@ export async function customClick( await context.page.locator(selector).click() } ``` + +### Locators are Strict by Default + +Browser locators now match the text exactly by default, requiring a full, case-sensitive match. To keep the previous behaviour, you can set [`browser.locators.exact`](/config/browser/locators#browser-locators-exact) to `false`. + +```ts +// With exact: true (default), this only matches the string "Hello, World" exactly. +// With exact: false, this matches "Hello, World!", "Say Hello, World", etc. +const locator = page.getByText('Hello, World', { exact: true }) +await locator.click() +``` ### 移除了已弃用的入口 {#removed-deprecated-entrypoints} diff --git a/releases.md b/releases.md new file mode 100644 index 00000000..664bf97f --- /dev/null +++ b/releases.md @@ -0,0 +1,57 @@ + + +# Releases + +Vitest releases follow [Semantic Versioning](https://semver.org/). You can see the latest stable version of Vitest in the [Vitest npm package page](https://www.npmjs.com/package/vite). + +A full changelog of past releases is [available on GitHub](https://github.com/vitest-dev/vitest/releases). + +## Release Cycle + +Vitest does not have a fixed release cycle. + +- **Patch** releases are released as needed (usually every week). +- **Minor** releases always contain new features and are released as needed. Minor releases always have a beta pre-release phase (usually every two months). +- **Major** releases generally align with [Vite](https://vite.dev/releases) and [Node.js EOL schedule](https://endoflife.date/nodejs), and will be announced ahead of time. These releases will have a long beta pre-release phases (usually every year). + +## Supported Versions + +In summary, the current supported Vitest versions are: + + + +
+ +The supported version ranges are automatically determined by: + +- **Current Minor** gets regular fixes. +- **Previous Major** (only for its latest minor) and **Previous Minor** receives important fixes and security patches. +- All versions before these are no longer supported. + +We recommend updating Vitest regularly. Check out the [Migration Guides](/guide/migration) when you update to each Major. We test new Vitest versions before releasing them through the [vitest-ecosystem-ci project](https://github.com/vitest-dev/vitest-ecosystem-ci). Most projects using Vitest should be able to quickly offer support or migrate to new versions as soon as they are released. + +## Semantic Versioning Edge Cases + +### TypeScript Definitions + +We may ship incompatible changes to TypeScript definitions between minor versions. This is because: + +- Sometimes TypeScript itself ships incompatible changes between minor versions, and we may have to adjust types to support newer versions of TypeScript. +- Occasionally we may need to adopt features that are only available in a newer version of TypeScript, raising the minimum required version of TypeScript. +- If you are using TypeScript, you can use a semver range that locks the current minor and manually upgrade when a new minor version of Vite is released. + +## Pre Releases + +Minor releases typically go through a non-fixed number of beta releases. Major releases will go through a long beta phase. + +Pre-releases allow early adopters and maintainers from the Ecosystem to do integration and stability testing, and provide feedback. Do not use pre-releases in production. All pre-releases are considered unstable and may ship breaking changes in between. Always pin to exact versions when using pre-releases. + +## Deprecations + +We periodically deprecate features that have been superseded by better alternatives in Minor releases. Deprecated features will continue to work with a type or logged warning. They will be removed in the next major release after entering deprecated status. The [Migration Guide](/guide/migration.html) for each major will list these removals and document an upgrade path for them. + +## Experimental Features + +Some features are marked as experimental when released in a stable version of Vite. Experimental features allow us to gather real-world experience to influence their final design. The goal is to let users provide feedback by testing them in production. Experimental features themselves are considered unstable, and should only be used in a controlled manner. These features may change between Minors, so users must pin their Vite version when they rely on them. We will create [a GitHub discussion](https://github.com/vitest-dev/vitest/discussions/categories/feedback?discussions_q=is%3Aopen+label%3Aexperimental+category%3AFeedback) for each experimental feature.