@applitools/dom-snapshot - npm Package Compare versions

Comparing version 4.1.2 to 4.2.0

CHANGELOG.md

@@ -7,2 +7,10 @@
 
+## 4.2.0 - 2020/10/6
+
+- fix inline frames
+- extend current polling protocol to support chunking
+- add `pollResult` script which could be used to avoid sending full script in case of polling
+- add `serializeResources` and `compressResources` options for `processPage` script
+- deprecate `processPageAndSerialize`, `processPageAndSerializePoll`, `processPageAndSerializeForIE` and `processPageAndSerializePollForIE` scripts
+
 ## 4.1.2 - 2020/10/6
@@ -9,0 +17,0 @@

index.js

@@ -5,13 +5,27 @@ 'use strict';
 const getProcessPage = makeGetScript('processPage');
+const getProcessPagePoll = makeGetScript('processPagePoll');
 const getProcessPageAndSerialize = makeGetScript('processPageAndSerialize');
 const getProcessPageAndSerializePoll = makeGetScript('processPageAndSerializePoll');
+const getPollResult = makeGetScript('pollResult');
+const getProcessPageForIE = makeGetScript('processPageForIE');
+const getProcessPagePollForIE = makeGetScript('processPagePollForIE');
 const getProcessPageAndSerializeForIE = makeGetScript('processPageAndSerializeForIE');
 const getProcessPageAndSerializePollForIE = makeGetScript('processPageAndSerializePollForIE');
+const getPollResultForIE = makeGetScript('pollResultForIE');
 
 module.exports = {
   getProcessPage,
+  getProcessPagePoll,
+  getPollResult,
+
+  // IE scripts:
+  getProcessPageForIE,
+  getProcessPagePollForIE,
+  getPollResultForIE,
+
+  // deprecated:
   getProcessPageAndSerialize,
+  getProcessPageAndSerializePoll,
   getProcessPageAndSerializeForIE,
-  getProcessPageAndSerializePoll,
   getProcessPageAndSerializePollForIE,
 };

package.json

 {
   "name": "@applitools/dom-snapshot",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "main": "index.js",
@@ -15,3 +15,3 @@ "license": "SEE LICENSE IN LICENSE",
     "surge": "surge test/fixtures applitools-dom-snapshot.surge.sh",
-    "preversion": "BONGO_SKIP_VERIFY_VERSIONS=1 BONGO_SKIP_VERIFY_COMMITS=1 BONGO_SKIP_VERIFY_INSTALLED_VERSIONS=1 bongo preversion && yarn build && yarn test",
+    "preversion": "bongo preversion && yarn build && yarn test",
     "version": "yarn build && bongo version",
@@ -34,4 +34,4 @@ "postversion": "bongo postversion --skip-release-notification"
     "@applitools/monitoring-commons": "^1.0.19",
-    "@applitools/sdk-release-kit": "0.2.2",
-    "@applitools/sdk-shared": "0.1.0",
+    "@applitools/sdk-release-kit": "^0.3.3",
+    "@applitools/sdk-shared": "^0.1.1",
     "@babel/core": "^7.11.0",
@@ -71,5 +71,7 @@ "@babel/preset-env": "^7.8.3",
   "dependencies": {
+    "@applitools/dom-shared": "1.0.4",
     "@applitools/functional-commons": "1.6.0",
-    "css-tree": "^1.0.0-alpha.39"
+    "css-tree": "1.0.0-alpha.39",
+    "pako": "1.0.11"
   }
 }

README.md

@@ -17,16 +17,22 @@ # dom-snapshot
 
-- `getProcessPageScript`
-- `getProcessPageAndSerializeScript`
-- `getProcessPageAndPollScript`
-- `getProcessPageAndSerializeForIEScript`
-- `makeExtractResourcesFromSvg`
-- `toUriEncoding`
-- `toUnAnchoredUri`
+- `getProcessPage`
+- `getProcessPagePoll`
+- `getPollResult`
 
+The same 3 scripts are available in a transpiled version when running IE 11:
+- `getProcessPageForIE`
+- `getProcessPagePollForIE`
+- `getPollResultForIE`
+
+The following methods are deprecated:
+- `getProcessPageAndSerialize`
+- `getProcessPageAndSerializePoll`
+- `getProcessPageAndSerializeForIE`
+
 These async functions return 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:
 
 ```js
-  const {getProcessPageAndSerializeScript} = require('@applitools/dom-snapshot');
-  const processPageAndSerializeScript = await getProcessPageAndSerializeScript();
-  const returnValue = await page.evaluate(`(${processPageAndSerializeScript})()`); // puppeteer
+const {getProcessPage} = require('@applitools/dom-snapshot');
+const processPage = await getProcessPage();
+const returnValue = await page.evaluate(`(${processPage})()`); // puppeteer
 ```
@@ -39,3 +45,3 @@
 - `src/browser/processPage`
-- `src/browser/processPageAndSerialize`
+- `src/browser/processPageAndSerialize` (deprecated)
 
@@ -46,3 +52,3 @@ These functions can then be bundled together with other client-side code so they are consumed regardless of a browser driver (this is how the Eyes.Cypress SDK uses it).
 
