0
# jsdom
1
2
jsdom is a pure-JavaScript implementation of many web standards, notably the WHATWG DOM and HTML Standards, for use with Node.js. It provides a complete browser-like environment for testing and scraping web applications without requiring an actual browser.
3
4
## Quick Start
5
6
> **Best Practice:** Always wrap jsdom usage in try-finally to ensure cleanup, even on errors.
7
8
### Parse HTML and Extract Data
9
10
```javascript
11
const { JSDOM } = require("jsdom");
12
13
const html = '<div class="item"><h2>Title</h2><p>Description</p></div>';
14
const dom = new JSDOM(html);
15
16
try {
17
const { document } = dom.window;
18
19
const title = document.querySelector("h2")?.textContent || "";
20
const description = document.querySelector("p")?.textContent || "";
21
22
console.log({ title, description }); // { title: 'Title', description: 'Description' }
23
} finally {
24
dom.window.close(); // Always cleanup
25
}
26
```
27
28
### Setup for Testing
29
30
```javascript
31
const { JSDOM } = require("jsdom");
32
33
function setupDOM(html) {
34
const dom = new JSDOM(html || '<!DOCTYPE html><body></body>', {
35
url: "https://example.org/",
36
referrer: "https://google.com/",
37
includeNodeLocations: true
38
});
39
global.window = dom.window;
40
global.document = dom.window.document;
41
global.navigator = dom.window.navigator;
42
return dom;
43
}
44
45
function teardownDOM(dom) {
46
if (dom && dom.window) dom.window.close();
47
delete global.window;
48
delete global.document;
49
delete global.navigator;
50
}
51
52
const dom = setupDOM('<div id="test">Hello</div>');
53
try {
54
const element = document.getElementById("test");
55
console.log(element.textContent); // "Hello"
56
} finally {
57
teardownDOM(dom);
58
}
59
```
60
61
### Scrape a Web Page (with retry)
62
63
```javascript
64
const { JSDOM } = require("jsdom");
65
66
async function scrapePage(url, maxRetries = 3) {
67
let lastError;
68
69
for (let attempt = 1; attempt <= maxRetries; attempt++) {
70
let dom = null;
71
try {
72
dom = await JSDOM.fromURL(url, {
73
url, // Important: set URL for resource loading
74
resources: "usable",
75
runScripts: "dangerously",
76
pretendToBeVisual: true
77
});
78
79
const { document } = dom.window;
80
const result = {
81
title: document.title,
82
links: Array.from(document.querySelectorAll("a[href]")).map(a => a.href),
83
html: dom.serialize()
84
};
85
86
dom.window.close(); // Cleanup on success
87
return result;
88
} catch (error) {
89
lastError = error;
90
if (dom) dom.window.close(); // Cleanup on error
91
92
if (attempt < maxRetries) {
93
await new Promise(r => setTimeout(r, 1000 * attempt));
94
}
95
}
96
}
97
98
throw new Error(`Failed to scrape ${url} after ${maxRetries} attempts: ${lastError?.message}`);
99
}
100
101
scrapePage("https://example.com")
102
.then(data => console.log(data))
103
.catch(error => console.error(error));
104
```
105
106
## Quick Reference
107
108
| Task | Code |
109
|------|------|
110
| Create DOM | `const dom = new JSDOM('<p>Hello</p>');` |
111
| Access document | `const { document } = dom.window;` |
112
| Parse fragment | `const frag = JSDOM.fragment('<li>Item</li>');` |
113
| Load from URL | `const dom = await JSDOM.fromURL(url);` |
114
| Load from file | `const dom = await JSDOM.fromFile('page.html');` |
115
| Serialize | `dom.serialize()` |
116
| Cleanup | `dom.window.close();` |
117
118
## Decision Tree: Which Option to Use?
119
120
```
121
Need to parse HTML?
122
├─ Simple extraction? → JSDOM.fragment() (fastest)
123
├─ Need full document? → new JSDOM(html)
124
└─ Need external resources? → new JSDOM(html, { resources: "usable" })
125
126
Need to execute scripts?
127
├─ Trusted content? → { runScripts: "dangerously" }
128
└─ Untrusted content? → { runScripts: "outside-only" }
129
130
Need to test code?
131
├─ Setup before each test → setupDOM()
132
├─ Global access needed → global.window = dom.window
133
└─ Always cleanup → dom.window.close() in finally
134
135
Need to scrape?
136
├─ Single page → JSDOM.fromURL()
137
├─ Multiple pages → Shared CookieJar
138
└─ Need resilience → Retry logic with cleanup
139
```
140
141
## Common Patterns
142
143
### Execute Scripts Safely
144
145
```javascript
146
const dom = new JSDOM(`<!DOCTYPE html><body></body>`, {
147
url: "https://example.org/",
148
runScripts: "outside-only"
149
});
150
151
try {
152
dom.window.eval(`document.body.innerHTML = '<p>Added</p>';`);
153
console.log(dom.window.document.body.innerHTML);
154
} catch (error) {
155
console.error("Script execution failed:", error);
156
} finally {
157
dom.window.close();
158
}
159
```
160
161
### Capture Console Output
162
163
```javascript
164
const { JSDOM, VirtualConsole } = require("jsdom");
165
166
const virtualConsole = new VirtualConsole();
167
virtualConsole.on("log", (msg) => console.log("Page:", msg));
168
virtualConsole.on("error", (msg) => console.error("Page error:", msg));
169
virtualConsole.on("jsdomError", (err) => console.error("jsdom error:", err.message));
170
171
const dom = new JSDOM(`<script>console.log("Hello");</script>`, {
172
runScripts: "dangerously",
173
virtualConsole
174
});
175
```
176
177
### Manage Cookies
178
179
```javascript
180
const { JSDOM, CookieJar } = require("jsdom");
181
182
const cookieJar = new CookieJar();
183
184
const dom1 = new JSDOM(``, { url: "https://example.com/", cookieJar });
185
dom1.window.document.cookie = "session=abc123; path=/";
186
187
const dom2 = new JSDOM(``, { url: "https://example.com/", cookieJar });
188
console.log(dom2.window.document.cookie); // "session=abc123"
189
```
190
191
### Integration: Jest Testing
192
193
```javascript
194
const { JSDOM } = require("jsdom");
195
196
let dom;
197
198
beforeEach(() => {
199
dom = new JSDOM(`<!DOCTYPE html><body id="root"></body>`, {
200
url: "https://example.org/",
201
includeNodeLocations: true
202
});
203
204
global.window = dom.window;
205
global.document = dom.window.document;
206
global.navigator = dom.window.navigator;
207
});
208
209
afterEach(() => {
210
if (dom) dom.window.close();
211
delete global.window;
212
delete global.document;
213
delete global.navigator;
214
});
215
216
test("should manipulate DOM", () => {
217
const root = document.getElementById("root");
218
root.innerHTML = "<p>Test</p>";
219
220
expect(root.querySelector("p").textContent).toBe("Test");
221
});
222
```
223
224
### Integration: Mocha/Chai
225
226
```javascript
227
const { JSDOM } = require("jsdom");
228
const { expect } = require("chai");
229
230
describe("DOM Operations", () => {
231
let dom;
232
233
beforeEach(() => {
234
dom = new JSDOM(`<div id="app"></div>`, {
235
url: "https://example.org/"
236
});
237
global.window = dom.window;
238
global.document = dom.window.document;
239
});
240
241
afterEach(() => {
242
if (dom) dom.window.close();
243
delete global.window;
244
delete global.document;
245
});
246
247
it("should find elements", () => {
248
const app = document.getElementById("app");
249
expect(app).to.not.be.null;
250
});
251
});
252
```
253
254
### Integration: Vitest
255
256
```javascript
257
import { describe, it, expect, beforeEach, afterEach } from "vitest";
258
import { JSDOM } from "jsdom";
259
260
describe("jsdom integration", () => {
261
let dom;
262
263
beforeEach(() => {
264
dom = new JSDOM(`<!DOCTYPE html><body><h1>Test</h1></body>`, {
265
url: "https://example.org/"
266
});
267
global.window = dom.window;
268
global.document = dom.window.document;
269
});
270
271
afterEach(() => {
272
dom?.window.close();
273
delete global.window;
274
delete global.document;
275
});
276
277
it("should parse HTML", () => {
278
const h1 = document.querySelector("h1");
279
expect(h1.textContent).toBe("Test");
280
});
281
});
282
```
283
284
## Core APIs
285
286
```javascript { .api }
287
/**
288
* Create a new jsdom instance
289
* @param input - HTML string or binary data (optional)
290
* @param options - Configuration options
291
*/
292
class JSDOM {
293
constructor(input?: string | Buffer | ArrayBuffer | TypedArray, options?: JSDOMOptions);
294
readonly window: Window;
295
readonly virtualConsole: VirtualConsole;
296
readonly cookieJar: CookieJar;
297
serialize(): string;
298
nodeLocation(node: Node): LocationInfo | undefined;
299
getInternalVMContext(): object;
300
reconfigure(settings: { windowTop?: any, url?: string }): void;
301
302
static fromURL(url: string, options?: JSDOMOptions): Promise<JSDOM>;
303
static fromFile(filename: string, options?: JSDOMOptions): Promise<JSDOM>;
304
static fragment(string?: string): DocumentFragment;
305
}
306
307
interface JSDOMOptions {
308
url?: string; // Document URL (default: "about:blank")
309
referrer?: string; // Document referrer
310
contentType?: string; // Content type (default: "text/html")
311
includeNodeLocations?: boolean; // Track source locations
312
storageQuota?: number; // localStorage quota (default: 5000000)
313
runScripts?: "dangerously" | "outside-only"; // Script execution mode
314
resources?: "usable" | ResourceLoader; // Resource loading
315
pretendToBeVisual?: boolean; // Enable animation APIs
316
virtualConsole?: VirtualConsole; // Console output handler
317
cookieJar?: CookieJar; // Cookie storage
318
beforeParse?: (window: Window) => void; // Pre-parse callback
319
}
320
```
321
322
## Best Practices
323
324
1. **Always close**: `dom.window.close()` in finally block prevents memory leaks
325
2. **Set proper URL**: Enables relative URLs and cookies
326
3. **Use `runScripts: "outside-only"`**: Safe script execution
327
4. **Handle errors**: Wrap in try-catch for production code
328
5. **Cleanup globals**: Remove test globals after tests
329
6. **Use fragments**: For simple parsing without full document overhead
330
7. **Share CookieJar**: For maintaining sessions across requests
331
8. **Set resources**: Only when needed to avoid unnecessary network requests
332
9. **Enable location tracking**: Use `includeNodeLocations: true` for debugging
333
10. **Monitor console**: Use VirtualConsole to capture and handle page errors
334
335
## Package Information
336
337
- **Package Name**: jsdom
338
- **Package Type**: npm
339
- **Language**: JavaScript (CommonJS)
340
- **Installation**: `npm install jsdom`
341
- **Node.js Requirement**: v20 or newer
342
- **Repository**: https://github.com/jsdom/jsdom
343
344
## Architecture
345
346
jsdom is built around several key components:
347
348
- **JSDOM Class**: Main interface for creating and managing DOM instances
349
- **Window Object**: Browser-like global environment with complete web APIs
350
- **Virtual Console**: Captures console output and jsdom errors for external handling
351
- **Resource Loading**: Configurable system for fetching external resources (scripts, stylesheets, images)
352
- **Cookie Management**: HTTP cookie storage and handling via CookieJar
353
- **Script Execution**: Sandboxed JavaScript execution with configurable security levels
354
- **Parser**: HTML/XML parsing using parse5 for standards-compliant document creation
355
356
## Capabilities
357
358
### JSDOM Constructor
359
360
The primary way to create jsdom instances from HTML strings or binary data.
361
362
```javascript { .api }
363
/**
364
* Create a new jsdom instance
365
* @param input - HTML string or binary data (Buffer, ArrayBuffer, TypedArray)
366
* @param options - Configuration options
367
* @returns JSDOM instance with window, document, and DOM APIs
368
*/
369
class JSDOM {
370
constructor(input?: string | Buffer | ArrayBuffer | TypedArray, options?: JSDOMOptions);
371
372
/** The Window object containing the DOM and browser APIs */
373
window: Window;
374
375
/** The VirtualConsole instance for this jsdom */
376
virtualConsole: VirtualConsole;
377
378
/** The CookieJar instance for this jsdom */
379
cookieJar: CookieJar;
380
381
/** Serialize the document to an HTML string including DOCTYPE */
382
serialize(): string;
383
384
/** Get source code location of a node (requires includeNodeLocations option) */
385
nodeLocation(node: Node): LocationInfo | undefined;
386
387
/** Get Node.js VM context for advanced script execution */
388
getInternalVMContext(): object;
389
390
/** Reconfigure the jsdom after creation */
391
reconfigure(settings: { windowTop?: any, url?: string }): void;
392
}
393
394
interface JSDOMOptions {
395
url?: string;
396
referrer?: string;
397
contentType?: string;
398
includeNodeLocations?: boolean;
399
storageQuota?: number;
400
runScripts?: "dangerously" | "outside-only";
401
resources?: "usable" | ResourceLoader;
402
pretendToBeVisual?: boolean;
403
virtualConsole?: VirtualConsole;
404
cookieJar?: CookieJar;
405
beforeParse?: (window: Window) => void;
406
}
407
```
408
409
[JSDOM Class](./jsdom-class.md)
410
411
### Configuration Options
412
413
Comprehensive options for customizing jsdom behavior including URL handling, script execution, resource loading, and rendering simulation.
414
415
```javascript { .api }
416
interface JSDOMOptions {
417
/** Document URL (default: "about:blank") */
418
url?: string;
419
/** Document referrer */
420
referrer?: string;
421
/** Content type for parsing (default: "text/html") */
422
contentType?: string;
423
/** Enable node location tracking for source mapping */
424
includeNodeLocations?: boolean;
425
/** Storage quota for localStorage/sessionStorage in code units */
426
storageQuota?: number;
427
/** Script execution mode */
428
runScripts?: "dangerously" | "outside-only";
429
/** Resource loading configuration */
430
resources?: "usable" | ResourceLoader;
431
/** Pretend to be a visual browser */
432
pretendToBeVisual?: boolean;
433
/** Virtual console for output capture */
434
virtualConsole?: VirtualConsole;
435
/** Cookie jar for cookie storage */
436
cookieJar?: CookieJar;
437
/** Callback before HTML parsing */
438
beforeParse?: (window: Window) => void;
439
}
440
```
441
442
[Configuration](./configuration.md)
443
444
### Convenience Factory Methods
445
446
Static methods on JSDOM for creating instances from URLs or files.
447
448
```javascript { .api }
449
/**
450
* Create jsdom by fetching from a URL
451
* @param url - URL to fetch (HTTP/HTTPS)
452
* @param options - Configuration options (url and contentType not allowed)
453
* @returns Promise resolving to JSDOM instance
454
*/
455
static fromURL(url: string, options?: JSDOMOptions): Promise<JSDOM>;
456
457
/**
458
* Create jsdom by reading from a file
459
* @param filename - File path relative to current working directory
460
* @param options - Configuration options
461
* @returns Promise resolving to JSDOM instance
462
*/
463
static fromFile(filename: string, options?: JSDOMOptions): Promise<JSDOM>;
464
465
/**
466
* Create a DocumentFragment from HTML (lightweight, no full document)
467
* @param string - HTML string to parse
468
* @returns DocumentFragment with parsed content
469
*/
470
static fragment(string?: string): DocumentFragment;
471
```
472
473
[JSDOM Class](./jsdom-class.md)
474
475
### Virtual Console
476
477
EventEmitter-based console for capturing output from within jsdom, including page console calls and jsdom implementation errors.
478
479
```javascript { .api }
480
/**
481
* Create a virtual console for capturing output
482
*/
483
class VirtualConsole extends EventEmitter {
484
constructor();
485
486
/**
487
* Forward console output to another console
488
* @param anyConsole - Console object to forward to
489
* @param options - Control jsdom error forwarding
490
* @returns This VirtualConsole for chaining
491
*/
492
forwardTo(
493
anyConsole: Console,
494
options?: { jsdomErrors?: "none" | string[] }
495
): VirtualConsole;
496
}
497
```
498
499
VirtualConsole emits events for all console methods: `"log"`, `"warn"`, `"error"`, `"info"`, `"debug"`, `"trace"`, `"dir"`, `"dirxml"`, `"assert"`, `"count"`, `"countReset"`, `"group"`, `"groupCollapsed"`, `"groupEnd"`, `"table"`, `"time"`, `"timeLog"`, `"timeEnd"`, `"clear"`, and special `"jsdomError"` event.
500
501
[Virtual Console](./virtual-console.md)
502
503
### Resource Loading
504
505
Configurable system for loading external resources including custom loaders and proxy support.
506
507
```javascript { .api }
508
/**
509
* Resource loader for fetching external resources
510
*/
511
class ResourceLoader {
512
constructor(options?: {
513
strictSSL?: boolean;
514
proxy?: string;
515
userAgent?: string;
516
});
517
518
/**
519
* Fetch a resource from a URL
520
* @param urlString - URL to fetch
521
* @param options - Request options
522
* @returns Promise for Buffer with abort() method
523
*/
524
fetch(
525
urlString: string,
526
options?: {
527
accept?: string;
528
cookieJar?: CookieJar;
529
referrer?: string;
530
element?: Element;
531
}
532
): Promise<Buffer> & { abort(): void };
533
}
534
```
535
536
[Resources](./resources.md)
537
538
### Cookie Management
539
540
HTTP cookie storage and handling compatible with browser cookie behavior.
541
542
```javascript { .api }
543
/**
544
* Cookie jar for HTTP cookie storage (extends tough-cookie.CookieJar)
545
*/
546
class CookieJar {
547
constructor(store?: any, options?: object);
548
549
setCookie(cookieOrString: string | Cookie, currentUrl: string, options?: object, callback?: Function): void;
550
setCookieSync(cookieOrString: string | Cookie, currentUrl: string, options?: object): Cookie;
551
getCookies(currentUrl: string, options?: object, callback?: Function): void;
552
getCookiesSync(currentUrl: string, options?: object): Cookie[];
553
}
554
```
555
556
[Resources](./resources.md)
557
558
### Window and DOM APIs
559
560
Complete browser-like environment with standard web APIs accessible via `dom.window`.
561
562
The Window object provides:
563
- **DOM APIs**: Node, Element, Document, DocumentFragment, and all HTML elements
564
- **Events**: EventTarget, Event classes, addEventListener, dispatchEvent
565
- **Selection and Traversal**: Range, Selection, NodeIterator, TreeWalker
566
- **Storage**: localStorage, sessionStorage (Web Storage API)
567
- **Timers**: setTimeout, setInterval, setImmediate, requestAnimationFrame
568
- **Network**: WebSocket, basic XMLHttpRequest, Headers
569
- **Parsing**: DOMParser, XMLSerializer
570
- **Files**: Blob, File, FileReader, FileList
571
- **Custom Elements**: customElements, CustomElementRegistry
572
- **Navigation**: location, history (limited)
573
- **Console**: console object (connected to VirtualConsole)
574
- **And many more standard web platform APIs**
575
576
[DOM APIs](./dom-apis.md)
577
578
## Common Usage Patterns
579
580
### Creating a simple DOM
581
582
```javascript
583
const { JSDOM } = require("jsdom");
584
585
const dom = new JSDOM(`<!DOCTYPE html><body><div id="app"></div></body>`);
586
const { document } = dom.window;
587
588
const app = document.getElementById("app");
589
app.innerHTML = "<h1>Hello from jsdom!</h1>";
590
```
591
592
### Testing DOM-dependent code
593
594
```javascript
595
const { JSDOM } = require("jsdom");
596
597
// Create a DOM environment
598
const dom = new JSDOM(`<!DOCTYPE html><body></body>`, {
599
url: "https://example.org/",
600
runScripts: "dangerously"
601
});
602
603
// Make window available globally for tests
604
global.window = dom.window;
605
global.document = dom.window.document;
606
global.navigator = dom.window.navigator;
607
608
// Now DOM-dependent code can run in tests
609
```
610
611
### Executing scripts safely
612
613
```javascript
614
const { JSDOM } = require("jsdom");
615
616
const dom = new JSDOM(`<!DOCTYPE html><body></body>`, {
617
runScripts: "outside-only"
618
});
619
620
// Execute code in the jsdom context
621
dom.window.eval(`
622
document.body.innerHTML = '<p>Added from script</p>';
623
`);
624
625
console.log(dom.window.document.body.innerHTML); // '<p>Added from script</p>'
626
```
627
628
### Loading a page from a URL
629
630
```javascript
631
const { JSDOM } = require("jsdom");
632
633
JSDOM.fromURL("https://example.com/", {
634
resources: "usable",
635
runScripts: "dangerously"
636
}).then(dom => {
637
console.log(dom.serialize());
638
});
639
```
640
641
### Capturing console output
642
643
```javascript
644
const { JSDOM, VirtualConsole } = require("jsdom");
645
646
const virtualConsole = new VirtualConsole();
647
virtualConsole.on("error", (message) => {
648
console.error("Page error:", message);
649
});
650
651
const dom = new JSDOM(`
652
<!DOCTYPE html>
653
<script>console.log("Hello from page");</script>
654
`, { runScripts: "dangerously", virtualConsole });
655
```
656
657
## Important Notes
658
659
### Security Warning
660
661
The `runScripts: "dangerously"` option allows code execution within jsdom. This is not a secure sandbox - scripts can escape and access your Node.js environment if they try hard enough. **Only use with trusted content**.
662
663
### Unimplemented Features
664
665
jsdom does not support:
666
- **Navigation**: Cannot change the global object via `window.location.href = "..."`
667
- **Layout**: No visual layout calculation, layout properties return zeros
668
669
### Workarounds
670
671
- **Navigation**: Create new JSDOM instances for each page
672
- **Layout**: Use `Object.defineProperty()` to mock layout values
673
674
### Encoding Sniffing
675
676
jsdom accepts binary data (Buffer, ArrayBuffer, TypedArray) and automatically sniffs encoding using:
677
1. UTF-8 or UTF-16 BOM (takes precedence)
678
2. `charset` parameter in `contentType` option
679
3. `<meta charset>` tag in HTML
680
4. Default: `"UTF-8"` for XML, `"windows-1252"` for HTML
681
682
### Closing jsdoms
683
684
Timers keep Node.js processes alive. Use `window.close()` to terminate all timers and event listeners.
685
686
```javascript
687
dom.window.close(); // Shut down the jsdom
688
```
689
690
## Next Steps
691
692
- [Configuration](./configuration.md) - Detailed configuration options
693
- [DOM APIs](./dom-apis.md) - Available browser APIs
694
- [JSDOM Class](./jsdom-class.md) - JSDOM methods and properties
695
- [Resources](./resources.md) - Resource loading and cookies
696
- [Virtual Console](./virtual-console.md) - Console output handling
697
- [Troubleshooting](./troubleshooting.md) - Common issues and solutions
698
699
## Types
700
701
```javascript { .api }
702
interface LocationInfo {
703
startOffset: number;
704
endOffset: number;
705
startLine: number;
706
endLine: number;
707
startCol: number;
708
endCol: number;
709
startTag?: TagLocationInfo;
710
endTag?: TagLocationInfo;
711
attrs?: Record<string, AttrLocationInfo>;
712
}
713
714
interface TagLocationInfo {
715
startOffset: number;
716
endOffset: number;
717
startLine: number;
718
endLine: number;
719
startCol: number;
720
endCol: number;
721
attrs?: Record<string, AttrLocationInfo>;
722
}
723
724
interface AttrLocationInfo {
725
startOffset: number;
726
endOffset: number;
727
startLine: number;
728
endLine: number;
729
startCol: number;
730
endCol: number;
731
}
732
```
733