diff --git a/advanced/api.md b/advanced/api.md index 6b98421d..b549be86 100644 --- a/advanced/api.md +++ b/advanced/api.md @@ -1,7 +1,7 @@ # Node API ::: warning -Vitest 暴露了实验性的私有 API。由于可能不遵循语义化版本规范（SemVer），因此可能会出现不兼容的更改，请在使用 Vitest 时锁定版本。 +Vitest 暴露了实验性的私有 API。由于可能不严格遵循语义化版本规范，因此可能会出现破坏性更改，在使用 Vitest 的私有 API 时锁定版本。 ::: ## 启动 Vitest diff --git a/advanced/metadata.md b/advanced/metadata.md index 8c5325ca..13eab7b4 100644 --- a/advanced/metadata.md +++ b/advanced/metadata.md @@ -1,14 +1,14 @@ # 任务元数据 ::: warning -Vitest 导出了实验性私有 API。重大更改可能不遵循 semver，使用时请固定 Vitest 的版本。 +Vitest 暴露了实验性的私有 API。由于可能不严格遵循语义化版本规范，因此可能会出现破坏性更改，在使用 Vitest 的私有 API 时锁定版本。 ::: 如果你正在开发自定义报告器或使用 Vitest Node.js API，你可能会发现将在各种上下文中执行的测试中的数据传递给报告器或自定义 Vitest 处理程序很有用。 要实现此目的，依靠 [测试上下文](/guide/test-context) 是不可行的，因为它无法序列化。但是，使用 Vitest 时，你可以利用每个任务（套件或测试）上可用的 `meta` 属性在测试和 Node.js 进程之间共享数据。值得注意的是，这种通信只是单向的，因为 `meta` 属性只能在测试上下文中修改。Node.js 上下文中所做的任何更改在你的测试中都将不可见。 -你可以在测试上下文中或在套件任务的 `beforeAll`/`afterAll` 钩子中填充 `meta` 属性。 +你可以在测试上下文中或在测试套件的 `beforeAll`/`afterAll` 中填充 `meta` 属性。 ```ts afterAll((suite) => { @@ -20,16 +20,16 @@ test('custom', ({ task }) => { }) ``` -一旦测试完成，Vitest 将使用 RPC 将包含结果和 `meta` 的任务发送到 Node.js 进程。要拦截和处理此任务，你可以利用报告器实现中可用的 `onTaskUpdate` 方法： +一旦测试完成，Vitest 将使用 RPC 将包含结果和 `meta` 信息的任务发送到 Node.js 进程。要拦截和处理此任务，你可以利用报告器实现中可用的 `onTaskUpdate` 方法： ```ts // custom-reporter.js export default { - // you can intercept packs if needed + // 如有需要，您可以拦截此任务并修改它 onTaskUpdate(packs) { const [id, result, meta] = packs[0] }, - // meta is located on every task inside "onFinished" + // meta 位于 `onFinished` 内的每个任务上 onFinished(files) { files[0].meta.done === true files[0].tasks[0].meta.custom === 'some-custom-handler' @@ -38,15 +38,15 @@ export default { ``` ::: warning -如果短时间内完成多个测试，Vitest 可以同时发送多个任务。 +如果需要在短时间内完成多个测试，Vitest 可以同时发送多个任务。 ::: ::: danger BEWARE Vitest 使用不同的方法与 Node.js 进程进行通信。 - 如果 Vitest 在工作线程内运行测试，它将通过[消息端口](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort)发送数据 -- 如果 Vitest 使用子进程，数据将通过 [`process.send`](https://nodejs.org/api/process.html#processsendmessage-sendhandle-options-callback) API 作为序列化缓冲区发送 -- 如果 Vitest 在浏览器中运行测试，数据将使用 [flatted](https://www.npmjs.com/package/flatted) 包进行字符串化 +- 如果 Vitest 使用子进程，数据将通过 [`process.send`](https://nodejs.org/api/process.html#processsendmessage-sendhandle-options-callback) 作为序列化缓冲区发送 +- 如果 Vitest 在浏览器中运行测试，数据将使用 [flatted](https://www.npmjs.com/package/flatted) 进行字符串化 一般经验法则是，你几乎可以发送任何内容，除了函数、Promises、regexp（`v8.stringify` 无法序列化它，但你可以发送字符串版本并自己在 Node.js 进程中解析它），以及其他不可序列化的数据，但内部可以有循环引用。 diff --git a/advanced/pool.md b/advanced/pool.md index 41559051..218c5943 100644 --- a/advanced/pool.md +++ b/advanced/pool.md @@ -12,7 +12,7 @@ Vitest 在默认情况下以多种方式运行测试： - `browser` 使用浏览器提供程序运行测试 - `typescript` 在测试中运行类型检查 -你可以通过指定文件路径来提供自己的池： +你可以通过指定文件路径来提供自己的「 池 / pool 」： ```ts export default defineConfig({ @@ -50,13 +50,13 @@ export interface ProcessPool { 这个函数只会被调用一次（除非服务器配置被更新），通常最好在这个函数内初始化测试所需的一切，并在调用 `runTests` 时重复使用它。 -Vitest 在安排运行新测试时调用 `runTest`。如果 `files` 为空，将不会调用它。第一个参数是一个元组数组：第一个元素是对工作区项目的引用，第二个元素是测试文件的绝对路径。在调用 `runTests` 之前，文件将使用 [`sequencer`](/config/#sequence.sequencer) 进行排序。可能（但不太可能）会有相同的文件出现两次，但它们将始终属于不同的项目 - 这是通过 [`vitest.workspace.ts`](/guide/workspace) 配置实现的。 +Vitest 在安排运行新测试时调用 `runTest`。如果 `files` 为空，将不会调用它。第一个参数是一个 tuples 数组：第一个元素是对工作区项目的引用，第二个元素是测试文件的绝对路径。在调用 `runTests` 之前，文件将使用 [`sequencer`](/config/#sequence.sequencer) 进行排序。可能（但不太可能）会有相同的文件出现两次，但它们将始终属于不同的项目 - 这是通过 [`vitest.workspace.ts`](/guide/workspace) 配置实现的。 Vitest 会等到 `runTests` 执行完毕后才结束运行（即只有在 `runTests` 解决后才会触发 [`onFinished`](/guide/reporters)）。 -如果你正在使用自定义池，需要自行提供测试文件及其结果 - 可以参考 [`vitest.state`](https://github.com/vitest-dev/vitest/blob/main/packages/vitest/src/node/state.ts)（最重要的是 `collectFiles` 和 `updateTasks`）。Vitest 使用 `@vitest/runner` 包中的 `startTests` 函数来执行这些操作。 +如果你正在使用自定义 pool ，需要自行提供测试文件及其结果 - 可以参考 [`vitest.state`](https://github.com/vitest-dev/vitest/blob/main/packages/vitest/src/node/state.ts)（最重要的是 `collectFiles` 和 `updateTasks`）。Vitest 使用 `@vitest/runner` 包中的 `startTests` 函数来执行这些操作。 -要在不同进程之间进行通信，可以使用 `vitest/node` 中的 `createMethodsRPC` 创建方法对象，并使用你喜欢的任何通信形式。例如，要使用 `birpc` 的 websockets，可以编写类似以下的内容： +要在不同进程之间进行通信，可以使用 `vitest/node` 中的 `createMethodsRPC` 创建方法对象，或使用你喜欢的任何通信形式。例如，要使用 `birpc` 的 websockets，可以编写类似以下的内容： ```ts import { createBirpc } from 'birpc' diff --git a/advanced/runner.md b/advanced/runner.md index 90fb7fdb..e634700b 100644 --- a/advanced/runner.md +++ b/advanced/runner.md @@ -115,7 +115,7 @@ Vitest 还会将 `ViteNodeRunner` 的实例作为 `__vitest_executor` 属性注 ## 你的任务函数 -你可以通过扩展 `Vitest` 的任务系统来添加你自己的任务。一个任务是一个对象，是套件的一部分。它会自动通过 `suite.task` 方法添加到当前套件中： +你可以通过扩展 `Vitest` 的任务系统来添加你自己的任务。一个任务是一个对象，是测试套件的一部分。它会自动通过 `suite.task` 方法添加到当前测试套件中： ```js // ./utils/custom.js diff --git a/api/assert-type.md b/api/assert-type.md index c9f019a8..6450f0bc 100644 --- a/api/assert-type.md +++ b/api/assert-type.md @@ -1,13 +1,13 @@ # assertType -- **类型:** `(value: T): void` - -你可以使用此函数作为 [`expectTypeOf`](/api/expect-typeof) 的替代方法，以轻松地断言参数类型等于提供的泛型。 - ::: warning -在运行时，此函数不执行任何操作。要 [enable typechecking](/guide/testing-types#run-typechecking)，不要忘记传递 `--typecheck` 标志。 +运行时，此函数不会执行任何操作。要 [「 启用类型检查 / enable typechecking 」](/guide/testing-types#run-typechecking)，不要忘了传递 `--typecheck`。 ::: +- **类型:** `(value: T): void` + +你可以使用此函数作为 [`expectTypeOf`](/api/expect-typeof) 的替代方法，可以轻松地断言参数类型等于提供的泛型。 + ```ts import { assertType } from 'vitest' diff --git a/api/expect-typeof.md b/api/expect-typeof.md index a79b2e83..acffe76f 100644 --- a/api/expect-typeof.md +++ b/api/expect-typeof.md @@ -1,11 +1,11 @@ # expectTypeOf -- **类型:** `(a: unknown) => ExpectTypeOf` - -::: warning -在运行时，此函数不执行任何操作。要 [enable typechecking](/guide/testing-types#run-typechecking)，不要忘记传递 `--typecheck` 标志。 +::: warning 注意 +运行时，此函数不会执行任何操作。要 [「 启用类型检查 / enable typechecking 」](/guide/testing-types#run-typechecking)，不要忘了传递 `--typecheck`。 ::: +- **类型:** `(a: unknown) => ExpectTypeOf` + ## not - **类型:** `ExpectTypeOf` @@ -76,8 +76,8 @@ expectTypeOf(getResponsiveProp(cssProperties)) .toEqualTypeOf() ``` -::: warning -如果在联合类型中找不到类型，`.extract` 将返回 `never`。 +::: warning 注意 +如果在 union 中找不到类型，`.extract` 将返回 `never`。 ::: ## exclude @@ -106,8 +106,8 @@ expectTypeOf(getResponsiveProp(cssProperties)) ``` -::: warning -如果在联合类型中找不到类型，`.extract` 将返回 `never`。 +::: warning 注意 +如果在 union 中找不到类型，`.extract` 将返回 `never`。 ::: ## returns @@ -123,7 +123,7 @@ expectTypeOf(() => {}).returns.toBeVoid() expectTypeOf((a: number) => [a, a]).returns.toEqualTypeOf([1, 2]) ``` -::: warning +::: warning 注意 如果用在非函数类型上，它将返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: @@ -143,11 +143,11 @@ expectTypeOf().parameters.toEqualTypeOf<[]>() expectTypeOf().parameters.toEqualTypeOf<[string]>() ``` -::: warning +::: warning 注意 如果用在非函数类型上，它将返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: -::: tip +::: tip 提示 你还可以使用 [`.toBeCallableWith`](#tobecallablewith) 匹配器作为更具表现力的断言。 ::: @@ -168,7 +168,7 @@ expectTypeOf(foo).parameter(0).toBeNumber() expectTypeOf(foo).parameter(1).toBeString() ``` -::: warning +::: warning 注意 如果用在非函数类型上，它将返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: @@ -186,11 +186,11 @@ expectTypeOf(Date).constructorParameters.toEqualTypeOf< >() ``` -::: warning +::: warning 注意 如果用在非函数类型上，它将返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: -::: tip +::: tip 提示 你还可以使用 [`.toBeConstructibleWith`](#tobeconstructiblewith) 匹配器作为更具表现力的断言。 ::: @@ -206,7 +206,7 @@ import { expectTypeOf } from 'vitest' expectTypeOf(Date).instance.toHaveProperty('toISOString') ``` -::: warning +::: warning 注意 如果用在非函数类型上，它将返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: @@ -240,7 +240,7 @@ expectTypeOf(asyncFunc).returns.resolves.toBeNumber() expectTypeOf(Promise.resolve('string')).resolves.toBeString() ``` -::: warning +::: warning 注意 如果用于非承诺类型，它将返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: @@ -260,7 +260,7 @@ function isString(v: any): v is string { expectTypeOf(isString).guards.toBeString() ``` -::: warning +::: warning 注意 如果该值不是保护函数，则返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: @@ -281,7 +281,7 @@ function assertNumber(v: any): asserts v is number { expectTypeOf(assertNumber).asserts.toBeNumber() ``` -::: warning +::: warning 注意 如果该值不是断言函数，则返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: @@ -479,7 +479,7 @@ expectTypeOf().toBeCallableWith() expectTypeOf().toBeCallableWith('some string') ``` -::: warning +::: warning 注意 如果用在非函数类型上，它将返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: @@ -496,7 +496,7 @@ expectTypeOf(Date).toBeConstructibleWith(new Date()) expectTypeOf(Date).toBeConstructibleWith('01-01-2000') ``` -::: warning +::: warning 注意 如果用在非函数类型上，它将返回 `never`，因此你将无法将它与其他匹配器链接起来。 ::: diff --git a/api/expect.md b/api/expect.md index c6c7ef58..85914cee 100644 --- a/api/expect.md +++ b/api/expect.md @@ -23,7 +23,7 @@ expect(input).toBe(2); // jest API 此外，`expect` 可以静态地使用来访问匹配器函数，稍后将会介绍。 -::: warning +::: warning 注意 如果表达式没有类型错误，则 `expect` 对测试类型没有影响。 如果你想使用 Vitest 作为[类型检查器](/guide/testing-types)，请使用 [`expectTypeOf`](/api/expect-typeof) 或 [`assertType`](/api/assert-type) 。 ::: @@ -55,7 +55,7 @@ test("expect.soft test", () => { }); ``` -::: warning +::: warning 注意 `expect.soft` 只能在 [`test`](/api/#test) 函数的内部使用。 ::: @@ -541,7 +541,7 @@ test("top fruits", () => { }); ``` -::: tip +::: tip 提示 如果错误消息中的值被截断得太厉害，可以在配置文件中增加 [chaiConfig.truncateThreshold](/config/#chaiconfig-truncatethreshold)。 ::: @@ -1088,7 +1088,7 @@ test("all assertions are called", async () => { }); ``` -::: warning +::: warning 注意 在使用异步并发测试时，必须使用本地 [Test Context](/guide/test-context.md) 中的 `expect` 来确保正确的测试被检测到。 ::: @@ -1365,7 +1365,7 @@ test("custom matchers", () => { }); ``` -::: tip +::: tip 提示 如果希望匹配器出现在每个测试中，应该在 [`setupFiles`](/config/#setupFiles) 中调用此方法。 ::: @@ -1384,7 +1384,7 @@ declare module "vitest" { } ``` -::: warning +::: warning 注意 不要忘记在 `tsconfig.json` 中包含环境声明文件。 :::