@applitools/dom-capture

dom-capture

Script for getting a representation of the DOM in JSON format with information on position and computed style for each element.

Installing

npm install @applitools/dom-capture

Usage

From Node.js

This package exports getCaptureDomScript and getCaptureDomAndPollScript that can be used when working with puppeteer, CDP or Selenium in Node.js.

This async function returns a string with a function that can be sent to the browser for evaluation. It doesn't immediately invoke the function, so the sender should wrap it as an IIFE. For example:

  const {getCaptureDom} = require('@applitools/dom-capture');
  const captureDom = await getCaptureDom();
  const returnValue = await page.evaluate(`(${captureDom})()`); // puppeteer

From the browser

By using the non bundled version of the script: src/browser/captureFrame.

This function can then be bundled together with other client-side code so they are consumed regardless of a browser driver.

From non-JavaScript code

This package's dist folder contains a script that can be sent to the browser regardless of driver and language. An agent that wishes to extract information from a webpage can read the contents of dist/captureDom and send that to the browser as an async script. There's still the need to wrap it in a way that invokes it.

For example in Java:

  Object response = driver.executeAsyncScript("const callback = arguments[arguments.length - 1];(" + captureDom + ")().then(callback, err => callback(err.message))";

The captureDom script

This script receives information about what should be captured, and a document from which to capture the information.

Here are the available arguments with their defaults (values can be found in src/browser/constants.js):

captureFrame({
  doc = document,
  styleProps = DEFAULT_STYLE_PROPS,
  rectProps = DEFAULT_RECT_PROPS,
  ignoredTagNames = DEFAULT_IGNORED_TAG_NAMES,
  addStats = false,
  fetchTimeLimit = 30000,
}

• styleProps - an array containing the css properties that should be captured for computed style. E.g. ['background'].
• rectProps - an array containing the bounding client rect properties that should be captured. E.g. ['top', 'left'].
• ignoredTagNames - an array containing tag names that should not be captured. E.g. ['head'].
• addStats
• fetchTimeLimit

The script returns an object representing the DOM in hierarchical structure (as opposed to the flat structure of CDT), with computed style and bounding client rect information for each element.

Each element has the following properties:

• tagName
• style
• rect
• attributes
• childNodes
• shadowRoot

Text nodes have the following properties:

• tagName - always #text.
• text - the text of the text node.

In addition, in the object representing the HTML element there are 2 other special properties:

• css - the bundled css string for all the css in this frame (including style tags, link elements and css imports).
• images - image size information for all the images included as background image. The structure is as follows:

{
  "http://some/image.jpg": {width, height}
}

ShadowRoot nodes have childNodes, css and images attributes:

• notice that the css applies only to the dom tree starting from this shadowRoot (i.e. starting from it's childNodes), also note that css from outside this dom tree (i.e. css from a containing HTML or shadowRoot) does not apply to this tree.
• images is also relevant only in the current shadowRoot dom tree context.

The return value is a string that consists of a prefix specifying un fetched css resources and iframes, followed by the actual DOM structure. For example:

{"separator":"-----","cssStartToken":"#####","cssEndToken":"#####","iframeStartToken":"\"@@@@@","iframeEndToken":"@@@@@\""}
http://url/to/css/1
http://url/to/css/2
http://url/to/css/3
-----
html[1]/body[1]/iframe[2],html[1]/body[1]/iframe[1]
html[1]/body[1]/div[10]/div[3]/iframe[2],html[1]/body[1]/div[4]/iframe[6]
-----
{"tagName":"HTML","style":{...},"rect":{...},"childNodes":[
  {"tagName":"BODY","style":{...},"rect":{...},"childNodes":[
    {"tagName":"DIV","style":{...},"rect":{...},"childNodes":[
      {"tagName":"#text","text":"hello"}],"shadowRoot": { "childNodes": [{"tagName": "DIV","style": {...},"rect":{...},"childNodes":[]}],"css": `/** http://some/url.css **/
      div.inShadow{border: 5px solid salmon;}`,
      "images": {}}
    },
    {"tagName":"IFRAME","style":{...},"rect":{...},"attributes":{"src":"some/url.html"},"childNodes":[
      {"tagName":"HTML","style":{...},"rect":{...},"childNodes":[
        {"tagName":"BODY","style":{...},"rect":{...},"childNodes":[
          {"tagName":"IFRAME","style":{...},"rect":{...},"attributes":{"src":"http://localhost:7272/iframe.html","width":"200","height":"100"},"childNodes":["@@@@@html[1]/body[1]/iframe[2],html[1]/body[1]/iframe[1]@@@@@"}]}],
      "css":"","images":{}}]}]}],
  "css":`/** http://some/url.css **/
         div{border: 5px solid salmon;}
         /** http://url/to/css/1 **/
         #####http://url/to/css/1#####
         /** http://url/to/css/2 **/
         #####http://url/to/css/2#####
         /** http://url/to/css/3 **/
         #####http://url/to/css/3#####`,
  "images":{}}
-----
{
  "total": {
    "startTime": 1573131315953,
    "endTime": 1573131315964,
    "elapsedTime": 11
  },
  "prefetchCss": {
    "startTime": 1573131315953,
    "endTime": 1573131315961,
    "elapsedTime": 8
  },
  "doCaptureDoc": {
    "startTime": 1573131315961,
    "endTime": 1573131315964,
    "elapsedTime": 3
  },
  "waitForImages": {
    "startTime": 1573131315964,
    "endTime": 1573131315964,
    "elapsedTime": 0
  }
}

The first line should be parsed as a JSON and its properties serve to parse the rest of the string. The following lines up to the next separator are urls to cross-origin css resources. The following lines up to the next separator are comma-separated lists of xpath expressions that uniquely identify iframes (iframe per line). after the following separator is the JSON structure that was captured from the DOM. The last part is the performance metrics of the operation. This part is optional depends on the value of 3rd parameter in captureFrame function.

Notice how every css resource in the prefix has a corresponding token of the structure #####url#####, and every cross-origin iframe in the prefix has a corresponding token of the structure "@@@@@path@@@@@".

In order to complete the process of capturing the DOM, the SDK (or other code using this script) should fetch all the css resources, run JSON.stringify on the result of each css (this is important for escaping), then replace the token with the escaped css string. In addition, for each cross-origin iframe the captureDom script should be run again in the context of the frame, and the same process should be done recursively. When finalizing the result of a frame, it should then be injected to its parent's result in the corresponding token.

captureDomPoll

This function calls captureDom and returns immediately. Then pollResult should be called (or any of the ...Poll script variations, for backwards compatibility) to get the polling result.

Arguments

This function accepts the same arguments as captureDom, with one additional parameter:

• chunkByteLength - this will cause additional polling after the snapshot is ready, and will transfer the result in chunks, with the chunk size specified. Default: undefined.

For example, to pass a maximum chunk size of 256MB:

captureDomPoll({chunkByteLength: 1024 * 1024 * 256})

Return value

The polling result is a stringified JSON object, which is of the following shape:

{
  status: string,
  error: string,
  value: object
}

Status could be one of:

• "SUCCESS" - there's a value field with the return value
• "ERROR" - there's an error field with the result
• "WIP" - internal status, handled by pollResult to continue polling until "SUCCESS" or "ERROR" are received.
• "SUCCESS_CHUNKED" - internal status, handled by pollResult to continue polling until the entire value is received (used with chunkByteLength).

pollResult

returns the poll result - an object with the same shape as processPagePoll.