0
# jQuery Matchers
1

2
Comprehensive set of custom Jasmine matchers specifically designed for testing jQuery DOM elements. These matchers provide expressive assertions for element states, content, attributes, CSS properties, and form interactions.
3

4
## Capabilities
5

6
### Element State Matchers
7

8
#### toBeVisible
9

10
Checks if element is visible on the page.
11

12
```javascript { .api }
13
/**
14
 * Checks if element is visible (has width/height > 0 and not hidden)
15
 * Elements are visible if they consume space in the document
16
 */
17
expect(element).toBeVisible();
18
```
19

20
**Usage Example:**
21
```javascript
22
expect($('#modal')).toBeVisible();
23
expect($('.notification')).not.toBeVisible();
24
```
25

26
#### toBeHidden
27

28
Checks if element is hidden from view.
29

30
```javascript { .api }
31
/**
32
 * Checks if element is hidden via CSS display:none, visibility:hidden, 
33
 * width/height of 0, or hidden form input type
34
 */
35
expect(element).toBeHidden();
36
```
37

38
#### toBeChecked
39

40
Checks if form element is checked (checkboxes, radio buttons).
41

42
```javascript { .api }
43
/**
44
 * Checks if form element has checked attribute/property
45
 * Only applies to elements that can be checked
46
 */
47
expect(element).toBeChecked();
48
```
49

50
**Usage Example:**
51
```javascript
52
expect($('input[type="checkbox"]')).toBeChecked();
53
expect($('input[name="gender"][value="male"]')).not.toBeChecked();
54
```
55

56
#### toBeSelected
57

58
Checks if option element is selected.
59

60
```javascript { .api }
61
/**
62
 * Checks if option element has selected attribute/property
63
 * Only applies to <option> elements
64
 */
65
expect(element).toBeSelected();
66
```
67

68
#### toBeDisabled
69

70
Checks if form element is disabled.
71

72
```javascript { .api }
73
/**
74
 * Checks if element has disabled attribute/property
75
 */
76
expect(element).toBeDisabled();
77
```
78

79
#### toBeFocused
80

81
Checks if element currently has focus.
82

83
```javascript { .api }
84
/**
85
 * Checks if element is the currently active/focused element
86
 */
87
expect(element).toBeFocused();
88
```
89

90
**Usage Example:**
91
```javascript
92
$('#username').focus();
93
expect($('#username')).toBeFocused();
94
```
95

96
#### toBeEmpty
97

98
Checks if element has no child elements or text content.
99

100
```javascript { .api }
101
/**
102
 * Checks if element is empty (no child DOM elements or text)
103
 */
104
expect(element).toBeEmpty();
105
```
106

107
#### toBeInDOM
108

109
Checks if element is attached to the document DOM.
110

111
```javascript { .api }
112
/**
113
 * Checks if element is present in the document DOM tree
114
 */
115
expect(element).toBeInDOM();
116
```
117

118
#### toExist
119

120
Checks if element exists (in or out of DOM).
121

122
```javascript { .api }
123
/**
124
 * Checks if jQuery selector matches any elements
125
 */
126
expect(element).toExist();
127
```
128

129
### Content and Attribute Matchers
130

131
#### toHaveClass
132

133
Checks if element has specified CSS class.
134

135
```javascript { .api }
136
/**
137
 * Checks if element has the specified CSS class
138
 * @param className - CSS class name to check for
139
 */
140
expect(element).toHaveClass(className);
141
```
142

143
**Usage Example:**
144
```javascript
145
expect($('#alert')).toHaveClass('error');
146
expect($('.button')).toHaveClass('btn-primary');
147
```
148

149
#### toHaveAttr
150

151
Checks element attribute value.
152

153
```javascript { .api }
154
/**
155
 * Checks if element has specified attribute with optional value
156
 * @param attributeName - HTML attribute name
157
 * @param attributeValue - Expected attribute value (optional)
158
 */
159
expect(element).toHaveAttr(attributeName, attributeValue);
160
```
161

