0
# Configuration System
1

2
Comprehensive configuration options for test execution, filtering, and environment setup.
3

4
## Capabilities
5

6
### Base Configuration
7

8
Core configuration options that apply to all test execution modes.
9

10
```typescript { .api }
11
interface BaseConfig {
12
  /** Current working directory for searching test files */
13
  cwd?: string;
14
  /** Default timeout for all tests (can be overridden per test) */
15
  timeout?: number;
16
  /** Default retries for all tests (can be overridden per test) */
17
  retries?: number;
18
  /** Test filters to apply */
19
  filters?: Filters;
20
  /** Hook to configure suites before execution */
21
  configureSuite?: (suite: Suite) => void;
22
  /** Reporter configuration */
23
  reporters?: {
24
    activated: string[];
25
    list?: NamedReporterContract[];
26
  };
27
  /** Array of plugins to register */
28
  plugins?: PluginFn[];
29
  /** Custom test file importer */
30
  importer?: (filePath: URL) => void | Promise<void>;
31
  /** Custom test refiner for filtering */
32
  refiner?: Refiner;
33
  /** Force exit after test completion */
34
  forceExit?: boolean;
35
  /** Global setup hooks */
36
  setup?: SetupHookHandler[];
37
  /** Global teardown hooks */
38
  teardown?: TeardownHookHandler[];
39
  /** Directories to exclude when searching for test files */
40
  exclude?: string[];
41
}
42
```
43

44
### Configuration with Files
45

46
Configuration for running tests from file patterns.
47

48
```typescript { .api }
49
interface ConfigWithFiles extends BaseConfig {
50
  /** Test files to execute - glob patterns, arrays, or functions */
51
  files: TestFiles;
52
}
53

54
type TestFiles = string | string[] | (() => URL[] | Promise<URL[]>);
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { configure } from "@japa/runner";
61

62
// Simple file-based configuration
63
configure({
64
  files: ["tests/**/*.spec.ts"],
65
  timeout: 5000,
66
  forceExit: false,
67
});
68

69
// Advanced file patterns
70
configure({
71
  files: [
72
    "tests/unit/**/*.spec.ts",
73
    "tests/integration/**/*.spec.ts",
74
    "!tests/**/*.skip.ts", // Exclude files
75
  ],
76
  cwd: process.cwd(),
77
  exclude: ["node_modules", "build"],
78
});
79

80
// Dynamic file loading
81
configure({
82
  files: async () => {
83
    const testFiles = await discoverTestFiles();
84
    return testFiles.map(file => new URL(file, import.meta.url));
85
  },
86
});
87
```
88

89
### Configuration with Suites
90

91
Configuration for organizing tests into named suites with different settings.
92

93
```typescript { .api }
94
interface ConfigWithSuites extends BaseConfig {
95
  /** Array of test suites with individual configuration */
96
  suites: TestSuite[];
97
}
98

99
interface TestSuite {
100
  /** Unique name for the suite */
101
  name: string;
102
  /** Files associated with this suite */
103
  files: TestFiles;
104
  /** Function to configure the suite */
105
  configure?: (suite: Suite) => void;
106
  /** Suite-specific timeout */
107
  timeout?: number;
108
  /** Suite-specific retries */
109
  retries?: number;
110
}
111
```
112

113
**Usage Examples:**
114

115
```typescript
116
import { configure } from "@japa/runner";
117

118
configure({
119
  suites: [
120
    {
121
      name: "unit",
122
      files: ["tests/unit/**/*.spec.ts"],
123
      timeout: 2000,
124
      configure: (suite) => {
125
        suite.timeout(2000);
126
      },
127
    },
128
    {
129
      name: "integration",
130
      files: ["tests/integration/**/*.spec.ts"],
131
      timeout: 10000,
132
      retries: 2,
133
      configure: (suite) => {
134
        suite.timeout(10000);
135
      },
136
    },
137
    {
138
      name: "e2e",
139
      files: () => import("./e2e-file-discovery.js").then(m => m.getE2EFiles()),
140
      timeout: 30000,
141
    },
142
  ],
143
});
144
```
145

146
### Filter Configuration
147

148
Advanced filtering options for running specific tests, groups, or files.
149

150
```typescript { .api }
151
interface Filters {
152
  /** File patterns to include */
153
  files?: string[];
154
  /** Suite names to include */
155
  suites?: string[];
156
  /** Test patterns to include */
157
  tests?: string | string[];
158
  /** Group patterns to include */
159
  groups?: string | string[];
160
  /** Tags to include */
161
  tags?: string | string[];
162
}
163
```
164

165
**Usage Examples:**
166

167
```typescript
168
import { configure } from "@japa/runner";
169

170
// Filter by patterns
171
configure({
172
  files: ["tests/**/*.spec.ts"],
173
  filters: {
174
    tests: ["should authenticate*", "*validation*"],
175
    groups: ["User Management", "API Tests"],
176
    tags: ["@slow", "@integration"],
177
  },
178
});
179

180
// Filter by files and suites
181
configure({
182
  suites: [
183
    { name: "unit", files: ["tests/unit/**/*.spec.ts"] },
184
    { name: "integration", files: ["tests/integration/**/*.spec.ts"] },
185
  ],
186
  filters: {
187
    suites: ["unit"], // Only run unit tests
188
    files: ["**/auth*.spec.ts"], // Only auth-related files
189
  },
190
});
191
```
192

