0
# jasmine-jquery
1

2
jasmine-jquery is a comprehensive testing library that extends the Jasmine JavaScript Testing Framework with jQuery-specific matchers and fixture loading capabilities. It provides custom matchers for testing jQuery DOM elements, an API for handling HTML, CSS, and JSON fixtures with automatic cleanup, event spying functionality, and cross-browser compatibility.
3

4
## Package Information
5

6
- **Package Name**: jasmine-jquery
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jasmine-jquery` or `bower install jasmine-jquery`
10

11
## Core Imports
12

13
Browser (script tag):
14
```html
15
<script src="path/to/jasmine-jquery.js"></script>
16
<!-- All functionality available globally -->
17
```
18

19
CommonJS/Node.js:
20
```javascript
21
require('jasmine-jquery');
22
// Extends jasmine global object and window
23
```
24

25
## Basic Usage
26

27
```javascript
28
// HTML fixtures
29
loadFixtures('user-form.html');
30
$('#submit-button').click();
31
expect($('#error-message')).toBeVisible();
32

33
// jQuery matchers  
34
expect($('#my-element')).toHaveClass('active');
35
expect($('input[name="email"]')).toHaveValue('test@example.com');
36
expect($('.modal')).toBeHidden();
37

38
// Event spying
39
var clickSpy = spyOnEvent('#button', 'click');
40
$('#button').click();
41
expect(clickSpy).toHaveBeenTriggered();
42
```
43

44
## Architecture
45

46
jasmine-jquery operates by extending Jasmine's global objects and window:
47

48
- **Matcher Extensions**: Adds custom matchers to Jasmine's matcher registry via `jasmine.addMatchers()`
49
- **Factory Pattern**: Provides singleton factories (`jasmine.getFixtures()`, etc.) for fixture management
50
- **Global Shortcuts**: Registers convenient global functions (`loadFixtures()`, `spyOnEvent()`, etc.)
51
- **Automatic Cleanup**: Uses Jasmine's `afterEach` hooks for automatic fixture and spy cleanup
52
- **UMD Module**: Works in both browser and Node.js environments
53

54
## Capabilities
55

56
### jQuery DOM Matchers
57

58
Comprehensive set of custom matchers for testing jQuery elements, including visibility, content, attributes, CSS properties, and form states.
59

60
```javascript { .api }
61
// Element state matchers
62
expect(element).toBeVisible();
63
expect(element).toBeHidden();
64
expect(element).toBeChecked();
65
expect(element).toBeSelected();
66
expect(element).toBeDisabled();
67
expect(element).toBeFocused();
68
expect(element).toBeEmpty();
69
expect(element).toBeInDOM();
70
expect(element).toExist();
71

72
// Content and attribute matchers  
73
expect(element).toHaveClass(className);
74
expect(element).toHaveAttr(attributeName, attributeValue);
75
expect(element).toHaveProp(propertyName, propertyValue);
76
expect(element).toHaveId(id);
77
expect(element).toHaveText(text);
78
expect(element).toHaveHtml(html);
79
expect(element).toHaveValue(value);
80
expect(element).toHaveData(key, value);
81
expect(element).toHaveCss(cssProperties);
82
expect(element).toHaveLength(length);
83

84
// Containment and matching matchers
85
expect(element).toContainElement(selector);
86
expect(element).toContainText(text);  
87
expect(element).toContainHtml(html);
88
expect(element).toBeMatchedBy(selector);
89

90
// Event handling matchers
91
expect(element).toHandle(eventName);
92
expect(element).toHandleWith(eventName, eventHandler);
93
```
94

95
[jQuery Matchers](./jquery-matchers.md)
96

97
### HTML Fixtures
98

99
HTML fixture management system for loading external HTML files into test DOM with automatic cleanup and caching.
100

101
```javascript { .api }
102
// Global fixture functions
103
function loadFixtures(...fixtureUrls);
104
function appendLoadFixtures(...fixtureUrls);
105
function readFixtures(...fixtureUrls);
106
function setFixtures(html);
107
function appendSetFixtures(html);
108
function preloadFixtures(...fixtureUrls);
109
function sandbox(attributes);
110

