0
# Test Organization
1

2
Core functions for defining test suites, individual tests, and setup/teardown hooks. Provides the fundamental structure for organizing and executing tests in Jasmine.
3

4
## Capabilities
5

6
### Suite Definition
7

8
Functions for creating test suites that group related specifications.
9

10
```javascript { .api }
11
/**
12
 * Create a group/suite of specs
13
 * @param description - Descriptive name for the suite
14
 * @param specDefinitions - Function containing the specs and setup
15
 * @returns Suite object
16
 */
17
function describe(description: string, specDefinitions: () => void): Suite;
18

19
/**
20
 * Temporarily disable a suite (will be marked as pending)
21
 * @param description - Descriptive name for the suite
22
 * @param specDefinitions - Function containing the specs and setup
23
 * @returns Suite object
24
 */
25
function xdescribe(description: string, specDefinitions: () => void): Suite;
26

27
/**
28
 * Focus on this suite (only focused suites and specs will run)
29
 * @param description - Descriptive name for the suite
30
 * @param specDefinitions - Function containing the specs and setup
31
 * @returns Suite object
32
 */
33
function fdescribe(description: string, specDefinitions: () => void): Suite;
34
```
35

36
**Usage Examples:**
37

38
```javascript
39
describe('User Authentication', () => {
40
  describe('when user is logged in', () => {
41
    it('should show dashboard', () => {
42
      // test implementation
43
    });
44
  });
45

46
  describe('when user is not logged in', () => {
47
    it('should redirect to login page', () => {
48
      // test implementation
49
    });
50
  });
51
});
52

53
// Temporarily skip a suite
54
xdescribe('Feature in development', () => {
55
  it('will not run', () => {
56
    // this won't execute
57
  });
58
});
59

60
// Focus on specific suite during development
61
fdescribe('Current feature being tested', () => {
62
  it('only this suite will run', () => {
63
    // only focused suites/specs execute
64
  });
65
});
66
```
67

68
### Spec Definition
69

70
Functions for defining individual test specifications.
71

72
```javascript { .api }
73
/**
74
 * Define a single test/specification
75
 * @param description - Descriptive name for the test
76
 * @param testFunction - Optional function containing test logic
77
 * @param timeout - Optional timeout in milliseconds
78
 * @returns Spec object
79
 */
80
function it(description: string, testFunction?: () => void | Promise<void>, timeout?: number): Spec;
81

82
/**
83
 * Temporarily disable a spec (will be marked as pending)
84
 * @param description - Descriptive name for the test
85
 * @param testFunction - Optional function containing test logic
86
 * @returns Spec object
87
 */
88
function xit(description: string, testFunction?: () => void | Promise<void>): Spec;
89

90
/**
91
 * Focus on this spec (only focused suites and specs will run)
92
 * @param description - Descriptive name for the test
93
 * @param testFunction - Optional function containing test logic
94
 * @param timeout - Optional timeout in milliseconds
95
 * @returns Spec object
96
 */
97
function fit(description: string, testFunction?: () => void | Promise<void>, timeout?: number): Spec;
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
describe('Calculator', () => {
104
  it('should add two numbers', () => {
105
    const result = add(2, 3);
106
    expect(result).toEqual(5);
107
  });
108

109
  // Asynchronous test
110
  it('should fetch user data', async () => {
111
    const user = await fetchUser(123);
112
    expect(user.name).toBe('John');
113
  });
114

115
  // Test with custom timeout
116
  it('should handle slow operations', () => {
117
    // test logic
118
  }, 10000); // 10 second timeout
119

120
  // Pending test (no implementation yet)
121
  it('should handle edge case');
122

123
  // Temporarily disabled test
124
  xit('should work with legacy API', () => {
125
    // this won't run
126
  });
127

128
  // Focused test for development
129
  fit('should validate new feature', () => {
130
    // only this test will run
131
  });
132
});
133
```
134

135
### Setup and Teardown Hooks
136

137
Functions for running setup and cleanup code before and after tests.
138

139
```javascript { .api }
140
/**
141
 * Run before each spec in the describe block
142
 * @param action - Function to execute before each spec
143
 * @param timeout - Optional timeout in milliseconds
144
 */
145
function beforeEach(action: () => void | Promise<void>, timeout?: number): void;
146

147
/**
148
 * Run after each spec in the describe block
149
 * @param action - Function to execute after each spec
150
 * @param timeout - Optional timeout in milliseconds
151
 */
152
function afterEach(action: () => void | Promise<void>, timeout?: number): void;
153

154
/**
155
 * Run once before all specs in the describe block
156
 * @param action - Function to execute before all specs
157
 * @param timeout - Optional timeout in milliseconds
158
 */
159
function beforeAll(action: () => void | Promise<void>, timeout?: number): void;
160

161
/**
162
 * Run once after all specs in the describe block
163
 * @param action - Function to execute after all specs
164
 * @param timeout - Optional timeout in milliseconds
165
 */
166
function afterAll(action: () => void | Promise<void>, timeout?: number): void;
167
```
168

