0
# Japa Runner
1
2
Japa is a simple yet powerful testing framework specifically designed for Node.js backend applications and libraries. It offers a complete testing solution with a focus on simplicity, performance, and minimal bloat compared to frontend-oriented testing frameworks.
3
4
## Package Information
5
6
- **Package Name**: @japa/runner
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @japa/runner`
10
11
## Core Imports
12
13
```typescript
14
import { test, configure, run } from "@japa/runner";
15
```
16
17
For additional functionality:
18
19
```typescript
20
import { Test, Suite, Runner, Group, Emitter } from "@japa/runner/core";
21
import { spec, dot, ndjson, github } from "@japa/runner/reporters";
22
import { disallowPinnedTests } from "@japa/runner/plugins";
23
import { runner } from "@japa/runner/factories";
24
import type { Config, CLIArgs, PluginFn } from "@japa/runner/types";
25
```
26
27
For CommonJS:
28
29
```javascript
30
const { test, configure, run } = require("@japa/runner");
31
```
32
33
## Basic Usage
34
35
```typescript
36
import { test, configure, run } from "@japa/runner";
37
import { assert } from "chai"; // or your preferred assertion library
38
39
// Configure the test runner
40
configure({
41
files: ["tests/**/*.spec.ts"],
42
forceExit: false,
43
});
44
45
// Define tests
46
test("should add two numbers", async (ctx) => {
47
const result = 2 + 3;
48
assert.equal(result, 5);
49
});
50
51
test.group("Math operations", (group) => {
52
test("should subtract numbers", async (ctx) => {
53
const result = 5 - 3;
54
assert.equal(result, 2);
55
});
56
});
57
58
// Run the tests
59
await run();
60
```
61
62
## Architecture
63
64
Japa Runner is built around several key components:
65
66
- **Core Framework**: Test execution engine with Suite, Runner, and Test classes
67
- **Configuration System**: Flexible configuration with CLI argument processing and normalization
68
- **Plugin System**: Extensible architecture supporting custom plugins for various testing scenarios
69
- **Reporter System**: Multiple built-in reporters (spec, dot, ndjson, github) with custom reporter support
70
- **Hook System**: Global setup/teardown hooks and test-level cleanup functions
71
- **Factory System**: Test runner factory for testing reporters and plugins
72
73
## Capabilities
74
75
### Core Testing API
76
77
Primary API for creating and running tests with configuration, CLI processing, and execution management.
78
79
```typescript { .api }
80
function test(title: string, callback?: TestExecutor<TestContext, undefined>): Test<undefined>;
81
82
function configure(options: Config): void;
83
84
async function run(): Promise<void>;
85
86
function processCLIArgs(argv: string[]): void;
87
```
88
89
[Core Testing API](./core-api.md)
90
91
### Test Management
92
93
Advanced test creation, grouping, and macro functionality for organizing complex test suites.
94
95
```typescript { .api }
96
interface TestGroup {
97
(title: string, callback: (group: Group) => void): Group;
98
}
99
100
interface TestMacro {
101
<T extends (test: Test, ...args: any[]) => any>(callback: T): (...args: OmitFirstArg<Parameters<T>>) => ReturnType<T>;
102
}
103
104
function getActiveTest(): Test<any> | undefined;
105
function getActiveTestOrFail(): Test<any>;
106
```
107
108
[Test Management](./test-management.md)
109
110
### Configuration System
111
112
Comprehensive configuration options for test execution, filtering, and environment setup.
113
114
```typescript { .api }
115
interface Config {
116
cwd?: string;
117
timeout?: number;
118
retries?: number;
119
filters?: Filters;
120
configureSuite?: (suite: Suite) => void;
121
reporters?: {
122
activated: string[];
123
list?: NamedReporterContract[];
124
};
125
plugins?: PluginFn[];
126
forceExit?: boolean;
127
setup?: SetupHookHandler[];
128
teardown?: TeardownHookHandler[];
129
}
130
131
interface Filters {
132
files?: string[];
133
suites?: string[];
134
tests?: string | string[];
135
groups?: string | string[];
136
tags?: string | string[];
137
}
138
```
139
140
[Configuration System](./configuration.md)
141
142
### Reporter System
143
144
Built-in reporters and reporter creation for test output formatting and result reporting.
145
146
```typescript { .api }
147
function spec(options?: BaseReporterOptions): NamedReporterContract;
148
function dot(options?: BaseReporterOptions): NamedReporterContract;
149
function ndjson(options?: BaseReporterOptions): NamedReporterContract;
150
function github(options?: BaseReporterOptions): NamedReporterContract;
151
152
interface BaseReporterOptions {
153
framesMaxLimit?: number;
154
}
155
```
156
157
[Reporter System](./reporters.md)
158
159
### Plugin System
160
161
Plugin architecture for extending functionality with built-in and custom plugins.
162
163
```typescript { .api }
164
interface PluginFn {
165
(japa: {
166
config: NormalizedConfig;
167
cliArgs: CLIArgs;
168
runner: Runner;
169
emitter: Emitter;
170
}): void | Promise<void>;
171
}
172
173
function disallowPinnedTests(options?: {
174
disallow?: boolean;
175
errorMessage?: string;
176
}): PluginFn;
177
```
178
179
[Plugin System](./plugins.md)
180
181
### Core Classes
182
183
Low-level classes for advanced usage, testing frameworks, and plugin development.
184
185
```typescript { .api }
186
class Runner {
187
bail(toggle?: boolean): this;
188
registerReporter(reporter: ReporterContract): void;
189
getSummary(): RunnerSummary;
190
}
191
192
class Test<TestData = undefined> {
193
throws(message: string | RegExp, errorConstructor?: any): this;
194
timeout(duration: number): this;
195
retry(count: number): this;
196
}
197
198
class TestContext {
199
cleanup(cleanupCallback: TestHooksCleanupHandler<TestContext>): void;
200
}
201
```
202
203
[Core Classes](./core-classes.md)
204
205
### Factory System
206
207
Test runner factory for testing reporters, plugins, and creating isolated test environments.
208
209
```typescript { .api }
210
function runner(): RunnerFactory;
211
212
class RunnerFactory {
213
configure(config: Config, argv?: string[]): this;
214
useEmitter(emitter: Emitter): this;
215
async runTest(title: string, callback: TestExecutor<TestContext, undefined>): Promise<RunnerSummary>;
216
bail(toggle?: boolean): this;
217
async runSuites(suites: (emitter: Emitter, refiner: Refiner, file?: string) => Suite[]): Promise<RunnerSummary>;
218
}
219
```
220
221
[Factory System](./factories.md)
222
223
## Types
224
225
### Core Configuration Types
226
227
```typescript { .api }
228
interface CLIArgs {
229
_?: string[];
230
tags?: string | string[];
231
files?: string | string[];
232
tests?: string | string[];
233
groups?: string | string[];
234
timeout?: string;
235
retries?: string;
236
reporters?: string | string[];
237
forceExit?: boolean;
238
failed?: boolean;
239
help?: boolean;
240
matchAll?: boolean;
241
listPinned?: boolean;
242
bail?: boolean;
243
bailLayer?: string;
244
}
245
246
type TestFiles = string | string[] | (() => URL[] | Promise<URL[]>);
247
248
interface TestSuite {
249
name: string;
250
files: TestFiles;
251
configure?: (suite: Suite) => void;
252
timeout?: number;
253
retries?: number;
254
}
255
```
256
257
### Hook Types
258
259
```typescript { .api }
260
type SetupHookHandler = HookHandler<[runner: Runner], [error: Error | null, runner: Runner]>;
261
type TeardownHookHandler = HookHandler<[runner: Runner], [error: Error | null, runner: Runner]>;
262
263
interface HooksEvents {
264
setup: [[runner: Runner], [error: Error | null, runner: Runner]];
265
teardown: [[runner: Runner], [error: Error | null, runner: Runner]];
266
}
267
```