1---
2name: test-api
3description: test/it function for defining tests with modifiers
4---
5 
6# Test API
7 
8## Basic Test
9 
10```ts
11import { expect, test } from 'vitest'
12 
13test('adds numbers', () => {
14  expect(1 + 1).toBe(2)
15})
16 
17// Alias: it
18import { it } from 'vitest'
19 
20it('works the same', () => {
21  expect(true).toBe(true)
22})
23```
24 
25## Async Tests
26 
27```ts
28test('async test', async () => {
29  const result = await fetchData()
30  expect(result).toBeDefined()
31})
32 
33// Promises are automatically awaited
34test('returns promise', () => {
35  return fetchData().then(result => {
36    expect(result).toBeDefined()
37  })
38})
39```
40 
41## Test Options
42 
43```ts
44// Timeout (default: 5000ms)
45test('slow test', async () => {
46  // ...
47}, 10_000)
48 
49// Or with options object
50test('with options', { timeout: 10_000, retry: 2 }, async () => {
51  // ...
52})
53```
54 
55## Test Modifiers
56 
57### Skip Tests
58 
59```ts
60test.skip('skipped test', () => {
61  // Won't run
62})
63 
64// Conditional skip
65test.skipIf(process.env.CI)('not in CI', () => {})
66test.runIf(process.env.CI)('only in CI', () => {})
67 
68// Dynamic skip via context
69test('dynamic skip', ({ skip }) => {
70  skip(someCondition, 'reason')
71  // ...
72})
73```
74 
75### Focus Tests
76 
77```ts
78test.only('only this runs', () => {
79  // Other tests in file are skipped
80})
81```
82 
83### Todo Tests
84 
85```ts
86test.todo('implement later')
87 
88test.todo('with body', () => {
89  // Not run, shows in report
90})
91```
92 
93### Failing Tests
94 
95```ts
96test.fails('expected to fail', () => {
97  expect(1).toBe(2) // Test passes because assertion fails
98})
99```
100 
101### Concurrent Tests
102 
103```ts
104// Run tests in parallel
105test.concurrent('test 1', async ({ expect }) => {
106  // Use context.expect for concurrent tests
107  expect(await fetch1()).toBe('result')
108})
109 
110test.concurrent('test 2', async ({ expect }) => {
111  expect(await fetch2()).toBe('result')
112})
113```
114 
115### Sequential Tests
116 
117```ts
118// Force sequential in concurrent context
119test.sequential('must run alone', async () => {})
120```
121 
122## Parameterized Tests
123 
124### test.each
125 
126```ts
127test.each([
128  [1, 1, 2],
129  [1, 2, 3],
130  [2, 1, 3],
131])('add(%i, %i) = %i', (a, b, expected) => {
132  expect(a + b).toBe(expected)
133})
134 
135// With objects
136test.each([
137  { a: 1, b: 1, expected: 2 },
138  { a: 1, b: 2, expected: 3 },
139])('add($a, $b) = $expected', ({ a, b, expected }) => {
140  expect(a + b).toBe(expected)
141})
142 
143// Template literal
144test.each`
145  a    | b    | expected
146  ${1} | ${1} | ${2}
147  ${1} | ${2} | ${3}
148`('add($a, $b) = $expected', ({ a, b, expected }) => {
149  expect(a + b).toBe(expected)
150})
151```
152 
153### test.for
154 
155Preferred over `.each` - doesn't spread arrays:
156 
157```ts
158test.for([
159  [1, 1, 2],
160  [1, 2, 3],
161])('add(%i, %i) = %i', ([a, b, expected], { expect }) => {
162  // Second arg is TestContext
163  expect(a + b).toBe(expected)
164})
165```
166 
167## Test Context
168 
169First argument provides context utilities:
170 
171```ts
172test('with context', ({ expect, skip, task }) => {
173  console.log(task.name)   // Test name
174  skip(someCondition)      // Skip dynamically
175  expect(1).toBe(1)        // Context-bound expect
176})
177```
178 
179## Custom Test with Fixtures
180 
181```ts
182import { test as base } from 'vitest'
183 
184const test = base.extend({
185  db: async ({}, use) => {
186    const db = await createDb()
187    await use(db)
188    await db.close()
189  },
190})
191 
192test('query', async ({ db }) => {
193  const users = await db.query('SELECT * FROM users')
194  expect(users).toBeDefined()
195})
196```
197 
198## Retry Configuration
199 
200```ts
201test('flaky test', { retry: 3 }, async () => {
202  // Retries up to 3 times on failure
203})
204 
205// Advanced retry options
206test('with delay', {
207  retry: {
208    count: 3,
209    delay: 1000,
210    condition: /timeout/i, // Only retry on timeout errors
211  },
212}, async () => {})
213```
214 
215## Tags
216 
217```ts
218test('database test', { tags: ['db', 'slow'] }, async () => {})
219 
220// Run with: vitest --tags db
221```
222 
223## Key Points
224 
225- Tests with no body are marked as `todo`
226- `test.only` throws in CI unless `allowOnly: true`
227- Use context's `expect` for concurrent tests and snapshots
228- Function name is used as test name if passed as first arg
229 
230<!-- 
231Source references:
232- https://vitest.dev/api/test.html
233-->
234