169
**Usage Examples:**
170

171
```javascript
172
describe('Database operations', () => {
173
  let database;
174

175
  beforeAll(async () => {
176
    // Setup shared resources once
177
    database = await connectToDatabase();
178
  });
179

180
  afterAll(async () => {
181
    // Cleanup shared resources
182
    await database.close();
183
  });
184

185
  beforeEach(() => {
186
    // Reset state before each test
187
    database.clearCache();
188
  });
189

190
  afterEach(() => {
191
    // Cleanup after each test
192
    database.rollbackTransaction();
193
  });
194

195
  it('should save user', async () => {
196
    const user = await database.save({ name: 'Alice' });
197
    expect(user.id).toBeDefined();
198
  });
199

200
  it('should find user', async () => {
201
    await database.save({ name: 'Bob' });
202
    const user = await database.findByName('Bob');
203
    expect(user).toBeDefined();
204
  });
205
});
206
```
207

208
### Spec Control Functions
209

210
Functions for controlling spec execution and marking specs as pending or failed.
211

212
```javascript { .api }
213
/**
214
 * Mark the current spec as pending with an optional message
215
 * @param message - Optional reason for pending status
216
 */
217
function pending(message?: string): void;
218

219
/**
220
 * Explicitly fail the current spec with an error message
221
 * @param error - Error message or Error object
222
 */
223
function fail(error?: string | Error): void;
224
```
225

226
**Usage Examples:**
227

228
```javascript
229
describe('Feature tests', () => {
230
  it('should implement complex feature', () => {
231
    if (!featureImplemented) {
232
      pending('Feature not yet implemented');
233
      return;
234
    }
235
    
236
    // test implementation
237
  });
238

239
  it('should validate input', () => {
240
    const input = getInput();
241
    
242
    if (!input) {
243
      fail('No input provided for test');
244
    }
245
    
246
    expect(validateInput(input)).toBe(true);
247
  });
248
});
249
```
250

251
### Spec and Suite Properties
252

253
Functions for adding custom properties to test results.
254

255
```javascript { .api }
256
/**
257
 * Set a user-defined property on the current spec result
258
 * @param key - Property name
259
 * @param value - Property value
260
 */
261
function setSpecProperty(key: string, value: any): void;
262

263
/**
264
 * Set a user-defined property on the current suite result
265
 * @param key - Property name
266
 * @param value - Property value
267
 */
268
function setSuiteProperty(key: string, value: any): void;
269
```
270

271
**Usage Examples:**
272

273
```javascript
274
describe('Performance tests', () => {
275
  it('should complete within time limit', () => {
276
    const startTime = Date.now();
277
    
278
    performOperation();
279
    
280
    const duration = Date.now() - startTime;
281
    setSpecProperty('executionTime', duration);
282
    setSpecProperty('category', 'performance');
283
    
284
    expect(duration).toBeLessThan(1000);
285
  });
286
});
287

288
describe('API tests', () => {
289
  beforeAll(() => {
290
    setSuiteProperty('testEnvironment', 'staging');
291
    setSuiteProperty('apiVersion', '2.1');
292
  });
293

294
  it('should return user data', () => {
295
    // test implementation
296
  });
297
});
298
```
299

300
## Types
301

302
```javascript { .api }
303
interface Suite {
304
  id: number;
305
  description: string;
306
  fullName: string;
307
  parentSuite?: Suite;
308
  children: (Suite | Spec)[];
309
  status?: 'disabled' | 'pending' | 'finished';
310
}
311

312
interface Spec {
313
  id: number;
314
  description: string;
315
  fullName: string;
316
  suite: Suite;
317
  result: SpecResult;
318
  status?: 'disabled' | 'pending' | 'started' | 'finished';
319
}
320

321
interface SpecResult {
322
  id: number;
323
  description: string;
324
  fullName: string;
325
  status: 'passed' | 'failed' | 'pending';
326
  pendingReason?: string;
327
  failedExpectations: ExpectationResult[];
328
  passedExpectations: ExpectationResult[];
329
  deprecationWarnings: ExpectationResult[];
330
  properties?: { [key: string]: any };
331
}
332
```