0
# HTML Fixtures
1

2
HTML fixture management system that allows loading external HTML files into test DOM with automatic cleanup, caching, and container management. Perfect for testing components that require specific DOM structure.
3

4
## Capabilities
5

6
### Global Fixture Functions
7

8
#### loadFixtures
9

10
Loads HTML fixture(s) from files and appends to DOM.
11

12
```javascript { .api }
13
/**
14
 * Loads fixture(s) from one or more files and automatically appends to DOM
15
 * Cleans up any existing fixtures first
16
 * @param fixtureUrls - One or more fixture file URLs/paths
17
 */
18
function loadFixtures(...fixtureUrls);
19
```
20

21
**Usage Examples:**
22
```javascript
23
// Load single fixture
24
loadFixtures('user-form.html');
25

26
// Load multiple fixtures  
27
loadFixtures('header.html', 'navigation.html', 'footer.html');
28

29
// Test the loaded content
30
expect($('#user-form')).toExist();
31
expect($('#submit-button')).toBeVisible();
32
```
33

34
#### appendLoadFixtures
35

36
Loads fixtures and appends to existing fixture container.
37

38
```javascript { .api }
39
/**
40
 * Loads fixture(s) and appends to existing fixture container
41
 * Does not clean up existing fixtures first
42
 * @param fixtureUrls - One or more fixture file URLs/paths
43
 */
44
function appendLoadFixtures(...fixtureUrls);
45
```
46

47
#### readFixtures
48

49
Loads fixtures from files and returns as string without DOM insertion.
50

51
```javascript { .api }
52
/**
53
 * Loads fixture(s) from files and returns combined HTML as string
54
 * Does not append to DOM - useful for processing HTML directly
55
 * @param fixtureUrls - One or more fixture file URLs/paths
56
 * @returns Combined HTML content as string
57
 */
58
function readFixtures(...fixtureUrls);
59
```
60

61
**Usage Example:**
62
```javascript
63
var htmlContent = readFixtures('template.html', 'partial.html');
64
var processedHtml = someProcessingFunction(htmlContent);
65
setFixtures(processedHtml);
66
```
67

68
#### setFixtures
69

70
Sets fixture HTML directly without loading from files.
71

72
```javascript { .api }
73
/**
74
 * Sets fixture HTML directly and appends to DOM
75
 * Cleans up any existing fixtures first
76
 * @param html - HTML string or jQuery element
77
 * @returns jQuery element representing the fixture container
78
 */
79
function setFixtures(html);
80
```
81

82
**Usage Examples:**
83
```javascript
84
// Set HTML string
85
setFixtures('<div id="test-container"><p>Test content</p></div>');
86

87
// Set jQuery element
88
var $element = $('<form><input name="email" /></form>');
89
setFixtures($element);
90

91
// Chain with jQuery operations
92
var $fixture = setFixtures('<div class="widget"></div>');
93
$fixture.find('.widget').addClass('active');
94
```
95

96
#### appendSetFixtures
97

98
Sets fixture HTML and appends to existing container.
99

100
```javascript { .api }
101
/**
102
 * Sets fixture HTML and appends to existing fixture container  
103
 * Does not clean up existing fixtures first
104
 * @param html - HTML string or jQuery element
105
 */
106
function appendSetFixtures(html);
107
```
108

109
#### preloadFixtures
110

111
Pre-loads fixtures into cache without DOM insertion.
112

113
```javascript { .api }
114
/**
115
 * Pre-loads fixture(s) from files into cache without DOM insertion
116
 * Subsequent load/read calls will use cached content
117
 * @param fixtureUrls - One or more fixture file URLs/paths
118
 */
119
function preloadFixtures(...fixtureUrls);
120
```
121

122
**Usage Example:**
123
```javascript
124
// Pre-load fixtures before test suite runs
125
beforeAll(function() {
126
  preloadFixtures('user-form.html', 'modal.html', 'table.html');
127
});
128

129
// Later loads will use cache (faster, no AJAX)
130
it('should test user form', function() {
131
  loadFixtures('user-form.html'); // Loaded from cache
132
  // ... test code
133
});
134
```
135

136
#### sandbox
137

138
Creates empty DIV element with optional attributes.
139

140
```javascript { .api }
141
/**
142
 * Creates empty DIV element with optional attributes for quick fixture creation
143
 * @param attributes - Optional object with HTML attributes to set
144
 * @returns jQuery element representing the sandbox DIV
145
 */
146
function sandbox(attributes);
147
```
148

149
**Usage Examples:**
150
```javascript
151
// Basic sandbox
152
var $sandbox = sandbox();
153
// Returns: <div id="sandbox"></div>
154

155
// Sandbox with custom attributes
156
var $custom = sandbox({
157
  id: 'my-test-area',
158
  class: 'test-container',
159
  'data-test': 'true'
160
});
161
// Returns: <div id="my-test-area" class="test-container" data-test="true"></div>
162

163
// Use with setFixtures for quick test setup
164
setFixtures(sandbox({class: 'widget-container'}));
165
$('#sandbox').append('<div class="widget">Content</div>');
166
```
167

168
### Fixture Management Class
169

170
Access fixture management through `jasmine.getFixtures()`:
171