162
**Usage Examples:**
163
```javascript
164
// Check attribute exists
165
expect($('input')).toHaveAttr('required');
166

167
// Check attribute value  
168
expect($('img')).toHaveAttr('src', '/images/logo.png');
169
expect($('a')).toHaveAttr('href', 'https://example.com');
170
```
171

172
#### toHaveProp
173

174
Checks element property value.
175

176
```javascript { .api }
177
/**
178
 * Checks if element has specified property with optional value
179
 * @param propertyName - DOM property name
180
 * @param propertyValue - Expected property value (optional)  
181
 */
182
expect(element).toHaveProp(propertyName, propertyValue);
183
```
184

185
**Usage Example:**
186
```javascript
187
expect($('input[type="checkbox"]')).toHaveProp('checked', true);
188
expect($('select')).toHaveProp('selectedIndex', 2);
189
```
190

191
#### toHaveId
192

193
Checks element ID attribute.
194

195
```javascript { .api }
196
/**
197
 * Checks if element has specified ID
198
 * @param id - Expected ID value
199
 */
200
expect(element).toHaveId(id);
201
```
202

203
#### toHaveText
204

205
Checks element text content.
206

207
```javascript { .api }
208
/**
209
 * Checks if element text matches expected value or regex pattern
210
 * @param text - Expected text string or RegExp pattern
211
 */
212
expect(element).toHaveText(text);
213
```
214

215
**Usage Examples:**
216
```javascript
217
expect($('#message')).toHaveText('Welcome!');
218
expect($('.error')).toHaveText(/invalid/i);
219
```
220

221
#### toHaveHtml
222

223
Checks element HTML content.
224

225
```javascript { .api }
226
/**
227
 * Checks if element innerHTML matches expected HTML
228
 * @param html - Expected HTML string
229
 */
230
expect(element).toHaveHtml(html);
231
```
232

233
#### toHaveValue
234

235
Checks form element value.
236

237
```javascript { .api }
238
/**
239
 * Checks if form element has specified value
240
 * @param value - Expected form value
241
 */
242
expect(element).toHaveValue(value);
243
```
244

245
**Usage Example:**
246
```javascript
247
expect($('input[name="email"]')).toHaveValue('user@example.com');
248
expect($('textarea')).toHaveValue('');
249
```
250

251
#### toHaveData
252

253
Checks element data attribute or jQuery data.
254

255
```javascript { .api }
256
/**
257
 * Checks if element has specified data attribute with optional value
258
 * @param key - Data attribute key
259
 * @param value - Expected data value (optional)
260
 */
261
expect(element).toHaveData(key, value);
262
```
263

264
**Usage Example:**
265
```javascript
266
expect($('#user')).toHaveData('id', 123);
267
expect($('.widget')).toHaveData('config');
268
```
269

270
#### toHaveCss
271

272
Checks element CSS properties.
273

274
```javascript { .api }
275
/**
276
 * Checks if element has specified CSS properties and values
277
 * @param cssProperties - Object with CSS property-value pairs
278
 */
279
expect(element).toHaveCss(cssProperties);
280
```
281

282
**Usage Examples:**
283
```javascript
284
expect($('#modal')).toHaveCss({display: 'block'});
285
expect($('.button')).toHaveCss({
286
  'background-color': 'rgb(255, 0, 0)',
287
  'font-size': '14px'
288
});
289
```
290

291
#### toHaveLength
292

293
Checks jQuery collection length.
294

295
```javascript { .api }
296
/**
297
 * Checks if jQuery collection has specified number of elements
298
 * @param length - Expected number of elements
299
 */
300
expect(element).toHaveLength(length);
301
```
302

303
**Usage Example:**
304
```javascript
305
expect($('.menu-item')).toHaveLength(5);
306
expect($('ul li')).toHaveLength(3);
307
```
308

309
### Containment and Matching Matchers
310

311
#### toContainElement
312

313
Checks if element contains child matching selector.
314

315
```javascript { .api }
316
/**
317
 * Checks if element contains descendant matching selector
318
 * @param selector - CSS selector to find within element
319
 */
320
expect(element).toContainElement(selector);
321
```
322

323
**Usage Example:**
324
```javascript
325
expect($('#form')).toContainElement('input[type="submit"]');
326
expect($('.modal')).toContainElement('.close-button');
327
```
328

