Skip to content
Newer
Older
100644 278 lines (192 sloc) 9.15 KB
86a167d @tmpvar Edited README.md via GitHub
authored Sep 20, 2011
1 # jsdom
e1abc48 @tmpvar added some metadata
authored Jan 19, 2010
2
2141fa9 @tmpvar update readme
authored Feb 16, 2011
3 A javascript implementation of the W3C DOM.
3235f39 @tmpvar
authored Feb 26, 2010
4
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
5 ## Install
edfe278 @tmpvar
authored Feb 21, 2010
6
4faadca @tmpvar updated readme
authored Feb 16, 2011
7 npm install jsdom
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
8
4faadca @tmpvar updated readme
authored Feb 16, 2011
9 or
03a6f07 @tmpvar formatting
authored Feb 7, 2010
10
4faadca @tmpvar updated readme
authored Feb 16, 2011
11 git clone http://github.com/tmpvar/jsdom.git
12 cd jsdom
bc6956c @tmpvar Edited README.md via GitHub
authored Jun 24, 2011
13 npm link
70fb7ec @tmpvar updated readme
authored Feb 5, 2010
14
83bfd22 @tmpvar Update docs
authored Oct 9, 2011
15 ## Human contact
16
17 see: [mailing list][]
18
19 [mailing list]: http://groups.google.com/group/jsdom
20
21
22
23
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
24 ## Easymode
4faadca @tmpvar updated readme
authored Feb 16, 2011
25
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
26 Bootstrapping a DOM is generally a difficult process involving many error prone steps. We didn't want jsdom to fall into the same trap and that is why a new method, `jsdom.env()`, has been added in jsdom 0.2.0 which should make everyone's lives easier.
4faadca @tmpvar updated readme
authored Feb 16, 2011
27
76c7415 @karunasagark fixed the example to config object
karunasagark authored May 15, 2011
28 with URL
29
4faadca @tmpvar updated readme
authored Feb 16, 2011
30 // Count all of the links from the nodejs build page
31 var jsdom = require("jsdom");
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 21, 2011
32
33 jsdom.env("http://nodejs.org/dist/", [
34 'http://code.jquery.com/jquery-1.5.min.js'
35 ],
36 function(errors, window) {
37 console.log("there have been", window.$("a").length, "nodejs releases!");
38 });
4faadca @tmpvar updated readme
authored Feb 16, 2011
39
40 or with raw html
41
42 // Run some jQuery on a html fragment
43 var jsdom = require('jsdom');
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
44
45 jsdom.env('<p><a class="the-link" href="http://jsdom.org>JSDOM\'s Homepage</a></p>', [
46 'http://code.jquery.com/jquery-1.5.min.js'
47 ],
48 function(errors, window) {
49 console.log("contents of a.the-link:", window.$("a.the-link").text());
50 });
51
4faadca @tmpvar updated readme
authored Feb 16, 2011
52
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
53 or with a configuration object
54
82b86b3 @tmpvar added hackernews example in the readme
authored Feb 18, 2011
55 // Print all of the news items on hackernews
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
56 var jsdom = require('jsdom');
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
57
76c7415 @karunasagark fixed the example to config object
karunasagark authored May 15, 2011
58 jsdom.env({
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
59 html: 'http://news.ycombinator.com/',
60 scripts: [
61 'http://code.jquery.com/jquery-1.5.min.js'
62 ],
63 done: function(errors, window) {
64 var $ = window.$;
65 console.log('HN Links');
66 $('td.title:not(:last) a').each(function() {
67 console.log(' -', $(this).text());
68 });
69 }
70 });
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
71
f4c9d4f @jsievert update readme to include information about new src configuration
jsievert authored Jul 21, 2011
72 or with raw javascript source
73
74 // Print all of the news items on hackernews
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
75 var jsdom = require('jsdom');
76 var fs = require('fs');
77 var jquery = fs.readFileSync("./jquery-1.6.2.min.js").toString();
f4c9d4f @jsievert update readme to include information about new src configuration
jsievert authored Jul 21, 2011
78
79 jsdom.env({
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
80 html: 'http://news.ycombinator.com/',
81 src: [
82 jquery
83 ],
84 done: function(errors, window) {
85 var $ = window.$;
86 console.log('HN Links');
87 $('td.title:not(:last) a').each(function() {
88 console.log(' -', $(this).text());
89 });
90 }
91 });
82b86b3 @tmpvar added hackernews example in the readme
authored Feb 18, 2011
92
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
93 ### How it works
94 `jsdom.env` is built for ease of use, which is rare in the world of the DOM! Since the web has some absolutely horrible javascript on it, as of jsdom 0.2.0 `jsdom.env` will not process external resources (scripts, images, etc). If you want to process the javascript use one of the methods below (`jsdom.jsdom` or `jsdom.jQueryify`)
4faadca @tmpvar updated readme
authored Feb 16, 2011
95
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
96 jsdom.env(html, [scripts], [config], callback)
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
97
98 - `html` (**required**)
99 May be a url, html fragment, or file
100
101 - `scripts` (**optional**)
102 May contain files or urls
f4c9d4f @jsievert update readme to include information about new src configuration
jsievert authored Jul 21, 2011
103
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
104 - `callback` (**required**)
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
105 Takes 2 arguments:
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
106 - `errors` : array of errors
107 - `window` : a brand new window
108
2de13bb @tmpvar readme update
authored Feb 18, 2011
109 _example:_ jsdom.env(html, function(`errors`, `window`) {})
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
110
111
112 If you would like to specify a configuration object
dccaea1 @ulteriorlife actually added link to website in the readme.md
ulteriorlife authored May 5, 2010
113
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
114 jsdom.env({ /* config */ })
2351e18 @tmpvar
authored Aug 19, 2010
115
83bfd22 @tmpvar Update docs
authored Oct 10, 2011
116 - config.html : see `html` above
117 - config.scripts : see `scripts` above
118 - config.src : An array of javascript strings that will be evaluated against the resulting document. Similar to `scripts`, but it accepts javascript instead of paths/urls.
119 - config.done : see `callback` above
120 - config.document :
121 - referer : the new document will have this referer
7e3aa70 @tmpvar Add docs for config.document.cookie
authored Oct 9, 2011
122 - cookie : manually set a cookie value i.e. `'key=value; expires=Wed, Sep 21 2011 12:00:00 GMT; path=/'`
83bfd22 @tmpvar Update docs
authored Oct 10, 2011
123 - config.features : see `Flexibility` section below. **Note**: the default feature set for jsdom.env does _not_ include fetching remote javascript and executing it. This is something that you will need to **carefully** enable yourself.
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
124
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
125 ## For the hardcore
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
126
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
127 If you want to spawn a document/window and specify all sorts of options this is the section for you. This section covers the `jsdom.jsdom` method:
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
128
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
129 var jsdom = require("jsdom").jsdom,
130 doc = jsdom(markup, level, options),
131 window = doc.createWindow();
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
132
1179c5e @papandreou Follow-up to pull req #286: Docs for creating an empty/partial document.
papandreou authored Sep 5, 2011
133 - `markup` is an html/xml document to be parsed. You can also pass `null` or an undefined value to get a basic document with empty head and body tags. Document fragments are also supported (including `""`), and will behave as sanely as possible (eg. the resulting document will lack the `head`, `body` and `documentElement` properties if the corresponding elements aren't included).
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
134 - `level` is `null` (which means level3) by default, but you can pass another level if you'd like.
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
135
136
137 var jsdom = require('jsdom'),
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
138 doc = jsdom.jsdom('<html><body></body></html>', jsdom.dom.level1.core)
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
139
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
140 - `options` see the **Flexibility** section below
141
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
142 ### Flexibility
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
143
144 One of the goals of jsdom is to be as minimal and light as possible. This section details how
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
145 someone can change the behavior of `Document`s on the fly. These features are baked into
4faadca @tmpvar updated readme
authored Feb 16, 2011
146 the `DOMImplementation` that every `Document` has, and may be tweaked in two ways:
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
147
148 1. When you create a new `Document` using the jsdom builder (`require('jsdom').jsdom()`)
149
dbca1f1 @tmpvar indentation in readme +1
authored Jan 18, 2011
150 var jsdom = require('jsdom').jsdom,
151 doc = jsdom("<html><body></body></html>", null, {
152 features: {
153 FetchExternalResources : ['img']
154 }
155 });
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
156
157 Do note, that this will only affect the document that is currently being created. All other documents
158 will use the defaults specified below (see: Default Features)
159
160 2. Previous to creating any documents you can modify the defaults for all future documents
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
161
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
162 require('jsdom').defaultDocumentFeatures = {
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
163 FetchExternalResources : ['script'],
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
164 ProcessExternalResources : false,
165 MutationEvents : false,
166 QuerySelector : false
167 }
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
168
169
170
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
171 #### Default Features
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
172
173 Default features are extremely important for jsdom as they lower the configuration requirement and present developers a set of consistent default behaviors. The following sections detail the available features, their defaults, and the values that jsdom uses.
174
175
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
176 `FetchExternalResources`
177 _Default_: ['script']
178 _Allowed_: ['script', 'img', 'css', 'frame', 'link'] or false
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
179
180 Enables/Disables fetching files over the filesystem/http
181
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
182 `ProcessExternalResources`
183 _default_: ['script']
184 _allowed_: ['script'] or false
deaedc1 @tmpvar updated README, bump version (0.2.1), and removed old files
authored Jul 22, 2011
185
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
186 Disabling this will disable script execution (currently only javascript).
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
187
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
188 `MutationEvents`
189 _default_: '2.0'
190 _allowed_ : '2.0' or false
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
191
192 Initially enabled to be up to spec. Disable this if you do not need mutation events and want jsdom to be a bit more efficient.
193
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
194 **Note**: `ProcessExternalResources` requires this to be enabled
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
195
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
196 `QuerySelector`
197 _default_ : false
198 _allowed_ : true
aeb0e9c @tmpvar updated readme
authored Jan 18, 2011
199
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
200 This feature is backed by [sizzle][] but currently causes problems with some libraries. Enable this if you want `document.querySelector` and friends, but be aware that many libraries feature detect for this, and it may cause you a bit of trouble.
1d79a8c @tmpvar preparing for takeoff
authored Feb 18, 2011
201
202 [sizzle]:http://sizzlejs.com/
2351e18 @tmpvar
authored Aug 19, 2010
203
4faadca @tmpvar updated readme
authored Feb 16, 2011
204 # More Examples
2351e18 @tmpvar
authored Aug 19, 2010
205
0df8ca5 @tmpvar updated readme with some important updates
authored Sep 18, 2010
206 ## Creating a document-less window
207
8e0528b @tmpvar
authored Sep 18, 2010
208 var jsdom = require("jsdom"),
33797d9 @tmpvar update to jsdom.createWindow(), docs, and a version bump
authored Sep 18, 2010
209 window = jsdom.createWindow();
f25097f @tmpvar
authored Sep 18, 2010
210
33797d9 @tmpvar update to jsdom.createWindow(), docs, and a version bump
authored Sep 18, 2010
211 console.log(window.document);
212 // output: undefined
f25097f @tmpvar
authored Sep 18, 2010
213
33797d9 @tmpvar update to jsdom.createWindow(), docs, and a version bump
authored Sep 18, 2010
214 ## Creating a document
215 var jsdom = require("jsdom"),
216 doc = new (jsdom.dom.level1.core.Document)();
217 console.log(doc.nodeName);
218 // outputs: #document
0df8ca5 @tmpvar updated readme with some important updates
authored Sep 18, 2010
219
33797d9 @tmpvar update to jsdom.createWindow(), docs, and a version bump
authored Sep 18, 2010
220 ## Creating a browser-like BOM/DOM/Window
0df8ca5 @tmpvar updated readme with some important updates
authored Sep 18, 2010
221
4faadca @tmpvar updated readme
authored Feb 16, 2011
222 var jsdom = require("./lib/jsdom").jsdom,
223 document = jsdom("<html><head></head><body>hello world</body></html>"),
224 window = document.createWindow();
0df8ca5 @tmpvar updated readme with some important updates
authored Sep 18, 2010
225
a60bb1c @tmpvar
authored Sep 18, 2010
226 console.log(window.document.innerHTML);
227 // output: '<html><head></head><body>hello world</body></html>'
0df8ca5 @tmpvar updated readme with some important updates
authored Sep 18, 2010
228
a60bb1c @tmpvar
authored Sep 18, 2010
229 console.log(window.innerWidth)
230 // output: 1024
0df8ca5 @tmpvar updated readme with some important updates
authored Sep 18, 2010
231
a60bb1c @tmpvar
authored Sep 18, 2010
232 console.log(typeof window.document.getElementsByClassName);
233 // outputs: function
0df8ca5 @tmpvar updated readme with some important updates
authored Sep 18, 2010
234
a60bb1c @tmpvar
authored Sep 18, 2010
235
30575d5 @tmpvar fixed examples, and a bug in createWindow()
authored Sep 18, 2010
236 ## jQueryify
237
238 var jsdom = require("jsdom"),
a60bb1c @tmpvar
authored Sep 18, 2010
239 window = jsdom.jsdom().createWindow();
30575d5 @tmpvar fixed examples, and a bug in createWindow()
authored Sep 18, 2010
240
66018a3 Added missing quote
Felix Gnass authored Nov 10, 2010
241 jsdom.jQueryify(window, 'http://code.jquery.com/jquery-1.4.2.min.js' , function() {
242 window.$('body').append('<div class="testing">Hello World, It works</div>');
243 console.log(window.$('.testing').text());
a60bb1c @tmpvar
authored Sep 18, 2010
244 });
4faadca @tmpvar updated readme
authored Feb 16, 2011
245
ce82b49 @tmpvar update readme and populate changelog
authored Jul 21, 2011
246 # Test Compliance:
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
247
83bfd22 @tmpvar Update docs
authored Oct 10, 2011
248 level1/core 531/531 100%
249 level1/html 238/238 100%
250 level1/svg 527/527 100%
251 level2/core 283/283 100%
252 level2/html 687/687 100%
253 level2/style 4/4 100%
254 level2/extra 4/4 100%
255 level3/xpath 93/93 100%
2b885de @tmpvar Bump version (0.2.6)
authored Oct 9, 2011
256 window/index 5/5 100%
83bfd22 @tmpvar Update docs
authored Oct 10, 2011
257 window/script 8/8 100%
258 window/frame 14/14 100%
259 sizzle/index 12/15 80%
2b885de @tmpvar Bump version (0.2.6)
authored Oct 10, 2011
260 jsdom/index 63/63 100%
83bfd22 @tmpvar Update docs
authored Oct 10, 2011
261 --------------------------------------
2b885de @tmpvar Bump version (0.2.6)
authored Oct 10, 2011
262 TOTALS: 3/2472 failed; 99% success
263 TIME: 16730ms
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
264
ce82b49 @tmpvar update readme and populate changelog
authored Jul 22, 2011
265 ## Running the tests
4faadca @tmpvar updated readme
authored Feb 16, 2011
266
ce82b49 @tmpvar update readme and populate changelog
authored Jul 22, 2011
267 First you'll want to `npm install -g nodeunit` then `npm install --dev`
4faadca @tmpvar updated readme
authored Feb 16, 2011
268
ce82b49 @tmpvar update readme and populate changelog
authored Jul 22, 2011
269 Using `test/runner` you can slice and dice which tests your want to run from different levels. Usage is as follows:
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored Feb 18, 2011
270
ce82b49 @tmpvar update readme and populate changelog
authored Jul 22, 2011
271 test/runner --help
272 Run the jsdom test suite
4faadca @tmpvar updated readme
authored Feb 16, 2011
273
ce82b49 @tmpvar update readme and populate changelog
authored Jul 22, 2011
274 Options:
275 -s, --suites suites that you want to run. ie: -s level1/core,1/html,html [string]
276 -f, --fail-fast stop on the first failed test
277 -h, --help show the help
83bfd22 @tmpvar Update docs
authored Oct 10, 2011
278 -t, --tests choose the test cases to run. ie: -t jquery
Something went wrong with that request. Please try again.