1---
2name: describe-api
3description: describe/suite for grouping tests into logical blocks
4---
5 
6# Describe API
7 
8Group related tests into suites for organization and shared setup.
9 
10## Basic Usage
11 
12```ts
13import { describe, expect, test } from 'vitest'
14 
15describe('Math', () => {
16  test('adds numbers', () => {
17    expect(1 + 1).toBe(2)
18  })
19 
20  test('subtracts numbers', () => {
21    expect(3 - 1).toBe(2)
22  })
23})
24 
25// Alias: suite
26import { suite } from 'vitest'
27suite('equivalent to describe', () => {})
28```
29 
30## Nested Suites
31 
32```ts
33describe('User', () => {
34  describe('when logged in', () => {
35    test('shows dashboard', () => {})
36    test('can update profile', () => {})
37  })
38 
39  describe('when logged out', () => {
40    test('shows login page', () => {})
41  })
42})
43```
44 
45## Suite Options
46 
47```ts
48// All tests inherit options
49describe('slow tests', { timeout: 30_000 }, () => {
50  test('test 1', () => {}) // 30s timeout
51  test('test 2', () => {}) // 30s timeout
52})
53```
54 
55## Suite Modifiers
56 
57### Skip Suites
58 
59```ts
60describe.skip('skipped suite', () => {
61  test('wont run', () => {})
62})
63 
64// Conditional
65describe.skipIf(process.env.CI)('not in CI', () => {})
66describe.runIf(!process.env.CI)('only local', () => {})
67```
68 
69### Focus Suites
70 
71```ts
72describe.only('only this suite runs', () => {
73  test('runs', () => {})
74})
75```
76 
77### Todo Suites
78 
79```ts
80describe.todo('implement later')
81```
82 
83### Concurrent Suites
84 
85```ts
86// All tests run in parallel
87describe.concurrent('parallel tests', () => {
88  test('test 1', async ({ expect }) => {})
89  test('test 2', async ({ expect }) => {})
90})
91```
92 
93### Sequential in Concurrent
94 
95```ts
96describe.concurrent('parallel', () => {
97  test('concurrent 1', async () => {})
98  
99  describe.sequential('must be sequential', () => {
100    test('step 1', async () => {})
101    test('step 2', async () => {})
102  })
103})
104```
105 
106### Shuffle Tests
107 
108```ts
109describe.shuffle('random order', () => {
110  test('test 1', () => {})
111  test('test 2', () => {})
112  test('test 3', () => {})
113})
114 
115// Or with option
116describe('random', { shuffle: true }, () => {})
117```
118 
119## Parameterized Suites
120 
121### describe.each
122 
123```ts
124describe.each([
125  { name: 'Chrome', version: 100 },
126  { name: 'Firefox', version: 90 },
127])('$name browser', ({ name, version }) => {
128  test('has version', () => {
129    expect(version).toBeGreaterThan(0)
130  })
131})
132```
133 
134### describe.for
135 
136```ts
137describe.for([
138  ['Chrome', 100],
139  ['Firefox', 90],
140])('%s browser', ([name, version]) => {
141  test('has version', () => {
142    expect(version).toBeGreaterThan(0)
143  })
144})
145```
146 
147## Hooks in Suites
148 
149```ts
150describe('Database', () => {
151  let db
152 
153  beforeAll(async () => {
154    db = await createDb()
155  })
156 
157  afterAll(async () => {
158    await db.close()
159  })
160 
161  beforeEach(async () => {
162    await db.clear()
163  })
164 
165  test('insert works', async () => {
166    await db.insert({ name: 'test' })
167    expect(await db.count()).toBe(1)
168  })
169})
170```
171 
172## Modifier Combinations
173 
174All modifiers can be chained:
175 
176```ts
177describe.skip.concurrent('skipped concurrent', () => {})
178describe.only.shuffle('only and shuffled', () => {})
179describe.concurrent.skip('equivalent', () => {})
180```
181 
182## Key Points
183 
184- Top-level tests belong to an implicit file suite
185- Nested suites inherit parent's options (timeout, retry, etc.)
186- Hooks are scoped to their suite and nested suites
187- Use `describe.concurrent` with context's `expect` for snapshots
188- Shuffle order depends on `sequence.seed` config
189 
190<!-- 
191Source references:
192- https://vitest.dev/api/describe.html
193-->
194