-This package's `dist` folder contains scripts that can be sent to the browser regradless of driver and language. An agent that wishes to extract information from a webpage can read the contents of `dist/processPageAndSerialize` and send that to the browser as an async script. **There's still the need to wrap it in a way that invokes it**.
+This package's `dist` folder contains scripts that can be sent to the browser regradless of driver and language. An agent that wishes to extract information from a webpage can read the contents of `dist/processPage` and send that to the browser as an async script. **There's still the need to wrap it in a way that invokes it**.
 
@@ -52,5 +58,3 @@ For example in `Java` with Selenium WebDriver:
 ```java
-  String domCaptureScript = "var callback = arguments[arguments.length - 1]; return (" + PROCESS_RESOURCES + ")().then(JSON.stringify).then(callback, function(err) {callback(err.stack || err.toString())})";
-  
-  Object response = driver.executeAsyncScript("const callback = arguments[arguments.length - 1];(" + processPageAndSerialize + ")().then(JSON.stringify).then(callback, function(err) {callback(err.stack || err.toString())})";
+  String response = driver.executeAsyncScript("const callback = arguments[arguments.length - 1];(" + processPage + ")().then(JSON.stringify).then(callback, function(err) {callback(err.stack || err.toString())})";
 ```
@@ -62,2 +66,30 @@
 
+### Arguments
+
+One single argument with the following properties:
+
+```js
+processPage({
+  doc = document,
+  showLogs,
+  useSessionCache,
+  dontFetchResources,
+  fetchTimeout,
+  skipResources,
+  compressResources,
+  serializeResources,
+})
+```
+
+- `doc` - the document for which to take a snapshot. Default: the current document.
+- `showLogs` - toggle verbose logging in the console
+- `useSessionCache` - cache resources in the browser's `sessionCache`. Optimization for cases where `processPage` is run on the same browser tab more than once.
+- `dontFetchResources` - dont fetch resources. Only return `resourceUrls` and not `blobs`.
+- `fetchTimeout` - the time it takes to fail on a hanging fetch request for getting a resource. Default: 10000 (10 seconds)
+- `skipResources` - an array of absolute URL's of resources which shouldn't be fetched by `processPage`.
+- `compressResources` - a boolean indicating whether to use the `deflate` algorithm on blob data in order to return a smaller response. The caller should then `inflate` the blobs to get the value.
+- `serializeResources` - a boolean indicating whether to return blob data as base64 strings. This is useful in most cases since the `processPage` function is generally run from outside the browser, so its response should be serializable.
+
+### Return value
+
 This script receives a document, and returns an object with the following:
@@ -69,4 +101,46 @@
 - `blobs` - an array of objects with the following structure: `{url, type, value}`. These are resources that the browser was able to fetch. The `type` property is the `Content-Type` response header. The `value` property contains an ArrayBuffer with the content of the resource.
-- frames: an array with objects which recursively have the same structure as the `processPage` return value: `{url, cdt, resourceUrls, blobs, frames}`.
+- `frames`: an array with objects which recursively have the same structure as the `processPage` return value: `{url, cdt, resourceUrls, blobs, frames}`.
+- `srcAttr` - for frames, this is the original src attribute on the frame (in use by Selenium IDE Eyes extension)
+- `crossFramesSelectors` - an array of css selectors (strings) that point to cross origin frames. The caller can then call `processPage` in the context of those frames in order to build a complete DOM snapshot which also contains cross origin iframes.
+- `selector` - a css selector (string) for the frame (only for iframes). This is helpful to construct the full frame chain that leads to cross origin iframes on the caller side.
 
-The script scans the DOM for resource references, fetches them, and then also scans the body of css resources for more references, and so on recursively.
+The script scans the DOM for resource references, fetches them, and then also scans the body of css resources for more references, and so on recursively.
+
+## `processPagePoll`
+
+This function calls `processPage` 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 `processPage`, with one additional parameter:
+
+- `chunkByteSize` - 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:
+
+```
+procesPagePoll({chunkByteSize: 1024 * 1024 * 256})
+```
+
+### Return value
+
+The polling result is a stringified JSON object, which is of the following shape:
+
+```js
+{
+  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 `chunkByteSize`).
+
+## `pollResult`
+
+returns the poll result - an object with the same shape as `processPagePoll`.

No alert changes

Improved metrics

Total package byte prevSize

3121403

increased by95.38%

Number of package files

21

increased by50%

Lines of code

11969

increased by96.6%

Number of lines in readme file

140

increased by112.12%

Worsened metrics

Dependency count

4

increased by100%

Dependency changes

• + Added@applitools/dom-shared@1.0.4

• + Addedpako@1.0.11

• + Added@applitools/dom-shared@1.0.4(transitive)

• + Addedcss-tree@1.0.0-alpha.39(transitive)

• + Addedmdn-data@2.0.6(transitive)

• + Addedpako@1.0.11(transitive)

• - Removedcss-tree@1.1.3(transitive)

• - Removedmdn-data@2.0.14(transitive)

• Updatedcss-tree@1.0.0-alpha.39