0
# CSS Fixtures
1

2
CSS fixture management system for loading external CSS files into test DOM with automatic cleanup and style isolation. Essential for testing components that depend on specific CSS styles and layout behavior.
3

4
## Capabilities
5

6
### Global Style Fixture Functions
7

8
#### loadStyleFixtures
9

10
Loads CSS fixture(s) from files and applies to DOM.
11

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

21
**Usage Examples:**
22
```javascript
23
// Load single CSS fixture
24
loadStyleFixtures('widget-styles.css');
25

26
// Load multiple CSS fixtures
27
loadStyleFixtures('base.css', 'layout.css', 'theme.css');
28

29
// Test CSS-dependent behavior
30
expect($('#widget')).toHaveCss({position: 'absolute'});
31
expect($('.button')).toHaveCss({display: 'inline-block'});
32
```
33

34
#### appendLoadStyleFixtures
35

36
Loads CSS fixtures and appends to existing styles.
37

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

47
**Usage Example:**
48
```javascript
49
// Load base styles first
50
loadStyleFixtures('base.css');
51

52
// Add additional styles without removing base
53
appendLoadStyleFixtures('theme.css', 'responsive.css');
54
```
55

56
#### setStyleFixtures
57

58
Sets CSS directly without loading from files.
59

60
```javascript { .api }
61
/**
62
 * Sets CSS content directly and applies to DOM
63
 * Removes any existing style fixtures first
64
 * @param css - CSS string content
65
 */
66
function setStyleFixtures(css);
67
```
68

69
**Usage Examples:**
70
```javascript
71
// Set CSS string directly
72
setStyleFixtures(`
73
  .test-element { 
74
    position: absolute; 
75
    left: 300px; 
76
    top: 100px; 
77
  }
78
  .hidden { display: none; }
79
`);
80

81
// Test CSS-dependent positioning
82
loadFixtures('<div class="test-element">Test</div>');
83
expect($('.test-element')).toHaveCss({left: '300px'});
84
```
85

86
#### appendSetStyleFixtures
87

88
Sets CSS directly and appends to existing styles.
89

90
```javascript { .api }
91
/**
92
 * Sets CSS content directly and appends to existing style fixtures
93
 * Does not remove existing style fixtures first
94
 * @param css - CSS string content
95
 */
96
function appendSetStyleFixtures(css);
97
```
98

99
#### preloadStyleFixtures  
100

101
Pre-loads CSS fixtures into cache without applying to DOM.
102

103
```javascript { .api }
104
/**
105
 * Pre-loads CSS fixture(s) from files into cache without applying to DOM
106
 * Subsequent load calls will use cached content
107
 * @param fixtureUrls - One or more CSS fixture file URLs/paths
108
 */
109
function preloadStyleFixtures(...fixtureUrls);
110
```
111

112
**Usage Example:**
113
```javascript
114
// Pre-load CSS fixtures before test suite runs
115
beforeAll(function() {
116
  preloadStyleFixtures('layout.css', 'components.css');
117
});
118

119
// Later loads will use cache (faster, no AJAX)
120
it('should test styled components', function() {
121
  loadStyleFixtures('layout.css'); // Loaded from cache
122
  // ... test code
123
});
124
```
125

126
### Style Fixture Management Class
127

128
Access style fixture management through `jasmine.getStyleFixtures()`:
129

130
```javascript { .api }
131
/**
132
 * CSS Style Fixture management singleton
133
 */
134
interface StyleFixtures {
135
  /** File path for CSS fixture files (default: 'spec/javascripts/fixtures') */
136
  fixturesPath: string;
137
  
138
  /** Internal cache object for loaded CSS fixtures */
139
  fixturesCache_: object;
140
  
141
  /** Array of style DOM nodes added to document head */
142
  fixturesNodes_: HTMLStyleElement[];
143

144
  /** Load CSS fixtures from files and apply to DOM */
145
  load(...fixtureUrls): void;
146
  
147
  /** Load CSS fixtures and append to existing styles */
148
  appendLoad(...fixtureUrls): void;
149
  
150
  /** Set CSS directly and apply to DOM */
151
  set(css): void;
152
  
153
  /** Set CSS directly and append to existing styles */
154
  appendSet(css): void;
155
  
156
  /** Pre-load CSS fixtures into cache */
157
  preload(...fixtureUrls): void;
158
  
159
  /** Clear CSS fixture cache */
160
  clearCache(): void;
161
  
162
  /** Remove all style fixture nodes from DOM */
163
  cleanUp(): void;
164
}
165

166
// Access the singleton
167
var styleFixtures = jasmine.getStyleFixtures();
168
```
169

170
**Configuration Example:**
171
```javascript
172
// Customize CSS fixture path
173
jasmine.getStyleFixtures().fixturesPath = 'test/fixtures/styles';
174

175
// Use style fixture methods directly
176
jasmine.getStyleFixtures().load('widget.css');
177
jasmine.getStyleFixtures().clearCache();
178
```
179

180
### CSS Loading Behavior
181

182
#### File Loading
183
- CSS files loaded via synchronous AJAX requests
184
- Files loaded relative to `fixturesPath` configuration
185
- Multiple files processed in order specified
186
- CSS content extracted from HTML wrapper if needed
187

188
#### Style Application
189
- CSS content wrapped in `<style>` elements
190
- Style elements appended to document `<head>`
191
- Styles immediately available for testing
192
- Multiple style fixtures create separate `<style>` elements
193