329
#### toContainText
330

331
Checks if element contains specified text.
332

333
```javascript { .api }
334
/**
335
 * Checks if element text content contains specified string or matches regex
336
 * @param text - Text string or RegExp pattern to find
337
 */
338
expect(element).toContainText(text);
339
```
340

341
#### toContainHtml
342

343
Checks if element contains specified HTML.
344

345
```javascript { .api }
346
/**
347
 * Checks if element HTML content contains specified HTML string
348
 * @param html - HTML string to find within element
349
 */
350
expect(element).toContainHtml(html);
351
```
352

353
#### toBeMatchedBy
354

355
Checks if element matches selector.
356

357
```javascript { .api }
358
/**
359
 * Checks if element matches the given CSS selector
360
 * @param selector - CSS selector to match against
361
 */
362
expect(element).toBeMatchedBy(selector);
363
```
364

365
**Usage Example:**
366
```javascript
367
expect($('.button.primary')).toBeMatchedBy('.button');
368
expect($('#nav ul li')).toBeMatchedBy('li');
369
```
370

371
### Event Handling Matchers
372

373
#### toHandle
374

375
Checks if element has event handler for specified event.
376

377
```javascript { .api }
378
/**
379
 * Checks if element has registered event handler for event type
380
 * @param eventName - Event name (can include namespaces like 'click.myapp')
381
 */
382
expect(element).toHandle(eventName);
383
```
384

385
**Usage Examples:**
386
```javascript
387
expect($('#button')).toHandle('click');
388
expect($('#form')).toHandle('submit.validation');
389
```
390

391
#### toHandleWith
392

393
Checks if element has specific event handler function.
394

395
```javascript { .api }
396
/**
397
 * Checks if element has the exact event handler function registered
398
 * @param eventName - Event name
399
 * @param eventHandler - Specific handler function to check for
400
 */
401
expect(element).toHandleWith(eventName, eventHandler);
402
```
403

404
**Usage Example:**
405
```javascript
406
function myClickHandler() { /* ... */ }
407
$('#button').on('click', myClickHandler);
408
expect($('#button')).toHandleWith('click', myClickHandler);
409
```
410

411
## jQuery Utility Functions
412

413
jasmine-jquery provides utility functions for cross-browser HTML processing:
414

415
#### jasmine.jQuery.browserTagCaseIndependentHtml
416

417
Normalizes HTML for cross-browser compatibility.
418

419
```javascript { .api }
420
/**
421
 * Normalizes HTML tag case for cross-browser comparison
422
 * Helps ensure consistent HTML comparisons across different browsers
423
 * @param html - HTML string to normalize
424
 * @returns Normalized HTML string
425
 */
426
function jasmine.jQuery.browserTagCaseIndependentHtml(html);
427
```
428

429
**Usage Example:**
430
```javascript
431
var normalizedHtml = jasmine.jQuery.browserTagCaseIndependentHtml('<DIV>content</DIV>');
432
// Returns: '<div>content</div>' (lowercase tags)
433
```
434

435
#### jasmine.jQuery.elementToString
436

437
Converts jQuery elements to string representation.
438

439
```javascript { .api }
440
/**
441
 * Converts jQuery element(s) to string representation using outerHTML
442
 * Useful for debugging and custom matcher implementations  
443
 * @param element - jQuery element or collection
444
 * @returns String representation of element(s)
445
 */
446
function jasmine.jQuery.elementToString(element);
447
```
448

449
**Usage Example:**
450
```javascript
451
var elementString = jasmine.jQuery.elementToString($('<div class="test">Hello</div>'));
452
// Returns: '<div class="test">Hello</div>'
453

454
var multipleElements = jasmine.jQuery.elementToString($('<span>A</span><span>B</span>'));
455
// Returns: '<span>A</span>, <span>B</span>'
456
```
457

458
## Negation Support
459

460
All matchers support negation using `.not`:
461

462
```javascript
463
expect($('#hidden-element')).not.toBeVisible();
464
expect($('input')).not.toHaveClass('error');  
465
expect($('.empty-list')).not.toContainElement('li');
466
```