mirror of
https://github.com/S2-/minifyfromhtml.git
synced 2025-08-03 12:20:04 +02:00
update node modules
This commit is contained in:
102
node_modules/jsdom/README.md
generated
vendored
102
node_modules/jsdom/README.md
generated
vendored
@@ -5,9 +5,7 @@
|
||||
|
||||
jsdom is a pure-JavaScript implementation of many web standards, notably the WHATWG [DOM](https://dom.spec.whatwg.org/) and [HTML](https://html.spec.whatwg.org/multipage/) Standards, for use with Node.js. In general, the goal of the project is to emulate enough of a subset of a web browser to be useful for testing and scraping real-world web applications.
|
||||
|
||||
The latest versions of jsdom require Node.js v6 or newer. (Versions of jsdom below v10 still work with Node.js v4, but are unsupported.)
|
||||
|
||||
As of v10, jsdom has a new API (documented below). The old API is still supported for now; [see its documentation](./lib/old-api.md) for details.
|
||||
The latest versions of jsdom require Node.js v8 or newer. (Versions of jsdom below v12 still work with Node.js v6, but are unsupported.)
|
||||
|
||||
## Basic usage
|
||||
|
||||
@@ -25,7 +23,7 @@ console.log(dom.window.document.querySelector("p").textContent); // "Hello world
|
||||
|
||||
(Note that jsdom will parse the HTML you pass it just like a browser does, including implied `<html>`, `<head>`, and `<body>` tags.)
|
||||
|
||||
The resulting object is an instance of the `JSDOM` class, which contains a number of useful properties and methods besides `window`. In general it can be used to act on the jsdom from the "outside," doing things that are not possible with the normal DOM APIs. For simple cases, where you don't need any of this functionality, we recommend a coding pattern like
|
||||
The resulting object is an instance of the `JSDOM` class, which contains a number of useful properties and methods besides `window`. In general, it can be used to act on the jsdom from the "outside," doing things that are not possible with the normal DOM APIs. For simple cases, where you don't need any of this functionality, we recommend a coding pattern like
|
||||
|
||||
```js
|
||||
const { window } = new JSDOM(`...`);
|
||||
@@ -35,6 +33,8 @@ const { document } = (new JSDOM(`...`)).window;
|
||||
|
||||
Full documentation on everything you can do with the `JSDOM` class is below, in the section "`JSDOM` Object API".
|
||||
|
||||
_Important note: in the default configuration, JavaScript globals like `window.Date` or `window.Map` will not exist. Read the "Executing scripts" section below for more._
|
||||
|
||||
## Customizing jsdom
|
||||
|
||||
The `JSDOM` constructor accepts a second parameter which can be used to customize your jsdom in the following ways.
|
||||
@@ -46,16 +46,16 @@ const dom = new JSDOM(``, {
|
||||
url: "https://example.org/",
|
||||
referrer: "https://example.com/",
|
||||
contentType: "text/html",
|
||||
userAgent: "Mellblomenator/9000",
|
||||
includeNodeLocations: true
|
||||
includeNodeLocations: true,
|
||||
storageQuota: 10000000
|
||||
});
|
||||
```
|
||||
|
||||
- `url` sets the value returned by `window.location`, `document.URL`, and `document.documentURI`, and affects things like resolution of relative URLs within the document and the same-origin restrictions and referrer used while fetching subresources. It defaults to `"about:blank"`.
|
||||
- `referrer` just affects the value read from `document.referrer`. It defaults to no referrer (which reflects as the empty string).
|
||||
- `contentType` affects the value read from `document.contentType`, and how the document is parsed: as HTML or as XML. Values that are not `"text/html"` or an [XML mime type](https://html.spec.whatwg.org/multipage/infrastructure.html#xml-mime-type) will throw. It defaults to `"text/html"`.
|
||||
- `userAgent` affects the value read from `navigator.userAgent`, as well as the `User-Agent` header sent while fetching subresources. It defaults to <code>\`Mozilla/5.0 (${process.platform}) AppleWebKit/537.36 (KHTML, like Gecko) jsdom/${jsdomVersion}\`</code>.
|
||||
- `includeNodeLocations` preserves the location info produced by the HTML parser, allowing you to retrieve it with the `nodeLocation()` method (described below). It also ensures that line numbers reported in exception stack traces for code running inside `<script>` elements are correct. It defaults to `false` to give the best performance, and cannot be used with an XML content type since our XML parser does not support location info.
|
||||
- `storageQuota` is the maximum size in code units for the separate storage areas used by `localStorage` and `sessionStorage`. Attempts to store data larger than this limit will cause a `DOMException` to be thrown. By default, it is set to 5,000,000 code units per origin, as inspired by the HTML specification.
|
||||
|
||||
Note that both `url` and `referrer` are canonicalized before they're used, so e.g. if you pass in `"https:example.com"`, jsdom will interpret that as if you had given `"https://example.com/"`. If you pass an unparseable URL, the call will throw. (URLs are parsed and serialized according to the [URL Standard](http://url.spec.whatwg.org/).)
|
||||
|
||||
@@ -91,7 +91,7 @@ If you want to execute _external_ scripts, included via `<script src="">`, you'l
|
||||
|
||||
Note that event handler attributes, like `<div onclick="">`, will also not function unless `runScripts` is set to `"dangerously"`. (However, event handler _properties_, like `div.onclick = ...`, will function regardless of `runScripts`.)
|
||||
|
||||
If you are simply trying to execute script "from the outside", instead of letting `<script>` elements (and inline event handlers) run "from the inside", you can use the `runScripts: "outside-only"` option, which enables `window.eval`:
|
||||
If you are simply trying to execute script "from the outside", instead of letting `<script>` elements (and inline event handlers) run "from the inside", you can use the `runScripts: "outside-only"` option, which enables all the JavaScript spec-provided globals to be installed on `window`. This includes things like `window.Array`, `window.Promise`, etc. It also, notably, includes `window.eval`, which allows running scripts, but with the jsdom `window` as the global:
|
||||
|
||||
```js
|
||||
const window = (new JSDOM(``, { runScripts: "outside-only" })).window;
|
||||
@@ -128,14 +128,66 @@ Note that jsdom still [does not do any layout or rendering](#unimplemented-parts
|
||||
|
||||
### Loading subresources
|
||||
|
||||
#### Basic options
|
||||
|
||||
By default, jsdom will not load any subresources such as scripts, stylesheets, images, or iframes. If you'd like jsdom to load such resources, you can pass the `resources: "usable"` option, which will load all usable resources. Those are:
|
||||
|
||||
* Frames and iframes, via `<frame>` and `<iframe>`
|
||||
* Stylesheets, via `<link rel="stylesheet">`
|
||||
* Scripts, via `<script>`, but only if `runScripts: "dangerously"` is also set
|
||||
* Images, via `<img>`, but only if the `canvas` (or `canvas-prebuilt`) npm package is also installed (see "Canvas Support" below)
|
||||
* Images, via `<img>`, but only if the `canvas` npm package is also installed (see "[Canvas Support](#canvas-support)" below)
|
||||
|
||||
In the future we plan to offer more customization of resource loading via this option, but for now the default and the `"usable"` option are the two modes offered.
|
||||
#### Advanced configuration
|
||||
|
||||
_This resource loader system is new as of jsdom v12.0.0, and we'd love your feedback on whether it meets your needs and how easy it is to use. Please file an issue to discuss!_
|
||||
|
||||
To more fully customize jsdom's resource-loading behavior, you can pass an instance of the `ResourceLoader` class as the `resources` option value:
|
||||
|
||||
```js
|
||||
const resourceLoader = new jsdom.ResourceLoader({
|
||||
proxy: "http://127.0.0.1:9001",
|
||||
strictSSL: false,
|
||||
userAgent: "Mellblomenator/9000",
|
||||
});
|
||||
const dom = new JSDOM(``, { resources: resourceLoader });
|
||||
```
|
||||
|
||||
The three options to the `ResourceLoader` constructor are:
|
||||
|
||||
- `proxy` is the address of an HTTP proxy to be used.
|
||||
- `strictSSL` can be set to false to disable the requirement that SSL certificates be valid.
|
||||
- `userAgent` affects the `User-Agent` header sent, and thus the resulting value for `navigator.userAgent`. It defaults to <code>\`Mozilla/5.0 (${process.platform || "unknown OS"}) AppleWebKit/537.36 (KHTML, like Gecko) jsdom/${jsdomVersion}\`</code>.
|
||||
|
||||
You can further customize resource fetching by subclassing `ResourceLoader` and overriding the `fetch()` method. For example, here is a version that only returns results for requests to a trusted origin:
|
||||
|
||||
```js
|
||||
class CustomResourceLoader extends jsdom.ResourceLoader {
|
||||
fetch(url, options) {
|
||||
// Override the contents of this script to do something unusual.
|
||||
if (url === "https://example.com/some-specific-script.js") {
|
||||
return Promise.resolve(Buffer.from("window.someGlobal = 5;"));
|
||||
}
|
||||
|
||||
return super.fetch(url, options);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
jsdom will call your custom resource loader's `fetch()` method whenever it encounters a "usable" resource, per the above section. The method takes a URL string, as well as a few options which you should pass through unmodified if calling `super.fetch()`. It must return a promise for a Node.js `Buffer` object, or return `null` if the resource is intentionally not to be loaded. In general, most cases will want to delegate to `super.fetch()`, as shown.
|
||||
|
||||
One of the options you will receive in `fetch()` will be the element (if applicable) that is fetching a resource.
|
||||
|
||||
```js
|
||||
class CustomResourceLoader extends jsdom.ResourceLoader {
|
||||
fetch(url, options) {
|
||||
if (options.element) {
|
||||
console.log(`Element ${options.element.localName} is requesting the url ${url}`);
|
||||
}
|
||||
|
||||
return super.fetch(url, options);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Virtual consoles
|
||||
|
||||
@@ -172,7 +224,7 @@ There is also a special event, `"jsdomError"`, which will fire with error object
|
||||
- Script execution errors that are not handled by a window `onerror` event handler that returns `true` or calls `event.preventDefault()`
|
||||
- Not-implemented errors resulting from calls to methods, like `window.alert`, which jsdom does not implement, but installs anyway for web compatibility
|
||||
|
||||
If you're using `sendTo(c)` to send errors to `c`, by default it will call `console.error` with information from `"jsdomError"` events. If you'd prefer to maintain a strict one-to-one mapping of events to method calls, and perhaps handle `"jsdomError"`s yourself, then you can do
|
||||
If you're using `sendTo(c)` to send errors to `c`, by default it will call `c.error(errorStack[, errorDetail])` with information from `"jsdomError"` events. If you'd prefer to maintain a strict one-to-one mapping of events to method calls, and perhaps handle `"jsdomError"`s yourself, then you can do
|
||||
|
||||
```js
|
||||
virtualConsole.sendTo(c, { omitJSDOMErrors: true });
|
||||
@@ -257,7 +309,7 @@ console.log(dom.nodeLocation(imgEl)); // { startOffset: 13, endOffset: 32 }
|
||||
|
||||
Note that this feature only works if you have set the `includeNodeLocations` option; node locations are off by default for performance reasons.
|
||||
|
||||
### Running vm-created scripts with `runVMScript(script)`
|
||||
### Running vm-created scripts with `runVMScript(script[, options])`
|
||||
|
||||
The built-in `vm` module of Node.js allows you to create `Script` instances, which can be compiled ahead of time and then run multiple times on a given "VM context". Behind the scenes, a jsdom `Window` is indeed a VM context. To get access to this ability, use the `runVMScript()` method:
|
||||
|
||||
@@ -282,6 +334,8 @@ dom.window.ran === 3;
|
||||
|
||||
This is somewhat-advanced functionality, and we advise sticking to normal DOM APIs (such as `window.eval()` or `document.createElement("script")`) unless you have very specific needs.
|
||||
|
||||
`runVMScript()` also takes an `options` object as its second argument. See the [Node.js docs](https://nodejs.org/api/vm.html#vm_script_runincontext_contextifiedsandbox_options) for details. (This functionality does not work when [using jsdom in a web browser](running-jsdom-inside-a-web-browser).)
|
||||
|
||||
### Reconfiguring the jsdom with `reconfigure(settings)`
|
||||
|
||||
The `top` property on `window` is marked `[Unforgeable]` in the spec, meaning it is a non-configurable own property and thus cannot be overridden or shadowed by normal code running inside the jsdom, even using `Object.defineProperty`.
|
||||
@@ -302,7 +356,7 @@ dom.window.top === myFakeTopForTesting;
|
||||
dom.window.location.href === "https://example.com/";
|
||||
```
|
||||
|
||||
Note that changing the jsdom's URL will impact all APIs that return the current document URL, such as `window.location`, `document.URL`, and `document.documentURI`, as well as resolution of relative URLs within the document, and the same-origin checks and referrer used while fetching subresources. It will not, however, perform a navigation to the contents of that URL; the contents of the DOM will remain unchanged, and no new instances of `Window`, `Document`, etc. will be created.
|
||||
Note that changing the jsdom's URL will impact all APIs that return the current document URL, such as `window.location`, `document.URL`, and `document.documentURI`, as well as the resolution of relative URLs within the document, and the same-origin checks and referrer used while fetching subresources. It will not, however, perform navigation to the contents of that URL; the contents of the DOM will remain unchanged, and no new instances of `Window`, `Document`, etc. will be created.
|
||||
|
||||
## Convenience APIs
|
||||
|
||||
@@ -322,12 +376,10 @@ The options provided to `fromURL()` are similar to those provided to the `JSDOM`
|
||||
|
||||
- The `url` and `contentType` options cannot be provided.
|
||||
- The `referrer` option is used as the HTTP `Referer` request header of the initial request.
|
||||
- The `userAgent` option is used as the HTTP `User-Agent` request header of any requests.
|
||||
- The `resources` option also affects the initial request; this is useful if you want to, for example, configure a proxy (see above).
|
||||
- The resulting jsdom's URL, content type, and referrer are determined from the response.
|
||||
- Any cookies set via HTTP `Set-Cookie` response headers are stored in the jsdom's cookie jar. Similarly, any cookies already in a supplied cookie jar are sent as HTTP `Cookie` request headers.
|
||||
|
||||
The initial request is not infinitely customizable to the same extent as is possible in a package like [request](https://www.npmjs.com/package/request); `fromURL()` is meant to be a convenience API for the majority of cases. If you need greater control over the initial request, you should perform it yourself, and then use the `JSDOM` constructor manually.
|
||||
|
||||
### `fromFile()`
|
||||
|
||||
Similar to `fromURL()`, jsdom also provides a `fromFile()` factory method for constructing a jsdom from a filename:
|
||||
@@ -353,13 +405,13 @@ For the very simplest of cases, you might not need a whole `JSDOM` instance with
|
||||
const frag = JSDOM.fragment(`<p>Hello</p><p><strong>Hi!</strong>`);
|
||||
|
||||
frag.childNodes.length === 2;
|
||||
frag.querySelector("strong").textContent = "Why hello there!";
|
||||
frag.querySelector("strong").textContent === "Hi!";
|
||||
// etc.
|
||||
```
|
||||
|
||||
Here `frag` is a [`DocumentFragment`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) instance, whose contents are created by parsing the provided string. The parsing is done using a `<template>` element, so you can include any element there (including ones with weird parsing rules like `<td>`).
|
||||
Here `frag` is a [`DocumentFragment`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) instance, whose contents are created by parsing the provided string. The parsing is done using a `<template>` element, so you can include any element there (including ones with weird parsing rules like `<td>`). It's also important to note that the resulting `DocumentFragment` will not have [an associated browsing context](https://html.spec.whatwg.org/multipage/#concept-document-bc): that is, elements' `ownerDocument` will have a null `defaultView` property, resources will not load, etc.
|
||||
|
||||
All invocations of the `fragment()` factory result in `DocumentFragment`s that share the same owner `Document` and `Window`. This allows many calls to `fragment()` with no extra overhead. But it also means that calls to `fragment()` cannot be customized with any options.
|
||||
All invocations of the `fragment()` factory result in `DocumentFragment`s that share the same template owner `Document`. This allows many calls to `fragment()` with no extra overhead. But it also means that calls to `fragment()` cannot be customized with any options.
|
||||
|
||||
Note that serialization is not as easy with `DocumentFragment`s as it is with full `JSDOM` objects. If you need to serialize your DOM, you should probably use the `JSDOM` constructor more directly. But for the special case of a fragment containing a single element, it's pretty easy to do through normal means:
|
||||
|
||||
@@ -372,7 +424,7 @@ console.log(frag.firstChild.outerHTML); // logs "<p>Hello</p>"
|
||||
|
||||
### Canvas support
|
||||
|
||||
jsdom includes support for using the [`canvas`](https://www.npmjs.com/package/canvas) or [`canvas-prebuilt`](https://npmjs.org/package/canvas-prebuilt) package to extend any `<canvas>` elements with the canvas API. To make this work, you need to include `canvas` as a dependency in your project, as a peer of `jsdom`. If jsdom can find the `canvas` package, it will use it, but if it's not present, then `<canvas>` elements will behave like `<div>`s.
|
||||
jsdom includes support for using the [`canvas`](https://www.npmjs.com/package/canvas) package to extend any `<canvas>` elements with the canvas API. To make this work, you need to include `canvas` as a dependency in your project, as a peer of `jsdom`. If jsdom can find the `canvas` package, it will use it, but if it's not present, then `<canvas>` elements will behave like `<div>`s. Since jsdom v13, version 2.x of `canvas` is required; version 1.x is no longer supported.
|
||||
|
||||
### Encoding sniffing
|
||||
|
||||
@@ -408,7 +460,7 @@ By default jsdom elements are formatted as plain old JS objects in the console.
|
||||
|
||||
### Asynchronous script loading
|
||||
|
||||
People often have trouble with asynchronous script loading when using jsdom. Many pages loads scripts asynchronously, but there is no way to tell when they're done doing so, and thus when it's a good time to run your code and inspect the resulting DOM structure. This is a fundamental limitation; we cannot predict what scripts on the web page will do, and so cannot tell you when they are done loading more scripts.
|
||||
People often have trouble with asynchronous script loading when using jsdom. Many pages load scripts asynchronously, but there is no way to tell when they're done doing so, and thus when it's a good time to run your code and inspect the resulting DOM structure. This is a fundamental limitation; we cannot predict what scripts on the web page will do, and so cannot tell you when they are done loading more scripts.
|
||||
|
||||
This can be worked around in a few ways. The best way, if you control the page in question, is to use whatever mechanisms are given by the script loader to detect when loading is done. For example, if you're using a module loader like RequireJS, the code could look like:
|
||||
|
||||
@@ -449,14 +501,6 @@ This is done mainly for performance and memory reasons: creating separate copies
|
||||
|
||||
Nevertheless, we remain interested in one day providing an option to create an "independent" jsdom, at the cost of some performance.
|
||||
|
||||
### Missing features in the new API
|
||||
|
||||
Compared to the old jsdom API from v9.x and before, the new API is noticeably missing fine-grained control of resource loads. Previous versions of jsdom allowed you to set options that were used when making requests (both for the initial request, in the old equivalent of `JSDOM.fromURL()`, and for subresource requests). They also allowed you to control which subresources were requested and applied to the main document, so that you could e.g. download stylesheets but not scripts. Finally, they provided a customizable resource loader that let you intercept any outgoing request and fulfill it with a completely synthetic response.
|
||||
|
||||
None of these features are yet in the new jsdom API, although we are hoping to add them back soon! This requires a decent amount of behind-the-scenes work to implement in a reasonable way, unfortunately.
|
||||
|
||||
In the meantime, please feel free to use the old jsdom API to get access to this functionality. It is supported and maintained, although it will not be getting new features. The documentation is found in [lib/old-api.md](./lib/old-api.md).
|
||||
|
||||
### Unimplemented parts of the web platform
|
||||
|
||||
Although we enjoy adding new features to jsdom and keeping it up to date with the latest web specs, it has many missing APIs. Please feel free to file an issue for anything missing, but we're a small and busy team, so a pull request might work even better.
|
||||
|
Reference in New Issue
Block a user