@percy/core - npm Package Compare versions

Comparing version 1.0.0-beta.39 to 1.0.0-beta.40

dist/config.js

@@ -81,4 +81,4 @@ "use strict";
           },
-          headless: {
-            type: 'boolean'
+          timeout: {
+            type: 'integer'
           },
@@ -91,4 +91,4 @@ args: {
           },
-          timeout: {
-            type: 'integer'
+          headless: {
+            type: 'boolean'
           }
@@ -95,0 +95,0 @@ }

dist/discovery/browser.js

@@ -65,4 +65,4 @@ "use strict";
     executable = process.env.PERCY_BROWSER_EXECUTABLE,
+    args: uargs = [],
     headless = true,
-    args: uargs = [],
     timeout
@@ -69,0 +69,0 @@ } = {}) {

dist/discovery/page.js

@@ -110,3 +110,5 @@ "use strict";
       this.closedReason = 'Page crashed!';
-      this.close();
+      /* istanbul ignore next: racey with browser close */
+
+      this.close().catch(error => this.log.debug(error));
     });
@@ -113,0 +115,0 @@

package.json

 {
   "name": "@percy/core",
-  "version": "1.0.0-beta.39",
+  "version": "1.0.0-beta.40",
   "license": "MIT",
@@ -17,7 +17,7 @@ "main": "dist/index.js",
   "scripts": {
-    "build": "cross-env NODE_ENV=production babel src --out-dir dist --root-mode upward",
+    "build": "node ../../scripts/build",
     "lint": "eslint --ignore-path ../../.gitignore .",
     "postinstall": "node ./post-install",
-    "test": "cross-env NODE_ENV=test mocha",
-    "test:coverage": "nyc yarn test",
+    "test": "node ../../scripts/test",
+    "test:coverage": "yarn test --coverage",
     "test:types": "tsd"
@@ -28,12 +28,7 @@ },
   },
-  "mocha": {
-    "require": "../../scripts/babel-register",
-    "recursive": true,
-    "timeout": 10000
-  },
   "dependencies": {
-    "@percy/client": "^1.0.0-beta.39",
-    "@percy/config": "^1.0.0-beta.39",
-    "@percy/dom": "^1.0.0-beta.39",
-    "@percy/logger": "^1.0.0-beta.39",
+    "@percy/client": "^1.0.0-beta.40",
+    "@percy/config": "^1.0.0-beta.40",
+    "@percy/dom": "^1.0.0-beta.40",
+    "@percy/logger": "^1.0.0-beta.40",
     "cross-spawn": "^7.0.3",
@@ -45,3 +40,3 @@ "extract-zip": "^2.0.1",
   },
-  "gitHead": "bd5cea12ca0d21ca167ce9100df2ead274428b7e"
+  "gitHead": "1607ab0f5dbe5ab8ef3c9f7b6c2a89f66533348c"
 }

README.md

@@ -8,6 +8,14 @@ # @percy/core
 
