0
# Test Flavors
1

2
QUnit provides several test variants that allow you to control test execution and handle different testing scenarios.
3

4
## Test Variants
5

6
### Regular Tests
7

8
Standard test execution that runs as part of the normal test suite.
9

10
```javascript { .api }
11
/**
12
 * Define a regular test
13
 * @param {string} testName - Name of the test
14
 * @param {Function} callback - Test callback function
15
 */
16
QUnit.test(testName, callback)
17
```
18

19
**Usage Example:**
20

21
```javascript
22
QUnit.test("basic math operations", function(assert) {
23
  assert.strictEqual(2 + 2, 4, "addition works");
24
  assert.strictEqual(5 * 3, 15, "multiplication works");
25
});
26
```
27

28
### Skip Tests
29

30
Skip test execution entirely. Useful for temporarily disabling tests without removing them.
31

32
```javascript { .api }
33
/**
34
 * Skip a test (will not execute)
35
 * @param {string} testName - Name of the test
36
 * @param {Function} [callback] - Test callback (optional for skip)
37
 */
38
QUnit.skip(testName, callback)
39
```
40

41
**Usage Example:**
42

43
```javascript
44
QUnit.skip("broken feature test", function(assert) {
45
  // This test will be skipped and not executed
46
  assert.ok(brokenFeature(), "this won't run");
47
});
48
```
49

50
### Only Tests
51

52
Run only specific tests, ignoring all others. Useful for focusing on specific functionality during development.
53

54
```javascript { .api }
55
/**
56
 * Run only this test (ignores all other tests)
57
 * @param {string} testName - Name of the test
58
 * @param {Function} callback - Test callback function
59
 */
60
QUnit.only(testName, callback)
61
```
62

63
**Usage Example:**
64

65
```javascript
66
QUnit.only("focused test", function(assert) {
67
  // Only this test will run, all others will be ignored
68
  assert.ok(true, "this is the only test that runs");
69
});
70

71
QUnit.test("ignored test", function(assert) {
72
  // This test will be ignored when QUnit.only is used above
73
  assert.ok(false, "this won't run");
74
});
75
```
76

77
### Todo Tests
78

79
Tests that are expected to fail. These represent features not yet implemented or known bugs that need to be fixed.
80

81
```javascript { .api }
82
/**
83
 * Define a todo test (expected to fail)
84
 * @param {string} testName - Name of the test
85
 * @param {Function} callback - Test callback function
86
 */
87
QUnit.todo(testName, callback)
88
```
89

90
**Usage Example:**
91

92
```javascript
93
QUnit.todo("implement new feature", function(assert) {
94
  // This test is expected to fail until the feature is implemented
95
  assert.strictEqual(newFeature(), "expected result", "feature not implemented yet");
96
});
97
```
98

99
## Module Variants
100

101
### Regular Modules
102

103
Standard module definition that groups related tests together.
104

105
```javascript { .api }
106
/**
107
 * Define a regular module
108
 * @param {string} name - Module name
109
 * @param {Function} [scope] - Module scope function
110
 */
111
QUnit.module(name, scope)
112

113
/**
114
 * Define a module with options
115
 * @param {string} name - Module name
116
 * @param {Object} options - Module configuration
117
 * @param {Function} [scope] - Module scope function
118
 */
119
QUnit.module(name, options, scope)
120
```
121

122
**Usage Example:**
123

124
```javascript
125
QUnit.module("User Management", function() {
126
  QUnit.test("create user", function(assert) {
127
    assert.ok(createUser({name: "Alice"}), "user created");
128
  });
129
  
130
  QUnit.test("delete user", function(assert) {
131
    assert.ok(deleteUser("alice"), "user deleted");
132
  });
133
});
134
```
135

136
### Skip Modules
137

138
Skip an entire module and all its tests.
139

140
```javascript { .api }
141
/**
142
 * Skip an entire module
143
 * @param {string} name - Module name
144
 * @param {Object} [options] - Module configuration
145
 * @param {Function} [scope] - Module scope function
146
 */
147
QUnit.module.skip(name, options, scope)
148
```
149

150
**Usage Example:**
151

152
```javascript
153
QUnit.module.skip("Broken Features", function() {
154
  QUnit.test("broken test 1", function(assert) {
155
    // This entire module is skipped
156
    assert.ok(false);
157
  });
158
  
159
  QUnit.test("broken test 2", function(assert) {
160
    // This test is also skipped
161
    assert.ok(false);
162
  });
163
});
164
```
165

166
### Only Modules
167

168
Run only tests in this module, ignoring all other modules and tests.
169

170
```javascript { .api }
171
/**
172
 * Run only this module (ignores all other modules)
173
 * @param {string} name - Module name
174
 * @param {Object} [options] - Module configuration
175
 * @param {Function} [scope] - Module scope function
176
 */
177
QUnit.module.only(name, options, scope)
178
```
179

180
**Usage Example:**
181

