1---
2name: test-context-fixtures
3description: Test context, custom fixtures with test.extend
4---
5 
6# Test Context & Fixtures
7 
8## Built-in Context
9 
10Every test receives context as first argument:
11 
12```ts
13test('context', ({ task, expect, skip }) => {
14  console.log(task.name)  // Test name
15  expect(1).toBe(1)       // Context-bound expect
16  skip()                  // Skip test dynamically
17})
18```
19 
20### Context Properties
21 
22- `task` - Test metadata (name, file, etc.)
23- `expect` - Expect bound to this test (important for concurrent tests)
24- `skip(condition?, message?)` - Skip the test
25- `onTestFinished(fn)` - Cleanup after test
26- `onTestFailed(fn)` - Run on failure only
27 
28## Custom Fixtures with test.extend
29 
30Create reusable test utilities:
31 
32```ts
33import { test as base } from 'vitest'
34 
35// Define fixture types
36interface Fixtures {
37  db: Database
38  user: User
39}
40 
41// Create extended test
42export const test = base.extend<Fixtures>({
43  // Fixture with setup/teardown
44  db: async ({}, use) => {
45    const db = await createDatabase()
46    await use(db)           // Provide to test
47    await db.close()        // Cleanup
48  },
49  
50  // Fixture depending on another fixture
51  user: async ({ db }, use) => {
52    const user = await db.createUser({ name: 'Test' })
53    await use(user)
54    await db.deleteUser(user.id)
55  },
56})
57```
58 
59Using fixtures:
60 
61```ts
62test('query user', async ({ db, user }) => {
63  const found = await db.findUser(user.id)
64  expect(found).toEqual(user)
65})
66```
67 
68## Fixture Initialization
69 
70Fixtures only initialize when accessed:
71 
72```ts
73const test = base.extend({
74  expensive: async ({}, use) => {
75    console.log('initializing')  // Only runs if test uses it
76    await use('value')
77  },
78})
79 
80test('no fixture', () => {})           // expensive not called
81test('uses fixture', ({ expensive }) => {}) // expensive called
82```
83 
84## Auto Fixtures
85 
86Run fixture for every test:
87 
88```ts
89const test = base.extend({
90  setup: [
91    async ({}, use) => {
92      await globalSetup()
93      await use()
94      await globalTeardown()
95    },
96    { auto: true }  // Always run
97  ],
98})
99```
100 
101## Scoped Fixtures
102 
103### File Scope
104 
105Initialize once per file:
106 
107```ts
108const test = base.extend({
109  connection: [
110    async ({}, use) => {
111      const conn = await connect()
112      await use(conn)
113      await conn.close()
114    },
115    { scope: 'file' }
116  ],
117})
118```
119 
120### Worker Scope
121 
122Initialize once per worker:
123 
124```ts
125const test = base.extend({
126  sharedResource: [
127    async ({}, use) => {
128      await use(globalResource)
129    },
130    { scope: 'worker' }
131  ],
132})
133```
134 
135## Injected Fixtures (from Config)
136 
137Override fixtures per project:
138 
139```ts
140// test file
141const test = base.extend({
142  apiUrl: ['/default', { injected: true }],
143})
144 
145// vitest.config.ts
146defineConfig({
147  test: {
148    projects: [
149      {
150        test: {
151          name: 'prod',
152          provide: { apiUrl: 'https://api.prod.com' },
153        },
154      },
155    ],
156  },
157})
158```
159 
160## Scoped Values per Suite
161 
162Override fixture for specific suite:
163 
164```ts
165const test = base.extend({
166  environment: 'development',
167})
168 
169describe('production tests', () => {
170  test.scoped({ environment: 'production' })
171  
172  test('uses production', ({ environment }) => {
173    expect(environment).toBe('production')
174  })
175})
176 
177test('uses default', ({ environment }) => {
178  expect(environment).toBe('development')
179})
180```
181 
182## Extended Test Hooks
183 
184Type-aware hooks with fixtures:
185 
186```ts
187const test = base.extend<{ db: Database }>({
188  db: async ({}, use) => {
189    const db = await createDb()
190    await use(db)
191    await db.close()
192  },
193})
194 
195// Hooks know about fixtures
196test.beforeEach(({ db }) => {
197  db.seed()
198})
199 
200test.afterEach(({ db }) => {
201  db.clear()
202})
203```
204 
205## Composing Fixtures
206 
207Extend from another extended test:
208 
209```ts
210// base-test.ts
211export const test = base.extend<{ db: Database }>({
212  db: async ({}, use) => { /* ... */ },
213})
214 
215// admin-test.ts
216import { test as dbTest } from './base-test'
217 
218export const test = dbTest.extend<{ admin: User }>({
219  admin: async ({ db }, use) => {
220    const admin = await db.createAdmin()
221    await use(admin)
222  },
223})
224```
225 
226## Key Points
227 
228- Use `{ }` destructuring to access fixtures
229- Fixtures are lazy - only initialize when accessed
230- Return cleanup function from fixtures
231- Use `{ auto: true }` for setup fixtures
232- Use `{ scope: 'file' }` for expensive shared resources
233- Fixtures compose - extend from extended tests
234 
235<!-- 
236Source references:
237- https://vitest.dev/guide/test-context.html
238-->
239