193
### Reporter Configuration
194

195
Configuration for test output formatting and reporting.
196

197
```typescript { .api }
198
interface ReporterConfig {
199
  /** Names of activated reporters */
200
  activated: string[];
201
  /** Custom reporter instances */
202
  list?: NamedReporterContract[];
203
}
204

205
interface NamedReporterContract {
206
  name: string;
207
  handler: (...args: any[]) => ReporterContract;
208
}
209

210
interface BaseReporterOptions {
211
  framesMaxLimit?: number;
212
}
213
```
214

215
**Usage Examples:**
216

217
```typescript
218
import { configure } from "@japa/runner";
219
import { spec, dot, ndjson } from "@japa/runner/reporters";
220

221
configure({
222
  files: ["tests/**/*.spec.ts"],
223
  reporters: {
224
    activated: ["spec", "custom"],
225
    list: [
226
      spec({ framesMaxLimit: 10 }),
227
      dot(),
228
      {
229
        name: "custom",
230
        handler: (runner, emitter) => ({
231
          // Custom reporter implementation
232
        }),
233
      },
234
    ],
235
  },
236
});
237
```
238

239
### Hook Configuration
240

241
Global setup and teardown hooks for test environment management.
242

243
```typescript { .api }
244
type SetupHookHandler = (runner: Runner) => void | Promise<void>;
245
type TeardownHookHandler = (error: Error | null, runner: Runner) => void | Promise<void>;
246
```
247

248
**Usage Examples:**
249

250
```typescript
251
import { configure } from "@japa/runner";
252

253
configure({
254
  files: ["tests/**/*.spec.ts"],
255
  setup: [
256
    async (runner) => {
257
      // Initialize database
258
      await connectToDatabase();
259
      console.log("Database connected");
260
    },
261
    async (runner) => {
262
      // Start test server
263
      await startTestServer();
264
      console.log("Test server started");
265
    },
266
  ],
267
  teardown: [
268
    async (error, runner) => {
269
      // Cleanup database
270
      await disconnectFromDatabase();
271
      console.log("Database disconnected");
272
    },
273
    async (error, runner) => {
274
      // Stop test server
275
      await stopTestServer();
276
      console.log("Test server stopped");
277
    },
278
  ],
279
});
280
```
281

282
### Plugin Configuration
283

284
Plugin system for extending test runner functionality.
285

286
```typescript { .api }
287
interface PluginFn {
288
  (japa: {
289
    config: NormalizedConfig;
290
    cliArgs: CLIArgs;
291
    runner: Runner;
292
    emitter: Emitter;
293
  }): void | Promise<void>;
294
}
295
```
296

297
**Usage Examples:**
298

299
```typescript
300
import { configure } from "@japa/runner";
301
import { disallowPinnedTests } from "@japa/runner/plugins";
302

303
// Custom plugin
304
const customPlugin = () => {
305
  return ({ runner, emitter, config }) => {
306
    emitter.on("test:end", (payload) => {
307
      if (payload.hasError) {
308
        console.log(`Test failed: ${payload.title}`);
309
      }
310
    });
311
  };
312
};
313

314
configure({
315
  files: ["tests/**/*.spec.ts"],
316
  plugins: [
317
    disallowPinnedTests({ disallow: true }),
318
    customPlugin(),
319
  ],
320
});
321
```
322

323
## Types
324

325
### Configuration Types
326

327
```typescript { .api }
328
type Config = BaseConfig & (
329
  | { files: TestFiles }
330
  | { suites: TestSuite[] }
331
);
332

333
interface NormalizedConfig {
334
  // All BaseConfig properties are required after normalization
335
  cwd: string;
336
  timeout: number;
337
  retries: number;
338
  filters: Filters;
339
  configureSuite: (suite: Suite) => void;
340
  reporters: {
341
    activated: string[];
342
    list: NamedReporterContract[];
343
  };
344
  plugins: PluginFn[];
345
  importer: (filePath: URL) => void | Promise<void>;
346
  refiner: Refiner;
347
  forceExit: boolean;
348
  setup: SetupHookHandler[];
349
  teardown: TeardownHookHandler[];
350
  exclude: string[];
351
} & (
352
  | { files: TestFiles }
353
  | { suites: Required<TestSuite>[] }
354
);
355
```
356

357
### CLI Args Type
358

359
```typescript { .api }
360
interface CLIArgs {
361
  _?: string[];
362
  tags?: string | string[];
363
  files?: string | string[];
364
  tests?: string | string[];
365
  groups?: string | string[];
366
  timeout?: string;
367
  retries?: string;
368
  reporters?: string | string[];
369
  forceExit?: boolean;
370
  failed?: boolean;
371
  help?: boolean;
372
  matchAll?: boolean;
373
  listPinned?: boolean;
374
  bail?: boolean;
375
  bailLayer?: string;
376
}
377
```