172
```javascript { .api }
173
/**
174
 * HTML Fixture management singleton
175
 */
176
interface Fixtures {
177
  /** DOM container ID for fixtures (default: 'jasmine-fixtures') */
178
  containerId: string;
179
  
180
  /** File path for fixture files (default: 'spec/javascripts/fixtures') */
181
  fixturesPath: string;
182
  
183
  /** Internal cache object for loaded fixtures */
184
  fixturesCache_: object;
185

186
  /** Load fixtures from files and create/replace container */
187
  load(...fixtureUrls): void;
188
  
189
  /** Load fixtures and append to existing container */
190
  appendLoad(...fixtureUrls): void;
191
  
192
  /** Load fixtures from files and return as string */
193
  read(...fixtureUrls): string;
194
  
195
  /** Set HTML directly and create/replace container */
196
  set(html): jQuery;
197
  
198
  /** Set HTML directly and append to existing container */
199
  appendSet(html): void;
200
  
201
  /** Pre-load fixtures into cache */
202
  preload(...fixtureUrls): void;
203
  
204
  /** Clear fixture cache */
205
  clearCache(): void;
206
  
207
  /** Remove fixture container from DOM */
208
  cleanUp(): void;
209
  
210
  /** Create sandbox DIV element */
211
  sandbox(attributes): jQuery;
212
}
213

214
// Access the singleton
215
var fixtures = jasmine.getFixtures();
216
```
217

218
**Configuration Examples:**
219
```javascript
220
// Customize fixture path
221
jasmine.getFixtures().fixturesPath = 'test/fixtures/html';
222

223
// Customize container ID  
224
jasmine.getFixtures().containerId = 'my-test-container';
225

226
// Use fixture methods directly
227
jasmine.getFixtures().load('modal.html');
228
jasmine.getFixtures().clearCache();
229
```
230

231
### Fixture Loading Behavior
232

233
#### File Loading
234
- Fixtures loaded via synchronous AJAX requests
235
- Files loaded relative to `fixturesPath` configuration
236
- Multiple files concatenated in order specified
237
- Automatic script tag processing in HTML fixtures
238

239
#### Caching System
240
- All loaded fixtures automatically cached by filename
241
- Cache persists across multiple test runs
242
- Use `clearCache()` to purge cache if needed
243
- `preload()` populates cache without DOM insertion
244

245
#### DOM Container Management
246
- Fixtures inserted into container with ID specified by `containerId`
247
- Container automatically created if it doesn't exist
248
- Container appended to `document.body`
249
- Automatic cleanup between tests via `afterEach` hook
250

251
#### Script Processing
252
HTML fixtures can contain `<script src="">` tags that will be:
253
- Automatically loaded and executed
254
- Included in the cached fixture content
255
- Processed synchronously during fixture loading
256

257
**Example HTML Fixture with Scripts:**
258
```html
259
<!-- user-widget.html -->
260
<div id="user-widget">
261
  <h3>User Profile</h3>
262
  <div class="user-info"></div>
263
</div>
264
<script src="user-widget-behavior.js"></script>
265
```
266

267
### Error Handling
268

269
The fixture system throws errors for:
270

271
```javascript { .api }
272
/**
273
 * Specific error messages thrown by fixture system:
274
 * - "Fixture could not be loaded: [url] (status: [status], message: [message])"
275
 * - "Script could not be loaded: [url] (status: [status], message: [message])"
276
 * 
277
 * These errors occur when:
278
 * - Fixture file doesn't exist at specified path
279
 * - Network/file access issues during AJAX loading
280
 * - Script files referenced in HTML fixtures fail to load
281
 * - Invalid file paths or permission issues
282
 */
283
```
284

285
**Error Handling Example:**
286
```javascript
287
try {
288
  loadFixtures('missing-file.html');
289
} catch (error) {
290
  console.log('Fixture loading failed:', error.message);
291
}
292
```
293

294
### Configuration
295

296
#### Default Configuration
297
```javascript
298
{
299
  fixturesPath: 'spec/javascripts/fixtures',  // Default HTML fixture directory
300
  containerId: 'jasmine-fixtures'             // Default DOM container ID
301
}
302
```
303

304
#### Custom Configuration  
305
```javascript
306
// Set custom fixture path
307
jasmine.getFixtures().fixturesPath = 'test/html-fixtures';
308

309
// Set custom container ID
310
jasmine.getFixtures().containerId = 'test-workspace';
311

312
// Verify configuration
313
expect(jasmine.getFixtures().fixturesPath).toBe('test/html-fixtures');
314
```
315

316
### Integration with jasmine-ajax
317

318
When using jasmine-ajax (which overrides XMLHttpRequest), preload fixtures before jasmine-ajax loads:
319

320
```javascript
321
// Preload before jasmine-ajax interferes with AJAX
322
beforeAll(function() {
323
  preloadFixtures('form.html', 'modal.html', 'table.html');
324
});
325

326
// Later fixture loads will use cache instead of AJAX
327
it('should work with jasmine-ajax', function() {
328
  loadFixtures('form.html'); // Uses cache, not blocked by jasmine-ajax
329
  // ... test code
330
});
331
```