0
# Test Definition
1

2
Core functionality for defining and organizing tests into logical groups with support for various test types, execution modes, and module organization.
3

4
## Capabilities
5

6
### Basic Test Definition
7

8
Define individual tests with descriptive names and test functions.
9

10
```javascript { .api }
11
/**
12
 * Define a standard test case
13
 * @param {string} testName - Descriptive name for the test
14
 * @param {Function} callback - Test function receiving assert object
15
 */
16
QUnit.test(testName, callback)
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
import QUnit from "qunit";
23

24
QUnit.test("basic arithmetic", function(assert) {
25
  assert.strictEqual(2 + 2, 4, "addition works");
26
  assert.strictEqual(5 - 3, 2, "subtraction works");
27
});
28

29
QUnit.test("async operation", function(assert) {
30
  const done = assert.async();
31
  
32
  setTimeout(() => {
33
    assert.ok(true, "async test completed");
34
    done();
35
  }, 100);
36
});
37
```
38

39
### Test Variants
40

41
Special test types for different execution scenarios.
42

43
```javascript { .api }
44
/**
45
 * Skip a test (will not run but appears in results)
46
 * @param {string} testName - Test name
47
 * @param {Function} [callback] - Test function (optional for skip)
48
 */
49
QUnit.skip(testName, callback)
50

51
/**
52
 * TODO test (expected to fail, used for test-driven development)
53
 * @param name - Test name  
54
 * @param callback - Test function
55
 */
56
function todo(name: string, callback: (assert: Assert) => void): void;
57

58
/**
59
 * Only test (run this test exclusively, skip others)
60
 * @param name - Test name
61
 * @param callback - Test function
62
 */
63
function only(name: string, callback: (assert: Assert) => void): void;
64
```
65

66
**Usage Examples:**
67

68
```javascript
69
QUnit.skip("feature not implemented yet", function(assert) {
70
  // This test will be skipped
71
  assert.ok(false);
72
});
73

74
QUnit.todo("fix this failing test", function(assert) {
75
  // This test is expected to fail
76
  assert.strictEqual(buggyFunction(), "expected");
77
});
78

79
QUnit.only("debug this specific test", function(assert) {
80
  // Only this test will run when .only() is used
81
  assert.ok(true);
82
});
83
```
84

85
### Conditional Tests
86

87
Tests that run based on specific conditions.
88

89
```javascript { .api }
90
/**
91
 * Conditionally run test based on condition
92
 * @param name - Test name
93
 * @param condition - Boolean condition to evaluate
94
 * @param callback - Test function
95
 */
96
function if(name: string, condition: boolean, callback: (assert: Assert) => void): void;
97
```
98

99
**Usage Examples:**
100

101
```javascript
102
QUnit.test.if("browser-specific test", 
103
  typeof window !== "undefined", 
104
  function(assert) {
105
    assert.ok(window.navigator, "browser environment detected");
106
  }
107
);
108
```
109

110
### Data-Driven Tests
111

112
Run the same test logic with different data sets.
113

114
```javascript { .api }
115
/**
116
 * Run test for each item in dataset
117
 * @param name - Test name template
118
 * @param dataset - Array of test data or object with named datasets
119
 * @param callback - Test function receiving data and assert
120
 */
121
function each(
122
  name: string, 
123
  dataset: any[] | Record<string, any>, 
124
  callback: (data: any, assert: Assert) => void
125
): void;
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
QUnit.test.each("validate input", [
132
  { input: "hello", expected: true },
133
  { input: "", expected: false },
134
  { input: null, expected: false }
135
], function(data, assert) {
136
  const result = validateInput(data.input);
137
  assert.strictEqual(result, data.expected);
138
});
139

140
// Named datasets
141
QUnit.test.each("math operations", {
142
  "addition": { a: 2, b: 3, expected: 5, op: "+" },
143
  "subtraction": { a: 5, b: 2, expected: 3, op: "-" }
144
}, function(data, assert) {
145
  const result = calculate(data.a, data.b, data.op);
146
  assert.strictEqual(result, data.expected);
147
});
148
```
149

150
### Module Definition
151

152
Organize tests into logical groups with shared setup and teardown.
153

