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 
103## Asymmetric Matchers
104 
105Use inside `toEqual`, `toHaveBeenCalledWith`, etc:
106 
107```ts
108expect({ id: 1, name: 'test' }).toEqual({
109  id: expect.any(Number),
110  name: expect.any(String),
111})
112 
113expect({ a: 1, b: 2, c: 3 }).toEqual(
114  expect.objectContaining({ a: 1 })
115)
116 
117expect([1, 2, 3, 4]).toEqual(
118  expect.arrayContaining([1, 3])
119)
120 
121expect('hello world').toEqual(
122  expect.stringContaining('world')
123)
124 
125expect('hello world').toEqual(
126  expect.stringMatching(/world$/)
127)
128 
129expect({ value: null }).toEqual({
130  value: expect.anything() // Matches anything except null/undefined
131})
132 
133// Negate with expect.not
134expect([1, 2]).toEqual(
135  expect.not.arrayContaining([3])
136)
137```
138 
139## Soft Assertions
140 
141Continue test after failure:
142 
143```ts
144expect.soft(1).toBe(2) // Marks test failed but continues
145expect.soft(2).toBe(3) // Also runs
146// All failures reported at end
147```
148 
149## Poll Assertions
150 
151Retry until passes:
152 
153```ts
154await expect.poll(() => fetchStatus()).toBe('ready')
155 
156await expect.poll(
157  () => document.querySelector('.element'),
158  { interval: 100, timeout: 5000 }
159).toBeTruthy()
160```
161 
162## Assertion Count
163 
164```ts
165test('async assertions', async () => {
166  expect.assertions(2) // Exactly 2 assertions must run
167  
168  await doAsync((data) => {
169    expect(data).toBeDefined()
170    expect(data.id).toBe(1)
171  })
172})
173 
174test('at least one', () => {
175  expect.hasAssertions() // At least 1 assertion must run
176})
177```
178 
179## Extending Matchers
180 
181```ts
182expect.extend({
183  toBeWithinRange(received, floor, ceiling) {
184    const pass = received >= floor && received <= ceiling
185    return {
186      pass,
187      message: () => 
188        `expected ${received} to be within range ${floor} - ${ceiling}`,
189    }
190  },
191})
192 
193test('custom matcher', () => {
194  expect(100).toBeWithinRange(90, 110)
195})
196```
197 
198## Snapshot Assertions
199 
200```ts
201expect(data).toMatchSnapshot()
202expect(data).toMatchInlineSnapshot(`{ "id": 1 }`)
203await expect(result).toMatchFileSnapshot('./expected.json')
204 
205expect(() => throw new Error('fail')).toThrowErrorMatchingSnapshot()
206```
207 
208## Key Points
209 
210- Use `toBe` for primitives, `toEqual` for objects/arrays
211- `toStrictEqual` checks undefined properties and array sparseness
212- Always `await` async assertions (`resolves`, `rejects`, `poll`)
213- Use context's `expect` in concurrent tests for correct tracking
214- `toThrow` requires wrapping sync code in a function
215 
216<!-- 
217Source references:
218- https://vitest.dev/api/expect.html
219-->
220