182
```javascript
183
QUnit.module.only("Focus Module", function() {
184
  QUnit.test("focused test 1", function(assert) {
185
    assert.ok(true, "this runs");
186
  });
187
  
188
  QUnit.test("focused test 2", function(assert) {
189
    assert.ok(true, "this also runs");
190
  });
191
});
192

193
QUnit.module("Other Module", function() {
194
  QUnit.test("ignored test", function(assert) {
195
    // This entire module is ignored
196
    assert.ok(false);
197
  });
198
});
199
```
200

201
### Todo Modules
202

203
Modules where all tests are expected to fail, representing incomplete features.
204

205
```javascript { .api }
206
/**
207
 * Define a todo module (all tests expected to fail)
208
 * @param {string} name - Module name
209
 * @param {Object} [options] - Module configuration
210
 * @param {Function} [scope] - Module scope function
211
 */
212
QUnit.module.todo(name, options, scope)
213
```
214

215
**Usage Example:**
216

217
```javascript
218
QUnit.module.todo("Future Features", function() {
219
  QUnit.test("feature A", function(assert) {
220
    // Expected to fail until implemented
221
    assert.strictEqual(featureA(), "working", "not implemented");
222
  });
223
  
224
  QUnit.test("feature B", function(assert) {
225
    // Also expected to fail
226
    assert.ok(featureB(), "not implemented");
227
  });
228
});
229
```
230

231
## Test Parametrization
232

233
### Test.each()
234

235
Run the same test logic with multiple data sets.
236

237
```javascript { .api }
238
/**
239
 * Run test with multiple data sets
240
 * @param {string} testName - Base test name
241
 * @param {Array|Object} dataset - Data to iterate over
242
 * @param {Function} callback - Test callback function
243
 */
244
QUnit.test.each(testName, dataset, callback)
245
```
246

247
**Usage Example:**
248

249
```javascript
250
const mathData = [
251
  [2, 3, 5],
252
  [5, 7, 12],
253
  [10, -3, 7]
254
];
255

256
QUnit.test.each("addition", mathData, function(assert, [a, b, expected]) {
257
  assert.strictEqual(a + b, expected, `${a} + ${b} = ${expected}`);
258
});
259

260
// Object dataset
261
const userRoles = {
262
  admin: { role: 'admin', canDelete: true },
263
  user: { role: 'user', canDelete: false },
264
  guest: { role: 'guest', canDelete: false }
265
};
266

267
QUnit.test.each("user permissions", userRoles, function(assert, userData) {
268
  assert.strictEqual(
269
    checkDeletePermission(userData), 
270
    userData.canDelete,
271
    `${userData.role} delete permission`
272
  );
273
});
274
```
275

276
## Conditional Tests
277

278
### Test.if()
279

280
Run tests conditionally based on runtime conditions.
281

282
```javascript { .api }
283
/**
284
 * Run test conditionally
285
 * @param {string} testName - Name of the test
286
 * @param {boolean} condition - Whether to run the test
287
 * @param {Function} callback - Test callback function
288
 */
289
QUnit.test.if(testName, condition, callback)
290
```
291

292
**Usage Example:**
293

294
```javascript
295
const hasFeatureFlag = process.env.FEATURE_X === 'enabled';
296

297
QUnit.test.if("feature X test", hasFeatureFlag, function(assert) {
298
  assert.ok(featureX(), "feature X works");
299
});
300

301
// Browser-specific tests
302
const isChrome = navigator.userAgent.includes('Chrome');
303

304
QUnit.test.if("Chrome-specific feature", isChrome, function(assert) {
305
  assert.ok(chromeSpecificAPI(), "Chrome API available");
306
});
307
```
308

309
## Combining Flavors
310

311
You can combine test flavors with parametrization:
312

313
```javascript
314
// Todo test with multiple data sets
315
QUnit.test.todo.each("unimplemented feature", testData, function(assert, data) {
316
  assert.strictEqual(unimplementedFeature(data), data.expected);
317
});
318

319
// Skip test with multiple data sets
320
QUnit.test.skip.each("temporarily disabled", testData, function(assert, data) {
321
  // These tests are skipped
322
});
323

324
// Only run specific parametrized tests
325
QUnit.test.only.each("debug specific cases", debugData, function(assert, data) {
326
  // Only these parametrized tests will run
327
});
328
```
329

330
## Best Practices
331

332
1. **Use skip temporarily**: Use `QUnit.skip()` for temporarily disabling tests, but don't commit skipped tests to version control without good reason.
333

334
2. **Use only for debugging**: `QUnit.only()` is great for focusing on specific tests during development, but remove it before committing.
335

336
3. **Document todo tests**: Always include clear comments explaining what needs to be implemented for todo tests to pass.
337

338
4. **Organize with modules**: Group related tests using modules, and use module flavors to control entire feature sets.
339

340
5. **Parametrize similar tests**: Use `test.each()` when you have the same test logic but different input data.
341

342
6. **Conditional tests for environments**: Use `test.if()` for environment-specific or feature-flag controlled tests.