154
```javascript { .api }
155
/**
156
 * Define a test module
157
 * @param name - Module name
158
 * @param callback - Module definition function
159
 */
160
function module(name: string, callback?: () => void): void;
161

162
/**
163
 * Define a test module with hooks
164
 * @param name - Module name
165
 * @param options - Module configuration with lifecycle hooks
166
 * @param callback - Module definition function
167
 */
168
function module(
169
  name: string, 
170
  options: ModuleOptions, 
171
  callback?: () => void
172
): void;
173

174
interface ModuleOptions {
175
  /** Run once before all tests in module */
176
  before?: () => void;
177
  /** Run before each test in module */
178
  beforeEach?: (assert: Assert) => void;
179
  /** Run after each test in module */
180
  afterEach?: (assert: Assert) => void;
181
  /** Run once after all tests in module */
182
  after?: () => void;
183
}
184
```
185

186
**Usage Examples:**
187

188
```javascript
189
QUnit.module("User Management", function() {
190
  QUnit.test("user creation", function(assert) {
191
    assert.ok(true);
192
  });
193
  
194
  QUnit.test("user deletion", function(assert) {
195
    assert.ok(true);
196
  });
197
});
198

199
// Module with hooks
200
QUnit.module("Database Tests", {
201
  before: function() {
202
    // Setup database connection
203
    this.db = new Database();
204
  },
205
  
206
  beforeEach: function() {
207
    // Clear test data before each test
208
    this.db.clear();
209
  },
210
  
211
  afterEach: function() {
212
    // Cleanup after each test
213
    this.db.cleanup();
214
  },
215
  
216
  after: function() {
217
    // Close database connection
218
    this.db.close();
219
  }
220
}, function() {
221
  QUnit.test("data insertion", function(assert) {
222
    // Test has access to this.db
223
    assert.ok(this.db.insert({ name: "test" }));
224
  });
225
});
226
```
227

228
### Module Variants
229

230
Special module types for different execution scenarios.
231

232
```javascript { .api }
233
/**
234
 * Skip entire module (no tests will run)
235
 * @param name - Module name
236
 * @param options - Module options (optional)
237
 * @param callback - Module definition function (optional)
238
 */
239
function skip(
240
  name: string, 
241
  options?: ModuleOptions, 
242
  callback?: () => void
243
): void;
244

245
/**
246
 * TODO module (all tests expected to fail)
247
 * @param name - Module name
248
 * @param options - Module options (optional)
249
 * @param callback - Module definition function
250
 */
251
function todo(
252
  name: string, 
253
  options?: ModuleOptions, 
254
  callback: () => void
255
): void;
256

257
/**
258
 * Only module (run only this module, skip others)
259
 * @param name - Module name
260
 * @param options - Module options (optional)
261
 * @param callback - Module definition function
262
 */
263
function only(
264
  name: string, 
265
  options?: ModuleOptions, 
266
  callback: () => void
267
): void;
268

269
/**
270
 * Conditional module execution
271
 * @param name - Module name
272
 * @param condition - Boolean condition to evaluate
273
 * @param options - Module options (optional)
274
 * @param callback - Module definition function
275
 */
276
function if(
277
  name: string, 
278
  condition: boolean, 
279
  options?: ModuleOptions, 
280
  callback?: () => void
281
): void;
282
```
283

284
### Test Control
285

286
Global controls for test execution.
287

288
```javascript { .api }
289
/**
290
 * Manually start test suite (when autostart is false)
291
 * @param count - Number of expected start calls (optional)
292
 */
293
function start(count?: number): void;
294

295
/**
296
 * Get stack trace information
297
 * @param offset - Number of stack frames to skip (optional)
298
 * @returns Stack trace string
299
 */
300
function stack(offset?: number): string;
301
```
302

303
**Usage Examples:**
304

305
```javascript
306
// Disable autostart for manual control
307
QUnit.config.autostart = false;
308

309
// Load additional resources
310
loadTestData().then(() => {
311
  // Start tests after resources are ready
312
  QUnit.start();
313
});
314
```
315

316
## Types
317

318
```javascript { .api }
319
interface TestContext {
320
  /** Test timeout value */
321
  timeout?: number;
322
  /** Custom test properties */
323
  [key: string]: any;
324
}
325

326
interface ModuleContext {
327
  /** Module name */
328
  name: string;
329
  /** Parent module (for nested modules) */
330
  parent?: ModuleContext;
331
  /** Custom module properties */
332
  [key: string]: any;
333
}
334
```