diff --git a/api/expect-typeof.md b/api/expect-typeof.md index 9cd669a1..998d4a33 100644 --- a/api/expect-typeof.md +++ b/api/expect-typeof.md @@ -31,7 +31,14 @@ expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>() - **类型:** `(expected: T) => void` +<<<<<<< HEAD 此匹配器检查期望类型是否扩展了提供的类型。它不同于 `toEqual`,更类似于 [expect's](/api/expect) `toMatchObject()`。使用此匹配器,你可以检查对象是否“匹配”类型。 +======= +::: warning DEPRECATED +This matcher has been deprecated since expect-type v1.2.0. Use [`toExtend`](#toextend) instead. +::: +This matcher checks if expect type extends provided type. It is different from `toEqual` and is more similar to [expect's](/api/expect) `toMatchObject()`. With this matcher, you can check if an object “matches” a type. +>>>>>>> b3badd30ca3b494000aa8b51d8f733ea7bc86fb8 ```ts import { expectTypeOf } from 'vitest' @@ -41,6 +48,44 @@ expectTypeOf().toMatchTypeOf() expectTypeOf().not.toMatchTypeOf() ``` +## toExtend + +- **Type:** `(expected: T) => void` + +This matcher checks if expect type extends provided type. It is different from `toEqual` and is more similar to [expect's](/api/expect) `toMatchObject()`. With this matcher, you can check if an object "matches" a type. + +```ts +import { expectTypeOf } from 'vitest' + +expectTypeOf({ a: 1, b: 1 }).toExtend({ a: 1 }) +expectTypeOf().toExtend() +expectTypeOf().not.toExtend() +``` + +## toMatchObjectType + +- **Type:** `() => void` + +This matcher performs a strict check on object types, ensuring that the expected type matches the provided object type. It's stricter than [`toExtend`](#toextend) and is the recommended choice when working with object types as it's more likely to catch issues like readonly properties. + +```ts +import { expectTypeOf } from 'vitest' + +expectTypeOf({ a: 1, b: 2 }).toMatchObjectType<{ a: number }>() // preferred +expectTypeOf({ a: 1, b: 2 }).toExtend<{ a: number }>() // works but less strict + +// Supports nested object checking +const user = { + name: 'John', + address: { city: 'New York', zip: '10001' } +} +expectTypeOf(user).toMatchObjectType<{ name: string; address: { city: string } }>() +``` + +::: warning +This matcher only works with plain object types. It will fail for union types and other complex types. For those cases, use [`toExtend`](#toextend) instead. +::: + ## extract - **类型:** `ExpectTypeOf` diff --git a/guide/features.md b/guide/features.md index 96aca566..da242c72 100644 --- a/guide/features.md +++ b/guide/features.md @@ -246,7 +246,7 @@ import { mount } from './mount.js' test('my types work properly', () => { expectTypeOf(mount).toBeFunction() - expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>() + expectTypeOf(mount).parameter(0).toExtend<{ name: string }>() // @ts-expect-error name is a string assertType(mount({ name: 42 })) diff --git a/guide/testing-types.md b/guide/testing-types.md index a7744e58..56e94f9f 100644 --- a/guide/testing-types.md +++ b/guide/testing-types.md @@ -30,7 +30,7 @@ import { mount } from './mount.js' test('my types work properly', () => { expectTypeOf(mount).toBeFunction() - expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>() + expectTypeOf(mount).parameter(0).toExtend<{ name: string }>() // @ts-expect-error name is a string assertType(mount({ name: 42 })) @@ -45,7 +45,11 @@ test('my types work properly', () => { 如果使用的是 `expectTypeOf` API,请参阅 [expect-type 关于其错误信息的文档](https://github.com/mmkal/expect-type#error-messages)。 +<<<<<<< HEAD 当类型不匹配时,`.toEqualTypeOf` 和 `.toMatchTypeOf`会使用一种特殊的辅助类型来生成尽可能可操作的错误信息。但要理解它们还有一些细微差别。由于断言是 "流畅地 "编写的,所以失败应该发生在 "预期 "类型上,而不是 "实际 "类型上(`expect().toEqualTypeOf()`)。这意味着类型错误可能有点令人困惑,因此该库生成了一个 `MismatchInfo` 类型,试图明确说明期望是什么。例如 +======= +When types don't match, `.toEqualTypeOf` and `.toExtend` use a special helper type to produce error messages that are as actionable as possible. But there's a bit of an nuance to understanding them. Since the assertions are written "fluently", the failure should be on the "expected" type, not the "actual" type (`expect().toEqualTypeOf()`). This means that type errors can be a little confusing - so this library produces a `MismatchInfo` type to try to make explicit what the expectation is. For example: +>>>>>>> b3badd30ca3b494000aa8b51d8f733ea7bc86fb8 ```ts expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: string }>() @@ -91,7 +95,11 @@ expectTypeOf({ a: 1 }).toEqualTypeOf({ a: '' }) expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: string }>() ``` +<<<<<<< HEAD 这是因为 TypeScript 编译器需要推断 `.toEqualTypeOf({a: ''})` 样式的类型参数,并且该库只能通过将其与通用的 `Mismatch` 类型进行比较来标记它为失败。因此,在可能的情况下,使用类型参数而不是具体类型来使用 `.toEqualTypeOf` 和 `toMatchTypeOf`。如果使用两个具体类型进行比较更加方便,可以使用 `typeof`: +======= +This is because the TypeScript compiler needs to infer the typearg for the `.toEqualTypeOf({a: ''})` style, and this library can only mark it as a failure by comparing it against a generic `Mismatch` type. So, where possible, use a typearg rather than a concrete type for `.toEqualTypeOf` and `.toExtend`. If it's much more convenient to compare two concrete types, you can use `typeof`: +>>>>>>> b3badd30ca3b494000aa8b51d8f733ea7bc86fb8 ```ts const one = valueFromFunctionOne({ some: { complex: inputs } })