1---
2name: expect-api
3description: Assertions with matchers, asymmetric matchers, and custom matchers
4---
5 
6# Expect API
7 
8Vitest uses Chai assertions with Jest-compatible API.
9 
10## Basic Assertions
11 
12```ts
13import { expect, test } from 'vitest'
14 
15test('assertions', () => {
16  // Equality
17  expect(1 + 1).toBe(2)              // Strict equality (===)
18  expect({ a: 1 }).toEqual({ a: 1 }) // Deep equality
19 
20  // Truthiness
21  expect(true).toBeTruthy()
22  expect(false).toBeFalsy()
23  expect(null).toBeNull()
24  expect(undefined).toBeUndefined()
25  expect('value').toBeDefined()
26 
27  // Numbers
28  expect(10).toBeGreaterThan(5)
29  expect(10).toBeGreaterThanOrEqual(10)
30  expect(5).toBeLessThan(10)
31  expect(0.1 + 0.2).toBeCloseTo(0.3, 5)
32 
33  // Strings
34  expect('hello world').toMatch(/world/)
35  expect('hello').toContain('ell')
36 
37  // Arrays
38  expect([1, 2, 3]).toContain(2)
39  expect([{ a: 1 }]).toContainEqual({ a: 1 })
40  expect([1, 2, 3]).toHaveLength(3)
41 
42  // Objects
43  expect({ a: 1, b: 2 }).toHaveProperty('a')
44  expect({ a: 1, b: 2 }).toHaveProperty('a', 1)
45  expect({ a: { b: 1 } }).toHaveProperty('a.b', 1)
46  expect({ a: 1 }).toMatchObject({ a: 1 })
47 
48  // Types
49  expect('string').toBeTypeOf('string')
50  expect(new Date()).toBeInstanceOf(Date)
51})
52```
53 
54## Negation
55 
56```ts
57expect(1).not.toBe(2)
58expect({ a: 1 }).not.toEqual({ a: 2 })
59```
60 
61## Error Assertions
62 
63```ts
64// Sync errors - wrap in function
65expect(() => throwError()).toThrow()
66expect(() => throwError()).toThrow('message')
67expect(() => throwError()).toThrow(/pattern/)
68expect(() => throwError()).toThrow(CustomError)
69 
70// Async errors - use rejects
71await expect(asyncThrow()).rejects.toThrow('error')
72```
73 
74## Promise Assertions
75 
76```ts
77// Resolves
78await expect(Promise.resolve(1)).resolves.toBe(1)
79await expect(fetchData()).resolves.toEqual({ data: true })
80 
81// Rejects
82await expect(Promise.reject('error')).rejects.toBe('error')
83await expect(failingFetch()).rejects.toThrow()
84```
85 
86## Spy/Mock Assertions
87 
88```ts
89const fn = vi.fn()
90fn('arg1', 'arg2')
91fn('arg3')
92 
93expect(fn).toHaveBeenCalled()
94expect(fn).toHaveBeenCalledTimes(2)
95expect(fn).toHaveBeenCalledWith('arg1', 'arg2')
96expect(fn).toHaveBeenLastCalledWith('arg3')
97expect(fn).toHaveBeenNthCalledWith(1, 'arg1', 'arg2')
98 
99expect(fn).toHaveReturned()
100expect(fn).toHaveReturnedWith(value)
101 
102// v4 additions
103expect(fn).toHaveBeenCalledExactlyOnceWith('arg1', 'arg2')
104expect(fnA).toHaveBeenCalledBefore(fnB)
105expect(fnA).toHaveBeenCalledAfter(fnB)
106```
107 
108### Chai-Style Spy Assertions (4.1+)
109 
110Sinon-chai-compatible aliases, useful when migrating from Sinon:
111 
112```ts
113expect(spy).to.have.been.called
114expect(spy).to.have.been.calledOnce
115expect(spy).to.have.been.calledWith('arg1', 'arg2')
116expect(spy).to.have.been.calledOnceWith('arg')
117```
118 
119### Conditional Mock Exhaustion (v5)
120 
121Assert every `vi.when` behavior was consumed:
122 
123```ts
124const w = vi.when(spy).calledWith(1).thenReturnOnce('a')
125spy(1)
126expect(w).toHaveBeenExhausted()
127```
128 
129## Asymmetric Matchers
130 
131Use inside `toEqual`, `toHaveBeenCalledWith`, etc:
132 
133```ts
134expect({ id: 1, name: 'test' }).toEqual({
135  id: expect.any(Number),
136  name: expect.any(String),
137})
138 
139expect({ a: 1, b: 2, c: 3 }).toEqual(
140  expect.objectContaining({ a: 1 })
141)
142 
143expect([1, 2, 3, 4]).toEqual(
144  expect.arrayContaining([1, 3])
145)
146 
147expect('hello world').toEqual(
148  expect.stringContaining('world')
149)
150 
151expect('hello world').toEqual(
152  expect.stringMatching(/world$/)
153)
154 
155expect({ value: null }).toEqual({
156  value: expect.anything() // Matches anything except null/undefined
157})
158 
159// Negate with expect.not
160expect([1, 2]).toEqual(
161  expect.not.arrayContaining([3])
162)
163 
164// toBeOneOf - value matches any option (great for optional props)
165expect(user).toEqual({
166  name: expect.any(String),
167  middleName: expect.toBeOneOf([expect.any(String), undefined]),
168})
169 
170// schemaMatching (4.0+) - matches any Standard Schema (Zod, Valibot, ArkType)
171import { z } from 'zod'
172expect(payload).toEqual({
173  email: expect.schemaMatching(z.string().email()),
174})
175expect(repo.save).toHaveBeenCalledWith(expect.schemaMatching(UserSchema))
176```
177 
178## Soft Assertions
179 
180Prefer `expect.soft` for **non-critical assertions** — it marks the test failed but continues so all failures are reported together:
181 
182```ts
183expect.soft(response.status).toBe(200) // non-critical, keeps going
184expect.soft(response.headers.get('x-id')).toBeTruthy()
185expect(response.body).toBeDefined() // critical: hard expect stops on failure
186```
187 
188## Type-Narrowing Assertions (4.0+)
189 
190`expect.assert` throws at runtime **and** narrows the TypeScript type (unlike `toBeTruthy`/`toBeDefined`, which return `void`):
191 
192```ts
193const user = cache.get('alice') // { id, name } | undefined
194expect.assert(user)             // throws if undefined, narrows below
195expect(user.name).toBe('Alice') // no `!`, no `as`
196 
197// Narrows typeof / instanceof too
198expect.assert(typeof input === 'string')
199input.toUpperCase()
200 
201// Chai assert helpers via the same namespace
202expect.assert.isDefined(maybeUser)
203expect.assert.instanceOf(error, MyError)
204```
205 
206## Poll Assertions
207 
208Retry until passes:
209 
210```ts
211await expect.poll(() => fetchStatus()).toBe('ready')
212 
213await expect.poll(
214  () => document.querySelector('.element'),
215  { interval: 100, timeout: 5000 }
216).toBeTruthy()
217```
218 
219## Assertion Count
220 
221```ts
222test('async assertions', async () => {
223  expect.assertions(2) // Exactly 2 assertions must run
224  
225  await doAsync((data) => {
226    expect(data).toBeDefined()
227    expect(data.id).toBe(1)
228  })
229})
230 
231test('at least one', () => {
232  expect.hasAssertions() // At least 1 assertion must run
233})
234```
235 
236## Extending Matchers
237 
238```ts
239expect.extend({
240  toBeWithinRange(received, floor, ceiling) {
241    const pass = received >= floor && received <= ceiling
242    return {
243      pass,
244      message: () => 
245        `expected ${received} to be within range ${floor} - ${ceiling}`,
246    }
247  },
248})
249 
250test('custom matcher', () => {
251  expect(100).toBeWithinRange(90, 110)
252})
253```
254 
255## Snapshot Assertions
256 
257```ts
258expect(data).toMatchSnapshot()
259expect(data).toMatchInlineSnapshot(`{ "id": 1 }`)
260await expect(result).toMatchFileSnapshot('./expected.json')
261 
262expect(() => throw new Error('fail')).toThrowErrorMatchingSnapshot()
263```
264 
265## Key Points
266 
267- Use `toBe` for primitives, `toEqual` for objects/arrays
268- `toStrictEqual` checks undefined properties and array sparseness
269- Always `await` async assertions (`resolves`, `rejects`, `poll`)
270- Use context's `expect` in concurrent tests for correct tracking
271- `toThrow` requires wrapping sync code in a function
272- Use `expect.soft` for non-critical assertions; reserve hard `expect` for must-pass conditions
273- Use `expect.assert` (not `toBeTruthy`) when you also need TypeScript narrowing
274 
275<!-- 
276Source references:
277- https://vitest.dev/api/expect.html
278- https://vitest.dev/guide/recipes/type-narrowing
279- https://vitest.dev/guide/recipes/schema-matching
280-->
281