From a995998a01a838d27f1bf70f39b17630a08762a1 Mon Sep 17 00:00:00 2001
From: Satoshi <140612116+satohshi@users.noreply.github.com>
Date: Wed, 17 Dec 2025 00:04:58 +0900
Subject: [PATCH] docs: add documentation for `branded` helper (#9248)

---
 docs/api/expect-typeof.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/api/expect-typeof.md b/docs/api/expect-typeof.md
index c94785dfa..2014f5171 100644
--- a/docs/api/expect-typeof.md
+++ b/docs/api/expect-typeof.md
@@ -549,3 +549,23 @@ expectTypeOf(obj).toHaveProperty('a').toBeNumber()
 expectTypeOf(obj).toHaveProperty('b').toBeString()
 expectTypeOf(obj).toHaveProperty('a').not.toBeString()
 ```
+
+## branded
+
+- **Type:** `ExpectTypeOf<BrandedType>`
+
+You can use `.branded` to allow type assertions to succeed for types that are semantically equivalent but differ in representation.
+
+```ts
+import { expectTypeOf } from 'vitest'
+
+// Without .branded, this fails even though the types are effectively the same
+expectTypeOf<{ a: { b: 1 } & { c: 1 } }>().toEqualTypeOf<{ a: { b: 1; c: 1 } }>()
+
+// With .branded, the assertion succeeds
+expectTypeOf<{ a: { b: 1 } & { c: 1 } }>().branded.toEqualTypeOf<{ a: { b: 1; c: 1 } }>()
+```
+
+::: warning
+This helper comes at a performance cost and can cause the TypeScript compiler to 'give up' if used with excessively deep types. Use it sparingly and only when necessary.
+:::
-- 
2.51.2