@percy/core 1.0.0-beta.8 → 1.0.1

package/README.md

@@ -2,35 +2,71 @@
 
 The core component of Percy's CLI and SDKs that handles creating builds, discovering snapshot
 assets, uploading snapshots, and finalizing builds. Uses `@percy/client` for API communication, a
-Puppeteer browser for asset discovery, and starts a local API server for posting snapshots from
+Chromium browser for asset discovery, and starts a local API server for posting snapshots from
 other processes.
 
+- [Usage](#usage)
+  - [`#start()`](#start)
+  - [`#stop()`](#stopforce)
+  - [`#idle()`](#idle)
+  - [`#snapshot()`](#snapshotoptions)
+- [Advanced](#advanced)
+  - [Download discovery browser on install](#download-discovery-browser-on-install)
+  - [Skipping discovery browser download](#skipping-discovery-browser-download)
+
 ## 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.
 
 ``` js
 import Percy from '@percy/core'
 
-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
-    disableAssetCache: 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
+- `deferUploads` — Defer creating a build and uploading snapshots until later
+- `skipUploads` — Skip creating a build and uploading snapshots altogether
+
+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`)
+- `discovery` — Asset discovery options
+  - `allowedHostnames` — Array of allowed hostnames to capture assets from
+  - `disallowedHostnames` — Array of hostnames where requests will be aborted
+  - `requestHeaders` — Request headers used when discovering snapshot assets
+  - `authorization` — Basic auth `username` and `password` for protected snapshot assets
+  - `disableCache` — Disable asset caching (**default** `false`)
+  - `userAgent` — Custom user-agent string used when requesting assets
+  - `cookies` — Browser cookies to use when requesting assets
+  - `networkIdleTimeout` — Milliseconds to wait for the network to idle (**default** `100`)
+  - `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()`
 
 Starting a `Percy` instance will start a local API server, start the asset discovery browser, and
@@ -39,81 +75,204 @@ create a new Percy build. If an asset discovery browser is not found, one will b
 ``` js
 await percy.start()
 // [percy] Percy has started!
-// [percy] Created build #1: https://percy.io/org/project/123
 ```
 
 #### API Server
 
 Starting a `Percy` instance will start a local API server unless `server` is `false`. The server can
-be found at `http://localhost:5338/` or at the provided `port` number. All POST requests accept a
-JSON body with the `application/json` content-type.
+be found at `http://localhost:5338/` or at the provided `port` number.
 
 - GET `/percy/healthcheck` – Responds with information about the running instance
 - GET `/percy/dom.js` – Responds with the [`@percy/dom`](./packages/dom) library
+- GET `/percy/idle` - Responds when the running instance is [idle](#idle)
 - POST `/percy/snapshot` – Calls [`#snapshot()`](#snapshotoptions) with provided snapshot options
-- POST `/percy/stop` - Remotely [stops](#stop) the running `Percy` instance
+- POST `/percy/stop` - Remotely [stops](#stopforce) the running `Percy` instance
+
+### `#stop([force])`
+
+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. When uploads are deferred,
+stopping the instance will also trigger processing of the upload queue. When `force` is `true`,
+queues are cleared and closed to prevent queued snapshots from running.
+
+``` js
+await percy.stop()
+// [percy] Processing 3 snapshots...
+// [percy] Snapshot taken: Snapshot one
+// [percy] Snapshot taken: Snapshot two
+// [percy] Snapshot taken: Snapshot three
+// [percy] Uploading 3 snapshots...
+// [percy] Finalized build #1: https://percy.io/org/project/123
+
+await percy.stop(true)
+// [percy] Stopping percy...
+// [percy] Finalized build #1: https://percy.io/org/project/123
+```
+
+### `#idle()`
+
+This method will resolve shortly after pending snapshots and uploads have completed and no more have
+started. Queued tasks are not considered pending unless they are actively running, so deferred
+uploads will not be awaited on with this method.
+
+``` js
+percy.snapshot(...);
+percy.snapshot(...);
+percy.snapshot(...);
+
+await percy.idle()
+// [percy] Snapshot taken: ...
+// [percy] Snapshot taken: ...
+// [percy] Snapshot taken: ...
+```
 
 ### `#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.
+Takes one or more snapshots of a page while discovering resources to upload with the snapshot. Once
+asset discovery has completed, the queued snapshot will resolve and an upload task will be queued
+separately. Accepts several different syntaxes for taking snapshots in various ways.
+
+All available syntaxes will push snapshots into the snapshot queue without the need to await on the
+method directly. This method resolves after the snapshot upload is queued, but does not await on the
+upload to complete.
 
 ``` js
 // snapshots can be handled concurrently, no need to await
 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
-  clientInfo: '',                // user-agent client info for the SDK
-  environmentInfo: ''            // user-agent environment info for the SDK
+  name: 'Snapshot 1',
+  url: 'http://localhost:3000',
+  domSnapshot: domSnapshot,
+  clientInfo: 'my-sdk',
+  environmentInfo: 'my-lib'
+})
+
+// without a domSnapshot, capture options will be used to take one
+percy.snapshot({
+  name: 'Snapshot 2',
+  url: 'http://localhost:3000',
+  waitForTimeout: 1000,
+  waitForSelector: '.done-loading',
+  execute: async () => {},
+  additionalSnapshots: [{
+    name: 'Snapshot 2.1',
+    execute: () => {}
+  }]
 })
-```
 
-### `#capture(options)`
+// alternate shorthand syntax 
+percy.snapshot({
+  baseUrl: 'http://localhost:3000',
+  snapshots: ['/', '/about', '/contact'],
+  options: {
+    widths: [600, 1200]
+  }
+})
 
-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`.
+// gather snapshots from an external sitemap
+percy.snapshot({
+  sitemap: 'https://example.com/sitemap.xml',
+  exclude: ['/blog/*']
+})
 
-``` js
-// pages can be captured concurrently, no need to await
-percy.capture({
-  name: 'My Snapshot',            // snapshot name
-  url: 'http://localhost:3000/',  // required page URL
-  waitFor: selectorOrTimeout,     // selector or timeout to wait for before snapshotting
-  execute: async (page) => {},    // async page function to execute before snapshotting
-  snapshots: [{                   // additional snapshots to take on this page
-    name: 'Second Snapshot',        // additional snapshot name
-    execute: async (page) => {},    // additional snapshot page function
-    ...options                      // ...additional snapshot options
-  }],
-  ...options                      // ...other snapshot options
+// start a server and take static snapshots
+percy.snapshot({
+  serve: './public',
+  cleanUrls: true,
 })
 ```
 
-### `#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.
+When capturing a single snapshot, the snapshot URL may be provided as the only argument rather than
+a snapshot options object. When providing an options object, a few alternate syntaxes are available
+depending on the provided properties ([see alternate syntaxes below](#alternate-syntaxes)).
 
-``` 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 options** accepted for each snapshot:
+
+- `url` — Snapshot URL (**required**)
+- `name` — Snapshot name
+- `domSnapshot` — Snapshot DOM string
+- `discovery` - Limited snapshot specific discovery options
+  - `allowedHostnames`, `disallowedHostnames`, `requestHeaders`, `authorization`, `disableCache`, `userAgent`
+
+Common snapshot options are also accepted and will override instance snapshot options. [See instance
+options](#options) for common snapshot and discovery options.
+
+**Capture options** can only be provided when `domSnapshot` is missing:
+
+- `waitForTimeout` — Milliseconds to wait before taking a snapshot
+- `waitForSelector` — CSS selector to wait for before taking a snapshot
+- `execute` — Function or function body to execute within the page before taking a snapshot
+- `additionalSnapshots` — Array of additional sequential snapshots to take of the page
+  - `name` — Snapshot name (**required** if no `prefix` or `suffix`)
+  - `prefix` — Snapshot name prefix (**required** if no `name` or `suffix`)
+  - `suffix` — Snapshot name suffix (**required** if no `name` or `prefix`)
+  - `waitForTimeout`, `waitForSelector`, `execute` — See above
+  
+#### Alternate syntaxes
+
+All snapshot syntaxes can be provided as items within an array. For example, a single method call
+can upload multiple DOM snapshots, capture multiple external snapshots, crawl a sitemap for
+snapshots, and host a local static server for snapshots.
+
+**Shared options** accepted by all syntaxes:
+
+- `clientInfo` — Client info to include with the build
+- `environmentInfo` — Environment info to include with the build
+
+The following alternate syntaxes may **not** be combined with snapshot options, but rather offer
+alternate methods for taking multiple snapshots.
+
+**List options** can only be provided when a top-level `snapshots` is present:
+
+- `snapshots` — An array of snapshot URLs or snapshot options (**required**)
+- `baseUrl` — The full base URL (including protocol) used when snapshot URLs only include a pathname
+- `include`/`exclude` — Include and exclude matching snapshot names
+- `options` — Additional options to apply to snapshots
+  - `include`/`exclude` — Include and exclude snapshots to apply these options to
+  -  [Common snapshot and capture options](#options) (**excluding** `url`, `domSnapshot`)
+  
+**Sitemap options** can only be provided when a top-level `sitemap` is present:
+
+- `sitemap` — The URL where an XML sitemap can be located (**required**)
+- `include`/`exclude` — Include and exclude matching snapshot names
+- `options` — Additional options to apply to snapshots
+  - `include`/`exclude` — Include and exclude snapshots to apply these options to
+  -  [Common snapshot and capture options](#options) (**excluding** `url`, `domSnapshot`)
+  
+**Server options** can only be provided when a top-level `serve` is present:
+
+- `serve` — The static directory to serve relative to the current working directory (**required**)
+- `baseUrl` — The base URL to serve the directory at, starting with a forward slash (/)
+- `cleanUrls` — Set to `true` to strip `.html` and `index.html` from served URLs
+- `rewrites` — A source-destination map for rewriting source URLs into destination pathnames
+- `snapshots` — An array of specific snapshots to take while serving the static directory
+- `include`/`exclude` — Include and exclude matching snapshot names
+- `options` — Additional options to apply to snapshots
+  - `include`/`exclude` — Include and exclude snapshots to apply these options to
+  -  [Common snapshot and capture options](#options) (**excluding** `url`, `domSnapshot`)
 
 ## Advanced
 
-### Puppeteer Executable Path
+### Download discovery browser on install
+
+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.
+
+### Skipping discovery browser download
 
-To avoid downloading the browser used for asset discovery, the local browser executable can be
-defined with an `executablePath` option provided within `discovery.launchOptions`. This options
-falls back to the `PUPPETEER_EXECUTABLE_PATH` environment variable if defined.
+If your CI comes with a Chromium binary pre-installed and you wish to skip Percy's own browser
+installation, you can set the respective `discovery.launchOptions.executable` config option. When
+the executable at the provided path exists, the default download will be skipped and the provided
+binary will be used instead. This option can also be set using the `PERCY_BROWSER_EXECUTABLE`
+environment variable.
 
+> **Warning!** Percy is only tested against the browser it downloads automatically. When providing a
+> custom browser executable, you may experience unexpected issues.

package/dist/api.js

@@ -0,0 +1,94 @@
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import logger from '@percy/logger';
+import { getPackageJSON } from './utils.js';
+import Server from './server.js'; // need require.resolve until import.meta.resolve can be transpiled
+
+export const PERCY_DOM = createRequire(import.meta.url).resolve('@percy/dom'); // Create a Percy CLI API server instance
+
+export function createPercyServer(percy, port) {
+  let pkg = getPackageJSON(import.meta.url);
+  return new Server({
+    port
+  }) // facilitate logger websocket connections
+  .websocket(ws => logger.connect(ws)) // general middleware
+  .route((req, res, next) => {
+    // treat all request bodies as json
+    if (req.body) try {
+      req.body = JSON.parse(req.body);
+    } catch {} // add version header
+
+    res.setHeader('Access-Control-Expose-Headers', '*, X-Percy-Core-Version');
+    res.setHeader('X-Percy-Core-Version', pkg.version); // return json errors
+
+    return next().catch(e => res.json(e.status ?? 500, {
+      build: percy.build,
+      error: e.message,
+      success: false
+    }));
+  }) // healthcheck returns basic information
+  .route('get', '/percy/healthcheck', (req, res) => res.json(200, {
+    loglevel: percy.loglevel(),
+    config: percy.config,
+    build: percy.build,
+    success: true
+  })) // get or set config options
+  .route(['get', 'post'], '/percy/config', async (req, res) => res.json(200, {
+    config: req.body ? await percy.setConfig(req.body) : percy.config,
+    success: true
+  })) // responds once idle (may take a long time)
+  .route('get', '/percy/idle', async (req, res) => res.json(200, {
+    success: await percy.idle().then(() => true)
+  })) // convenient @percy/dom bundle
+  .route('get', '/percy/dom.js', (req, res) => {
+    return res.file(200, PERCY_DOM);
+  }) // legacy agent wrapper for @percy/dom
+  .route('get', '/percy-agent.js', async (req, res) => {
+    logger('core:server').deprecated(['It looks like you’re using @percy/cli with an older SDK.', 'Please upgrade to the latest version to fix this warning.', 'See these docs for more info: https:docs.percy.io/docs/migrating-to-percy-cli'].join(' '));
+    let content = await fs.promises.readFile(PERCY_DOM, 'utf-8');
+    let wrapper = '(window.PercyAgent = class { snapshot(n, o) { return PercyDOM.serialize(o); } });';
+    return res.send(200, 'applicaton/javascript', content.concat(wrapper));
+  }) // post one or more snapshots
+  .route('post', '/percy/snapshot', async (req, res) => {
+    let snapshot = percy.snapshot(req.body);
+    if (!req.url.searchParams.has('async')) await snapshot;
+    return res.json(200, {
+      success: true
+    });
+  }) // stops percy at the end of the current event loop
+  .route('/percy/stop', (req, res) => {
+    setImmediate(() => percy.stop());
+    return res.json(200, {
+      success: true
+    });
+  });
+} // Create a static server instance with an automatic sitemap
+
+export function createStaticServer(options) {
+  let {
+    serve,
+    port,
+    baseUrl = '/',
+    ...opts
+  } = options;
+  let server = new Server({
+    port
+  }).serve(baseUrl, serve, opts); // used when generating an automatic sitemap
+
+  let toURL = Server.createRewriter( // reverse rewrites' src, dest, & order
+  Object.entries((options === null || options === void 0 ? void 0 : options.rewrites) ?? {}).reduce((acc, rw) => [rw.reverse(), ...acc], []), (filename, rewrite) => new URL(path.posix.join(baseUrl, // cleanUrls will trim trailing .html/index.html from paths
+  !options.cleanUrls ? rewrite(filename) : rewrite(filename).replace(/(\/index)?\.html$/, '')), server.address())); // include automatic sitemap route
+
+  server.route('get', '/sitemap.xml', async (req, res) => {
+    let {
+      default: glob
+    } = await import('fast-glob');
+    let files = await glob('**/*.html', {
+      cwd: serve,
+      fs
+    });
+    return res.send(200, 'application/xml', ['<?xml version="1.0" encoding="UTF-8"?>', '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">', ...files.map(name => `  <url><loc>${toURL(name)}</loc></url>`), '</urlset>'].join('\n'));
+  });
+  return server;
+}