111
// Fixture management via jasmine.getFixtures()
112
interface Fixtures {
113
  fixturesPath: string;
114
  containerId: string;  
115
  load(...fixtureUrls): void;
116
  appendLoad(...fixtureUrls): void;
117
  read(...fixtureUrls): string;
118
  set(html): void;
119
  appendSet(html): void;
120
  preload(...fixtureUrls): void;
121
  clearCache(): void;
122
  cleanUp(): void;
123
  sandbox(attributes): jQuery;
124
}
125
```
126

127
[HTML Fixtures](./html-fixtures.md)
128

129
### CSS Style Fixtures
130

131
CSS fixture management for loading external CSS files into test DOM with automatic cleanup and style isolation.
132

133
```javascript { .api }
134
// Global style fixture functions
135
function loadStyleFixtures(...fixtureUrls);  
136
function appendLoadStyleFixtures(...fixtureUrls);
137
function setStyleFixtures(css);
138
function appendSetStyleFixtures(css);
139
function preloadStyleFixtures(...fixtureUrls);
140

141
// Style fixture management via jasmine.getStyleFixtures()
142
interface StyleFixtures {
143
  fixturesPath: string;
144
  load(...fixtureUrls): void;
145
  appendLoad(...fixtureUrls): void;
146
  set(css): void;
147
  appendSet(css): void;
148
  preload(...fixtureUrls): void;
149
  clearCache(): void;
150
  cleanUp(): void;
151
}
152
```
153

154
[CSS Fixtures](./css-fixtures.md)
155

156
### JSON Fixtures
157

158
JSON fixture management for loading test data from external JSON files with automatic caching.
159

160
```javascript { .api }
161
// Global JSON fixture functions  
162
function loadJSONFixtures(...fixtureUrls);
163
function getJSONFixture(fixtureUrl);
164

165
// JSON fixture management via jasmine.getJSONFixtures()
166
interface JSONFixtures {
167
  fixturesPath: string;
168
  load(...fixtureUrls): object;
169
  read(...fixtureUrls): object;
170
  clearCache(): void;
171
}
172
```
173

174
[JSON Fixtures](./json-fixtures.md)
175

176
### Event Spying
177

178
Event spy system for testing jQuery event triggers, with support for event prevention and propagation control.
179

180
```javascript { .api }
181
// Global event spy function
182
function spyOnEvent(selector, eventName);
183

184
// Event spy object returned by spyOnEvent()
185
interface EventSpy {
186
  selector: string;
187
  eventName: string;
188
  handler: Function;
189
  reset(): void;
190
  calls: {
191
    count(): number;
192
    any(): boolean;
193
  };
194
}
195

196
// Event spy matchers
197
expect(eventName).toHaveBeenTriggeredOn(selector);
198
expect(eventSpy).toHaveBeenTriggered();
199
expect(eventName).toHaveBeenTriggeredOnAndWith(selector, expectedArgs);
200
expect(eventName).toHaveBeenPreventedOn(selector);  
201
expect(eventSpy).toHaveBeenPrevented();
202
expect(eventName).toHaveBeenStoppedOn(selector);
203
expect(eventSpy).toHaveBeenStopped();
204
```
205

206
[Event Spying](./event-spying.md)
207

208
### Factory Functions and Utilities
209

210
Core factory functions and utility methods for advanced usage and debugging.
211

212
```javascript { .api }
213
// Factory functions for fixture management
214
function jasmine.getFixtures(): Fixtures;
215
function jasmine.getStyleFixtures(): StyleFixtures;
216
function jasmine.getJSONFixtures(): JSONFixtures;
217

218
// Utility functions
219
function jasmine.jQuery.browserTagCaseIndependentHtml(html: string): string;
220
function jasmine.jQuery.elementToString(element: jQuery|HTMLElement): string;
221
function jasmine.spiedEventsKey(selector: string, eventName: string): string;
222
```
223

224
## Automatic Lifecycle Management
225

226
jasmine-jquery automatically manages test isolation through Jasmine lifecycle hooks:
227

228
```javascript { .api }
229
// Automatic beforeEach hook registers all matchers and custom equality testers
230
beforeEach(function() {
231
  jasmine.addMatchers({ /* all jQuery matchers */ });
232
  jasmine.getEnv().addCustomEqualityTester(/* jQuery element comparisons */);
233
});
234

