0
# Core Testing Functions
1

2
Primary test definition functions for creating individual tests and organizing them into suites. These functions support multiple execution patterns, configuration options, and provide the foundation for all test operations.
3

4
## Capabilities
5

6
### Test Function
7

8
The main test function for creating individual test cases. Supports multiple overloads for different usage patterns.
9

10
```javascript { .api }
11
/**
12
 * Creates and runs an individual test case
13
 * @param name - Test name (optional)
14
 * @param options - Test configuration options (optional)
15
 * @param fn - Test function to execute
16
 */
17
function test(name: string, options: TestOptions, fn: TestFn): void;
18
function test(name: string, fn: TestFn): void;
19
function test(options: TestOptions, fn: TestFn): void;
20
function test(fn: TestFn): void;
21

22
type TestFn = (t: TestContext) => any | Promise<any>;
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
import test from "test";
29

30
// Named test
31
test("should calculate sum", (t) => {
32
  const result = 2 + 3;
33
  if (result !== 5) throw new Error("Math is broken");
34
});
35

36
// Test with options
37
test("slow operation", { timeout: 5000 }, async (t) => {
38
  await new Promise(resolve => setTimeout(resolve, 1000));
39
});
40

41
// Skipped test
42
test("not ready yet", { skip: "Feature not implemented" }, (t) => {
43
  // This won't run
44
});
45

46
// Anonymous test
47
test((t) => {
48
  t.diagnostic("Running anonymous test");
49
});
50
```
51

52
### Describe Function
53

54
Groups related tests into suites for better organization and shared setup/teardown.
55

56
```javascript { .api }
57
/**
58
 * Creates a test suite grouping related tests
59
 * @param name - Suite name (optional)
60
 * @param options - Suite configuration options (optional)
61
 * @param fn - Suite function containing tests and hooks
62
 */
63
function describe(name: string, options: TestOptions, fn: SuiteFn): void;
64
function describe(name: string, fn: SuiteFn): void;
65
function describe(options: TestOptions, fn: SuiteFn): void;
66
function describe(fn: SuiteFn): void;
67

68
type SuiteFn = (t: SuiteContext) => void;
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
import { describe, it, beforeEach } from "test";
75

76
describe("User authentication", () => {
77
  beforeEach(() => {
78
    // Setup for each test in this suite
79
  });
80

81
  it("should login with valid credentials", () => {
82
    // Test implementation
83
  });
84

85
  it("should reject invalid credentials", () => {
86
    // Test implementation
87
  });
88
});
89

90
// Nested suites
91
describe("API endpoints", () => {
92
  describe("User endpoints", () => {
93
    it("should create user", () => {
94
      // Test implementation
95
    });
96
  });
97
});
98
```
99

100
### It Function
101

102
Creates individual test cases within describe blocks. Functionally identical to the test function but semantically used within suites.
103

104
```javascript { .api }
105
/**
106
 * Creates an individual test case within a suite
107
 * @param name - Test name (optional)
108
 * @param options - Test configuration options (optional)  
109
 * @param fn - Test function to execute
110
 */
111
function it(name: string, options: TestOptions, fn: ItFn): void;
112
function it(name: string, fn: ItFn): void;
113
function it(options: TestOptions, fn: ItFn): void;
114
function it(fn: ItFn): void;
115

116
type ItFn = (t: ItContext) => any | Promise<any>;
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
import { describe, it } from "test";
123

124
describe("Calculator", () => {
125
  it("should add two numbers", (t) => {
126
    const result = add(2, 3);
127
    if (result !== 5) throw new Error("Addition failed");
128
  });
129

130
  it("handles negative numbers", { timeout: 1000 }, (t) => {
131
    const result = add(-1, 1);
132
    if (result !== 0) throw new Error("Negative addition failed");
133
  });
134

135
  it("TODO: should handle decimals", { todo: true }, (t) => {
136
    // Not implemented yet
137
  });
138
});
139
```
140

141
## Test Options
142

143
```javascript { .api }
144
interface TestOptions {
145
  /** Number of tests that can run concurrently. Default: 1 */
146
  concurrency?: boolean | number;
147
  /** Skip test with optional reason. Default: false */
148
  skip?: boolean | string;
149
  /** Mark test as TODO with optional reason. Default: false */
150
  todo?: boolean | string;
151
  /** Test timeout in milliseconds. Default: Infinity */
152
  timeout?: number;
153
  /** AbortSignal for test cancellation */
154
  signal?: AbortSignal;
155
}
156
```
157

158
## Context Objects
159

160
### TestContext
161

162
Context object passed to test functions providing diagnostic and control capabilities.
163

164
```javascript { .api }
165
interface TestContext {
166
  /** Create subtests within the current test */
167
  test(name: string, options: TestOptions, fn: TestFn): Promise<void>;
168
  test(name: string, fn: TestFn): Promise<void>;
169
  test(fn: TestFn): Promise<void>;
170
  /** Write diagnostic information to test output */
171
  diagnostic(message: string): void;
172
  /** Mark current test as skipped */
173
  skip(message?: string): void;
174
  /** Mark current test as TODO */
175
  todo(message?: string): void;
176
  /** AbortSignal for test cancellation */
177
  signal: AbortSignal;
178
}
179
```
180

181
**Usage Examples:**
182

183
```javascript
184
test("test with subtests", async (t) => {
185
  t.diagnostic("Starting parent test");
186
  
187
  await t.test("subtest 1", (st) => {
188
    // First subtest
189
  });
190
  
191
  await t.test("subtest 2", { timeout: 500 }, (st) => {
192
    // Second subtest with timeout
193
  });
194
});
195

196
test("conditional skip", (t) => {
197
  if (!process.env.API_KEY) {
198
    t.skip("API key not provided");
199
    return;
200
  }
201
  // Test implementation
202
});
203
```
204

205
### SuiteContext
206

207
Context object passed to describe functions.
208

209
```javascript { .api }
210
interface SuiteContext {
211
  /** AbortSignal for suite cancellation */
212
  signal: AbortSignal;
213
}
214
```
215

216
### ItContext
217

218
Context object passed to it functions.
219

220
```javascript { .api }
221
interface ItContext {
222
  /** AbortSignal for test cancellation */
223
  signal: AbortSignal;
224
}
225
```
226

227
## Error Handling
228

229
Tests can fail by:
230
- Throwing any error or exception
231
- Returning a rejected Promise
232
- Timing out (when timeout option is set)
233
- Being aborted via AbortSignal
234

235
```javascript
236
test("error handling examples", (t) => {
237
  // Explicit error
238
  throw new Error("Test failed");
239
  
240
  // Assertion-style
241
  if (result !== expected) {
242
    throw new Error(`Expected ${expected}, got ${result}`);
243
  }
244
});
245

246
test("async error handling", async (t) => {
247
  // Rejected promise
248
  await Promise.reject(new Error("Async operation failed"));
249
  
250
  // Async assertion
251
  const result = await fetchData();
252
  if (!result) {
253
    throw new Error("No data received");
254
  }
255
});
256
```