0
# Core Testing API
1

2
Primary API for creating and running tests with configuration, CLI processing, and execution management.
3

4
## Capabilities
5

6
### Test Function
7

8
Creates a Japa test. Defining a test without the callback will create a todo test.
9

10
```typescript { .api }
11
/**
12
 * Create a Japa test. Defining a test without the callback will create a todo test.
13
 * @param title - The test title
14
 * @param callback - Optional test executor function
15
 * @returns Test instance for chaining
16
 */
17
function test(title: string, callback?: TestExecutor<TestContext, undefined>): Test<undefined>;
18

19
interface TestExecutor<Context, TestData> {
20
  (context: Context, done?: Function): void | Promise<void>;
21
}
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { test } from "@japa/runner";
28
import { assert } from "chai"; // or your preferred assertion library
29

30
// Basic test
31
test("should calculate sum correctly", async (ctx) => {
32
  const result = 2 + 3;
33
  assert.equal(result, 5);
34
});
35

36
// Todo test (without callback)
37
test("should implement user authentication");
38

39
// Test with custom timeout
40
test("should handle async operations", async (ctx) => {
41
  await new Promise(resolve => setTimeout(resolve, 1000));
42
  assert.isTrue(true);
43
}).timeout(2000);
44
```
45

46
### Configure Function
47

48
Configure the tests runner with inline configuration. Must be called before the run method.
49

50
```typescript { .api }
51
/**
52
 * Configure the tests runner with inline configuration.
53
 * Must be called before the run method.
54
 * CLI flags will overwrite the options provided to the configure method.
55
 * @param options - Configuration options
56
 */
57
function configure(options: Config): void;
58

59
interface Config {
60
  cwd?: string;
61
  timeout?: number;
62
  retries?: number;
63
  filters?: Filters;
64
  configureSuite?: (suite: Suite) => void;
65
  reporters?: {
66
    activated: string[];
67
    list?: NamedReporterContract[];
68
  };
69
  plugins?: PluginFn[];
70
  importer?: (filePath: URL) => void | Promise<void>;
71
  refiner?: Refiner;
72
  forceExit?: boolean;
73
  setup?: SetupHookHandler[];
74
  teardown?: TeardownHookHandler[];
75
  exclude?: string[];
76
} & (
77
  | { files: TestFiles }
78
  | { suites: TestSuite[] }
79
);
80

81
interface Filters {
82
  files?: string[];
83
  suites?: string[];
84
  tests?: string | string[];
85
  groups?: string | string[];
86
  tags?: string | string[];
87
}
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
import { configure } from "@japa/runner";
94

95
// Basic configuration with files
96
configure({
97
  files: ["tests/**/*.spec.ts"],
98
  timeout: 5000,
99
  forceExit: false,
100
});
101

102
// Configuration with suites
103
configure({
104
  suites: [
105
    {
106
      name: "unit",
107
      files: ["tests/unit/**/*.spec.ts"],
108
      timeout: 2000,
109
    },
110
    {
111
      name: "integration", 
112
      files: ["tests/integration/**/*.spec.ts"],
113
      timeout: 10000,
114
    },
115
  ],
116
  filters: {
117
    tags: ["@slow", "@integration"],
118
  },
119
});
120

121
// Configuration with reporters and plugins
122
configure({
123
  files: ["tests/**/*.spec.ts"],
124
  reporters: {
125
    activated: ["spec", "ndjson"],
126
  },
127
  plugins: [myCustomPlugin()],
128
  setup: [setupDatabase],
129
  teardown: [cleanupDatabase],
130
});
131
```
132

133
### Run Function
134

135
Execute Japa tests. Calling this function will import the test files and run them.
136

137
```typescript { .api }
138
/**
139
 * Execute Japa tests. Calling this function will import the test files behind the scenes.
140
 * Must be called after configure().
141
 */
142
async function run(): Promise<void>;
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { test, configure, run } from "@japa/runner";
149

150
// Configure and run tests
151
configure({
152
  files: ["tests/**/*.spec.ts"],
153
});
154

155
// Define tests
156
test("example test", async (ctx) => {
157
  assert.isTrue(true);
158
});
159

160
// Run the tests
161
await run();
162
```
163

164
### Process CLI Args Function
165

166
Process command line arguments. The parsed output will be used by Japa to compute the configuration.
167

168
```typescript { .api }
169
/**
170
 * Make Japa process command line arguments. 
171
 * Later the parsed output will be used by Japa to compute the configuration.
172
 * @param argv - Array of command line arguments
173
 */
174
function processCLIArgs(argv: string[]): void;
175
```
176

177
**Usage Examples:**
178

179
```typescript
180
import { processCLIArgs, configure, run } from "@japa/runner";
181

182
// Process CLI arguments
183
processCLIArgs(process.argv.slice(2));
184

185
// Configure and run tests
186
configure({
187
  files: ["tests/**/*.spec.ts"],
188
});
189

190
await run();
191
```
192

193
### Active Test Helpers
194

195
Helper functions to access the currently running test instance.
196

197
```typescript { .api }
198
/**
199
 * Get the currently running test instance
200
 * @returns Current test instance or undefined if not in test context
201
 */
202
function getActiveTest(): Test<any> | undefined;
203

204
/**
205
 * Get the currently running test instance or throw an error
206
 * @returns Current test instance
207
 * @throws Error if not in test context
208
 */
209
function getActiveTestOrFail(): Test<any>;
210
```
211

212
**Usage Examples:**
213

214
```typescript
215
import { test, getActiveTest, getActiveTestOrFail } from "@japa/runner";
216

217
// Using in a macro
218
const assertUserExists = test.macro(() => {
219
  const currentTest = getActiveTestOrFail();
220
  currentTest.cleanup(() => {
221
    // Cleanup logic here
222
  });
223
  
224
  // Test logic here
225
});
226

227
test("user operations", (ctx) => {
228
  assertUserExists();
229
  // Test continues...
230
});
231
```
232

233
## Types
234

235
### Test Executor Type
236

237
```typescript { .api }
238
interface TestExecutor<Context, TestData> {
239
  (context: Context, done?: Function): void | Promise<void>;
240
}
241
```
242

243
### Test Files Type
244

245
```typescript { .api }
246
type TestFiles = string | string[] | (() => URL[] | Promise<URL[]>);
247
```
248

249
### Test Suite Type
250

251
```typescript { .api }
252
interface TestSuite {
253
  name: string;
254
  files: TestFiles;
255
  configure?: (suite: Suite) => void;
256
  timeout?: number;
257
  retries?: number;
258
}
259
```