235
// Automatic afterEach hook cleans up all fixtures and spies
236
afterEach(function() {
237
  jasmine.getFixtures().cleanUp();
238
  jasmine.getStyleFixtures().cleanUp(); 
239
  jasmine.jQuery.events.cleanUp();
240
});
241
```
242

243
## Custom Equality Testing
244

245
jasmine-jquery registers custom equality testers for seamless jQuery element comparison:
246

247
```javascript { .api }
248
// Enables direct jQuery element comparison in expectations
249
expect($('#element')).toEqual($('#element')); // Works automatically
250
expect($('<div/>')).toEqual('<div></div>'); // Cross-type comparison supported
251
```
252

253
## Factory Functions
254

255
Core factory functions for accessing fixture management singletons.
256

257
```javascript { .api }
258
// HTML fixture management singleton
259
function jasmine.getFixtures(): Fixtures;
260

261
// CSS style fixture management singleton
262
function jasmine.getStyleFixtures(): StyleFixtures;
263

264
// JSON fixture management singleton
265
function jasmine.getJSONFixtures(): JSONFixtures;
266
```
267

268
## Utility Functions
269

270
Cross-browser compatibility and debugging utilities.
271

272
```javascript { .api }
273
// Cross-browser HTML normalization
274
function jasmine.jQuery.browserTagCaseIndependentHtml(html: string): string;
275

276
// Element-to-string conversion for debugging
277
function jasmine.jQuery.elementToString(element: jQuery|HTMLElement): string;
278

279
// Event spy key generation (internal utility)  
280
function jasmine.spiedEventsKey(selector: string, eventName: string): string;
281
```
282

283
## Advanced Event System
284

285
Low-level event spy system methods for advanced usage.
286

287
```javascript { .api }
288
// Event spy data access and control
289
interface jasmine.jQuery.events {
290
  // Get arguments passed to spied event
291
  args(selector: string, eventName: string): Array;
292
  
293
  // Check if event was triggered (boolean)
294
  wasTriggered(selector: string, eventName: string): boolean;
295
  
296
  // Check if event was triggered with specific arguments
297
  wasTriggeredWith(selector: string, eventName: string, expectedArgs: any, util: object, customEqualityTesters: Array): boolean;
298
  
299
  // Check if event default was prevented
300
  wasPrevented(selector: string, eventName: string): boolean;
301
  
302
  // Check if event propagation was stopped
303
  wasStopped(selector: string, eventName: string): boolean;
304
  
305
  // Clean up all event spies (called automatically)
306
  cleanUp(): void;
307
  
308
  // Create event spy (internal method)
309
  spyOn(selector: string, eventName: string): EventSpy;
310
}
311
```
312

313
## Error Handling
314

315
jasmine-jquery provides specific error messages for common failure scenarios:
316

317
```javascript { .api }
318
// Fixture loading errors
319
// "Fixture could not be loaded: [url] (status: [status], message: [message])"
320
// "Script could not be loaded: [url] (status: [status], message: [message])"
321

322
// JSON fixture loading errors  
323
// "JSONFixture could not be loaded: [url] (status: [status], message: [message])"
324

325
// Event spy errors
326
// "There is no spy for [eventName] on [selector]. Make sure to create a spy using spyOnEvent."
327
```
328

329
## Types
330

331
```javascript { .api }
332
// Configuration interfaces
333
interface FixtureConfig {
334
  fixturesPath?: string;
335
  containerId?: string;
336
}
337

338
interface StyleFixtureConfig {
339
  fixturesPath?: string;  
340
}
341

342
interface JSONFixtureConfig {
343
  fixturesPath?: string;
344
}
345

346
// Enhanced EventSpy interface
347
interface EventSpy {
348
  selector: string;
349
  eventName: string;
350
  handler: Function;
351
  reset(): void;
352
  calls: {
353
    count(): number;
354
    any(): boolean;
355
  };
356
}
357

358
// Internal cache structure
359
interface FixtureCache {
360
  [filename: string]: string;
361
}
362

363
// jQuery utility functions
364
interface jasmine.jQuery {
365
  browserTagCaseIndependentHtml(html: string): string;
366
  elementToString(element: jQuery|HTMLElement): string;
367
  events: jasmine.jQuery.events;
368
}
369
```