+- [Usage](#usage)
+  - [`#start()`](#start)
+  - [`#stop()`](#stop)
+  - [`#snapshot()`](#snapshotoptions)
+  - [`#capture()`](#captureoptions)
+- [Advanced](#advanced)
+  - [Download discovery browser on install](#download-discovery-browser-on-install)
+
 ## Usage
 
-The `Percy` class will manage a Percy build and perform asset discovery on snapshots before
-uploading them to Percy. It also hosts a local API server for Percy SDKs to communicate with.
+A `Percy` class instance can manage a Percy build, take page snapshots, and perform snapshot asset
+discovery. It also hosts a local API server for Percy SDKs to communicate with.
 
@@ -17,20 +25,43 @@ ``` js
 
-const percy = new Percy({
-  token: PERCY_TOKEN,        // defaults to PERCY_TOKEN environment variable
-  loglevel: 'info',          // what level logs to write to console
-  server: true,              // start a local API server
-  port: 5338,                // port to start the API server at
-  concurrency: 5,            // concurrency of the #capture() method
-  snapshot: {},              // global snapshot options (see snapshots section)
-  discovery: {               // asset discovery options
-    allowedHostnames: [],      // list of hostnames allowed to capture from
-    networkIdleTimeout: 100,   // how long before network is considered idle
-    disableCache: false,  // disable discovered asset caching
-    concurrency: 5,            // asset discovery concurrency
-    launchOptions: {}          // browser launch options
-  },
-  ...config                  // additional config options accessible by SDKs
-})
+// create a new instance
+const percy = new Percy(percyOptions)
+
+// create a new instance and start it
+const percy = await Percy.start(percyOptions)
 ```
 
+#### Options
+
+- `token` — Your project's `PERCY_TOKEN` (**default** `process.env.PERCY_TOKEN`)
+- `loglevel` — Logger level, one of `"info"`, `"warn"`, `"error"`, `"debug"` (**default** `"info"`)
+- `server` — Controls whether an API server is created (**default** `true`)
+- `port` — API server port (**default** `5338`)
+- `clientInfo` — Client info sent to Percy via a user-agent string
+- `environmentInfo` — Environment info also sent with the user-agent string
+- `concurrency` — Page [`#capture()`](#captureoptions) concurrency (**default** `5`)
+
+The following options can also be defined within a Percy config file
+
+- `snapshot` — Snapshot options applied to each snapshot
+  - `widths` — Widths to take screenshots at (**default** `[375, 1280]`)
+  - `minHeight` — Minimum screenshot height (**default** `1024`)
+  - `percyCSS` — Percy specific CSS to inject into the snapshot
+  - `enableJavaScript` — Enable JavaScript for screenshots (**default** `false`)
+  - `requestHeaders` — Request headers used when discovering snapshot assets
+  - `authorization` — Basic auth `username` and `password` for protected snapshot assets
+- `discovery` — Asset discovery options
+  - `allowedHostnames` — Array of allowed hostnames to capture assets from
+  - `networkIdleTimeout` — Milliseconds to wait for the network to idle (**default** `100`)
+  - `disableCache` — Disable asset caching (**default** `false`)
+  - `concurrency` — Asset discovery concerrency (**default** `5`)
+  - `launchOptions` — Asset discovery browser launch options
+    - `executable` — Browser executable path (**default** `process.env.PERCY_BROWSER_EXECUTABLE`)
+    - `timeout` — Discovery launch timeout, in milliseconds (**default** `30000`)
+    - `args` — Additional browser process arguments
+    - `headless` — Runs the browser headlessy (**default** `true`)
+    
+Additional Percy config file options are also allowed and will override any options defined by a
+local config file. These config file options are also made available to SDKs via the local API
+health check endpoint.
+
 ### `#start()`
@@ -57,6 +88,20 @@
 
+### `#stop()`
+
+Stopping a `Percy` instance will wait for any pending snapshots, close the asset discovery browser,
+close the local API server, and finalize the current Percy build.
+
+``` js
+await percy.stop()
+// [percy] Stopping percy...
+// [percy] Waiting for 1 snapshot(s) to complete
+// [percy] Snapshot taken: My Snapshot
+// [percy] Finalized build #1: https://percy.io/org/project/123
+// [percy] Done
+```
+
 ### `#snapshot(options)`
 
-Performs asset discovery for the provided DOM snapshot at widths specified here or in the instance's
-provided `snapshot` option. This is the primary method used by Percy SDKs to upload snapshots.
+Performs asset discovery for the provided DOM snapshot. This is the primary method used by Percy
+SDKs to upload snapshots to the associated Percy build.
 
@@ -66,20 +111,27 @@ ``` js
 percy.snapshot({
-  name: 'My Snapshot',           // required name
-  url: 'http://localhost:3000',  // required url
-  domSnapshot: domSnapshot,      // required DOM string
-  widths: [500, 1280],           // widths to discover resources
-  minHeight: 1024,               // minimum height used when screenshotting
-  percyCSS: '',                  // percy specific css to inject
-  requestHeaders: {},            // asset request headers such as authorization
-  authorization: {},             // asset authorization credentials
-  clientInfo: '',                // user-agent client info for the SDK
-  environmentInfo: ''            // user-agent environment info for the SDK
+  name: 'My Snapshot',
+  url: 'http://localhost:3000',
+  domSnapshot: domSnapshot,
+  clientInfo: 'my-sdk',
+  environmentInfo: 'my-lib'
+  ...snapshotOptions
 })
 ```
 
+#### Options
+
+- `name` — Snapshot name (**required**)
+- `url` — Snapshot URL (**required**)
+- `domSnapshot` — Snapshot DOM string (**required**)
+- `clientInfo` — Additional client info
+- `environmentInfo` — Additional environment info
+
+Common snapshot options are also accepted and will override instance snapshot options. [See intance
+options](#options)
+
 ### `#capture(options)`
 
-Navigates to a URL and captures a snapshot or multiple snapshots of a page after optionally
-interacting with the page. Any [`#snapshot()`](#snapshotoptions) options can also be provided, with
-the exception of `domSnapshot`.
+Navigates to a URL and captures one or more snapshots of a page. Before the snapshot is captured,
+the page can be waited on and interacted with via various options. The resulting snapshot is then
+uploaded using the [`#snapshot()`](#snapshotoptions) method.
 
@@ -89,38 +141,45 @@ ``` js
 percy.capture({
-  name: 'My Snapshot',            // snapshot name
-  url: 'http://localhost:3000/',  // required page URL
-  waitForTimeout: 1000,           // timeout to wait before snapshotting
-  waitForSelector: '.selector',   // selector to wait for before snapshotting
-  execute: async () => {},        // function to execute within the page context
-  snapshots: [{                   // additional snapshots to take on this page
-    name: 'Second Snapshot',        // additional snapshot name
-    execute: async () => {},        // additional snapshot execute function
-    ...options                      // ...additional snapshot options
+  name: 'My Snapshot',
+  url: 'http://localhost:3000/',
+  waitForTimeout: 1000,
+  waitForSelector: '.done-loading',
+  execute: async () => {},
+  snapshots: [{
+    name: 'Second Snapshot',
+    execute: async () => {},
+    ...snapshotOptions
   }],
-  ...options                      // ...other snapshot options
+  ...snapshotOptions
 })
 ```
 
-### `#stop()`
+#### Options
 
-Stopping a `Percy` instance will wait for any pending snapshots, close the asset discovery browser,
-close the local API server, and finalize the current Percy build.
+- `name` — Snapshot name (**required** for single snapshots)
+- `url` — Snapshot URL (**required**)
+- `waitForTimeout` — Milliseconds to wait before snapshotting
+- `waitForSelector` — CSS selector to wait for before snapshotting
+- `execute` — Function or function body to execute within the page
+- `clientInfo` — Additional client info
+- `environmentInfo` — Additional environment info
+- `snapshots` — Array of additional sequential snapshots to take
+  - `name` — Snapshot name (**required**)
+  - `execute` — Function or function body to execute
 
-``` js
-await percy.stop()
-// [percy] Stopping percy...
-// [percy] Waiting for 1 snapshot(s) to complete
-// [percy] Snapshot taken: My Snapshot
-// [percy] Finalized build #1: https://percy.io/org/project/123
-// [percy] Done
-```
+Common snapshot options are also accepted and will override instance snapshot options. [See intance
+options](#options)
 
 ## Advanced
 
-### Chromium Executable Path
+### Download discovery browser on install
 
-**Use with caution as asset discovery may not work with some versions of Chromium.** To avoid
-downloading the browser used for asset discovery, the local browser executable can be defined with
-an `executable` option provided within `discovery.launchOptions`. This option should be a path to
-Chromium's binary executable and falls back to downloading a compatible browser when not found.
+By default, the browser is only downloaded when asset discovery is started for the first time. This
+is because many features of the CLI do not require a browser at all, and automatically downloading a
+browser creates a much heavier footprint than needed for those features. However, if your CI caches
+dependencies after the install step, the browser will not be cached and will be downloaded every
+time Percy runs without it.
 
+If the environment variable `PERCY_POSTINSTALL_BROWSER` is present and truthy, then the browser will
+be downloaded after the package is installed to allow it to be cached. You can also require
+`@percy/core/post-install` within another node module to trigger the browser download manually.
+

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

96381

increased by2.09%

Lines of code

2078

increased by0.05%

Number of lines in readme file

181

increased by48.36%

Dependency changes

• Updated@percy/client@^1.0.0-beta.40

• Updated@percy/config@^1.0.0-beta.40

• Updated@percy/dom@^1.0.0-beta.40

• Updated@percy/logger@^1.0.0-beta.40