194
#### Caching System
195
- All loaded CSS fixtures automatically cached by filename
196
- Cache persists across multiple test runs
197
- Use `clearCache()` to purge cache if needed
198
- `preload()` populates cache without DOM application
199

200
#### DOM Style Management
201
- Style elements tracked in `fixturesNodes_` array
202
- Automatic cleanup between tests via `afterEach` hook
203
- All fixture styles removed when `cleanUp()` called
204
- Styles isolated to test environment
205

206
### Why CSS Fixtures Are Needed
207

208
CSS fixtures solve browser-specific testing issues:
209

210
**Problem Example:**
211
```javascript
212
// Without CSS fixtures - unreliable across browsers
213
$('#element').css('left', '300px');
214
expect($('#element').css('left')).toBe('300px'); // May return 'auto' in some browsers
215
```
216

217
**Solution with CSS Fixtures:**
218
```javascript
219
// CSS fixture: element-positioning.css
220
// .positioned { position: absolute; }
221

222
// Test with CSS fixture
223
loadStyleFixtures('element-positioning.css');
224
loadFixtures('<div id="element" class="positioned"></div>');
225
$('#element').css('left', '300px');
226
expect($('#element').css('left')).toBe('300px'); // Reliable across browsers
227
```
228

229
### Common Use Cases
230

231
#### Testing CSS-Dependent Layout
232
```javascript
233
setStyleFixtures(`
234
  .grid { display: grid; grid-template-columns: 1fr 1fr; }
235
  .grid-item { padding: 10px; }
236
`);
237

238
setFixtures(`
239
  <div class="grid">
240
    <div class="grid-item">Item 1</div>
241
    <div class="grid-item">Item 2</div>
242
  </div>
243
`);
244

245
// Test grid layout behavior
246
expect($('.grid')).toHaveCss({display: 'grid'});
247
expect($('.grid-item')).toHaveLength(2);
248
```
249

250
#### Testing Responsive Behavior
251
```javascript
252
loadStyleFixtures('responsive.css');
253
setFixtures('<div class="responsive-widget">Widget</div>');
254

255
// Test responsive breakpoints
256
// (May require viewport manipulation in tests)
257
expect($('.responsive-widget')).toHaveCss({display: 'block'});
258
```
259

260
#### Testing Animation States
261
```javascript
262
setStyleFixtures(`
263
  .animated { transition: opacity 0.3s ease; }
264
  .fade-out { opacity: 0; }
265
  .fade-in { opacity: 1; }
266
`);
267

268
setFixtures('<div class="animated fade-in">Content</div>');
269
expect($('.animated')).toHaveCss({opacity: '1'});
270

271
$('.animated').removeClass('fade-in').addClass('fade-out');
272
expect($('.animated')).toHaveCss({opacity: '0'});
273
```
274

275
### Error Handling
276

277
The CSS fixture system throws errors for:
278

279
```javascript { .api }
280
/**
281
 * Specific error messages thrown by CSS fixture system:
282
 * - "Fixture could not be loaded: [url] (status: [status], message: [message])"
283
 * 
284
 * These errors occur when:
285
 * - CSS fixture file doesn't exist at specified path
286
 * - Network/file access issues during AJAX loading  
287
 * - Invalid file paths or permission issues
288
 * - CSS files are corrupted or inaccessible
289
 */
290
```
291

292
### Configuration
293

294
#### Default Configuration
295
```javascript
296
{
297
  fixturesPath: 'spec/javascripts/fixtures'  // Default CSS fixture directory (same as HTML fixtures)
298
}
299
```
300

301
#### Custom Configuration
302
```javascript
303
// Set custom CSS fixture path
304
jasmine.getStyleFixtures().fixturesPath = 'test/css-fixtures';
305

306
// Verify configuration
307
expect(jasmine.getStyleFixtures().fixturesPath).toBe('test/css-fixtures');
308
```
309

310
### Integration Patterns
311

312
#### Combined with HTML Fixtures
313
```javascript
314
// Load both HTML and CSS fixtures together
315
loadFixtures('modal.html');
316
loadStyleFixtures('modal.css');
317

318
// Test styled HTML behavior
319
expect($('#modal')).toBeVisible();
320
expect($('#modal')).toHaveCss({position: 'fixed'});
321
```
322

323
#### Testing CSS Framework Integration
324
```javascript
325
// Load framework CSS for testing
326
loadStyleFixtures('bootstrap.css', 'custom-overrides.css');
327
setFixtures('<button class="btn btn-primary">Click me</button>');
328

329
expect($('.btn')).toHaveCss({display: 'inline-block'});
330
expect($('.btn-primary')).toHaveCss({backgroundColor: 'rgb(0, 123, 255)'});
331
```
332

333
#### Cross-Browser CSS Testing
334
```javascript
335
describe('Cross-browser CSS behavior', function() {
336
  beforeEach(function() {
337
    loadStyleFixtures('cross-browser-fixes.css');
338
  });
339

340
  it('should position elements consistently', function() {
341
    setFixtures('<div class="positioned-element">Test</div>');
342
    $('.positioned-element').css('left', '100px');
343
    
344
    // Reliable across IE, Firefox, Chrome, Safari
345
    expect($('.positioned-element')).toHaveCss({left: '100px'});
346
  });
347
});
348
```