1---
2name: lifecycle-hooks
3description: beforeEach, afterEach, beforeAll, afterAll, and around hooks
4---
5 
6# Lifecycle Hooks
7 
8## Basic Hooks
9 
10```ts
11import { afterAll, afterEach, beforeAll, beforeEach, test } from 'vitest'
12 
13beforeAll(async () => {
14  // Runs once before all tests in file/suite
15  await setupDatabase()
16})
17 
18afterAll(async () => {
19  // Runs once after all tests in file/suite
20  await teardownDatabase()
21})
22 
23beforeEach(async () => {
24  // Runs before each test
25  await clearTestData()
26})
27 
28afterEach(async () => {
29  // Runs after each test
30  await cleanupMocks()
31})
32```
33 
34## Cleanup Return Pattern
35 
36Return cleanup function from `before*` hooks:
37 
38```ts
39beforeAll(async () => {
40  const server = await startServer()
41  
42  // Returned function runs as afterAll
43  return async () => {
44    await server.close()
45  }
46})
47 
48beforeEach(async () => {
49  const connection = await connect()
50  
51  // Runs as afterEach
52  return () => connection.close()
53})
54```
55 
56## Scoped Hooks
57 
58Hooks apply to current suite and nested suites:
59 
60```ts
61describe('outer', () => {
62  beforeEach(() => console.log('outer before'))
63  
64  test('test 1', () => {}) // outer before → test
65  
66  describe('inner', () => {
67    beforeEach(() => console.log('inner before'))
68    
69    test('test 2', () => {}) // outer before → inner before → test
70  })
71})
72```
73 
74## Hook Timeout
75 
76```ts
77beforeAll(async () => {
78  await slowSetup()
79}, 30_000) // 30 second timeout
80```
81 
82## Around Hooks
83 
84Wrap tests with setup/teardown context:
85 
86```ts
87import { aroundEach, test } from 'vitest'
88 
89// Wrap each test in database transaction
90aroundEach(async (runTest) => {
91  await db.beginTransaction()
92  await runTest() // Must be called!
93  await db.rollback()
94})
95 
96test('insert user', async () => {
97  await db.insert({ name: 'Alice' })
98  // Automatically rolled back after test
99})
100```
101 
102### aroundAll
103 
104Wrap entire suite:
105 
106```ts
107import { aroundAll, test } from 'vitest'
108 
109aroundAll(async (runSuite) => {
110  console.log('before all tests')
111  await runSuite() // Must be called!
112  console.log('after all tests')
113})
114```
115 
116### Multiple Around Hooks
117 
118Nested like onion layers:
119 
120```ts
121aroundEach(async (runTest) => {
122  console.log('outer before')
123  await runTest()
124  console.log('outer after')
125})
126 
127aroundEach(async (runTest) => {
128  console.log('inner before')
129  await runTest()
130  console.log('inner after')
131})
132 
133// Order: outer before → inner before → test → inner after → outer after
134```
135 
136## Test Hooks
137 
138Inside test body:
139 
140```ts
141import { onTestFailed, onTestFinished, test } from 'vitest'
142 
143test('with cleanup', () => {
144  const db = connect()
145  
146  // Runs after test finishes (pass or fail)
147  onTestFinished(() => db.close())
148  
149  // Only runs if test fails
150  onTestFailed(({ task }) => {
151    console.log('Failed:', task.result?.errors)
152  })
153  
154  db.query('SELECT * FROM users')
155})
156```
157 
158### Reusable Cleanup Pattern
159 
160```ts
161function useTestDb() {
162  const db = connect()
163  onTestFinished(() => db.close())
164  return db
165}
166 
167test('query users', () => {
168  const db = useTestDb()
169  expect(db.query('SELECT * FROM users')).toBeDefined()
170})
171 
172test('query orders', () => {
173  const db = useTestDb() // Fresh connection, auto-closed
174  expect(db.query('SELECT * FROM orders')).toBeDefined()
175})
176```
177 
178## Concurrent Test Hooks
179 
180For concurrent tests, use context's hooks:
181 
182```ts
183test.concurrent('concurrent', ({ onTestFinished }) => {
184  const resource = allocate()
185  onTestFinished(() => resource.release())
186})
187```
188 
189## Extended Test Hooks
190 
191With `test.extend`, hooks are type-aware:
192 
193```ts
194const test = base.extend<{ db: Database }>({
195  db: async ({}, use) => {
196    const db = await createDb()
197    await use(db)
198    await db.close()
199  },
200})
201 
202// These hooks know about `db` fixture
203test.beforeEach(({ db }) => {
204  db.seed()
205})
206 
207test.afterEach(({ db }) => {
208  db.clear()
209})
210```
211 
212## Hook Execution Order
213 
214Default order (stack):
2151. `beforeAll` (in order)
2162. `beforeEach` (in order)
2173. Test
2184. `afterEach` (reverse order)
2195. `afterAll` (reverse order)
220 
221Configure with `sequence.hooks`:
222 
223```ts
224defineConfig({
225  test: {
226    sequence: {
227      hooks: 'list', // 'stack' (default), 'list', 'parallel'
228    },
229  },
230})
231```
232 
233## Key Points
234 
235- Hooks are not called during type checking
236- Return cleanup function from `before*` to avoid `after*` duplication
237- `aroundEach`/`aroundAll` must call `runTest()`/`runSuite()`
238- `onTestFinished` always runs, even if test fails
239- Use context hooks for concurrent tests
240 
241<!-- 
242Source references:
243- https://vitest.dev/api/hooks.html
244-->
245