@percy/core 1.10.3 → 1.11.0

package/dist/percy.js

@@ -1,20 +1,19 @@
 import PercyClient from '@percy/client';
 import PercyConfig from '@percy/config';
 import logger from '@percy/logger';
-import Queue from './queue.js';
 import Browser from './browser.js';
 import { createPercyServer, createStaticServer } from './api.js';
-import { gatherSnapshots, validateSnapshotOptions, discoverSnapshotResources } from './snapshot.js';
-import { generatePromise, yieldAll } from './utils.js'; // A Percy instance will create a new build when started, handle snapshot
-// creation, asset discovery, and resource uploads, and will finalize the build
-// when stopped. Snapshots are processed concurrently and the build is not
-// finalized until all snapshots have been handled.
+import { gatherSnapshots, createSnapshotsQueue, validateSnapshotOptions } from './snapshot.js';
+import { discoverSnapshotResources, createDiscoveryQueue } from './discovery.js';
+import { generatePromise, yieldAll, yieldTo } from './utils.js'; // A Percy instance will create a new build when started, handle snapshot creation, asset discovery,
+// and resource uploads, and will finalize the build when stopped. Snapshots are processed
+// concurrently and the build is not finalized until all snapshots have been handled.
 
 export class Percy {
   log = logger('core');
   readyState = null;
-  #uploads = new Queue();
-  #snapshots = new Queue(); // Static shortcut to create and start an instance in one call
+  #discovery = null;
+  #snapshots = null; // Static shortcut to create and start an instance in one call
 
   static async start(options) {
     let instance = new this(options);
@@ -38,7 +37,7 @@ export class Percy {
     // implies `dryRun`, silent logs, and adds extra api endpoints
     testing,
     // configuration filepath
-    config,
+    config: configFile,
     // provided to @percy/client
     token,
     clientInfo = '',
@@ -50,6 +49,15 @@ export class Percy {
     // options which will become accessible via the `.config` property
     ...options
   } = {}) {
+    let {
+      percy,
+      ...config
+    } = PercyConfig.load({
+      overrides: options,
+      path: configFile
+    });
+    deferUploads ?? (deferUploads = percy === null || percy === void 0 ? void 0 : percy.deferUploads);
+    this.config = config;
     if (testing) loglevel = 'silent';
     if (loglevel) this.loglevel(loglevel);
     this.testing = testing ? {} : null;
@@ -57,30 +65,18 @@ export class Percy {
     this.skipUploads = this.dryRun || !!skipUploads;
     this.skipDiscovery = this.dryRun || !!skipDiscovery;
     this.delayUploads = this.skipUploads || !!delayUploads;
-    this.deferUploads = this.delayUploads || !!deferUploads;
-    if (this.deferUploads) this.#uploads.stop();
-    this.config = PercyConfig.load({
-      overrides: options,
-      path: config
-    });
-
-    if (this.config.discovery.concurrency) {
-      let {
-        concurrency
-      } = this.config.discovery;
-      this.#uploads.concurrency = concurrency;
-      this.#snapshots.concurrency = concurrency;
-    }
-
+    this.deferUploads = this.skipUploads || !!deferUploads;
     this.client = new PercyClient({
       token,
       clientInfo,
       environmentInfo
     });
     if (server) this.server = createPercyServer(this, port);
-    this.browser = new Browser(this); // generator methods are wrapped to autorun and return promises
+    this.browser = new Browser(this);
+    this.#discovery = createDiscoveryQueue(this);
+    this.#snapshots = createSnapshotsQueue(this); // generator methods are wrapped to autorun and return promises
 
-    for (let m of ['start', 'stop', 'flush', 'idle', 'snapshot']) {
+    for (let m of ['start', 'stop', 'flush', 'idle', 'snapshot', 'upload']) {
       // the original generator can be referenced with percy.yield.<method>
       let method = (this.yield || (this.yield = {}))[m] = this[m].bind(this);
 
@@ -101,7 +97,7 @@ export class Percy {
   } // Set client & environment info, and override loaded config options
 
 
-  setConfig({
+  set({
     clientInfo,
     environmentInfo,
     ...config
@@ -126,96 +122,45 @@ export class Percy {
     this.config = PercyConfig.merge([this.config, config], (path, prev, next) => {
       // replace arrays instead of merging
       return Array.isArray(next) && [path, next];
-    }); // adjust concurrency if necessary
-
-    if (this.config.discovery.concurrency) {
-      let {
-        concurrency
-      } = this.config.discovery;
-      this.#uploads.concurrency = concurrency;
-      this.#snapshots.concurrency = concurrency;
-    }
+    }); // adjust queue concurrency
 
+    let {
+      concurrency
+    } = this.config.discovery;
+    this.#discovery.set({
+      concurrency
+    });
+    this.#snapshots.set({
+      concurrency
+    });
     return this.config;
-  } // Resolves once snapshot and upload queues are idle
-
-
-  async *idle() {
-    yield* this.#snapshots.idle();
-    yield* this.#uploads.idle();
-  } // Immediately stops all queues, preventing any more tasks from running
-
-
-  close() {
-    this.#snapshots.close(true);
-    this.#uploads.close(true);
-  } // Starts a local API server, a browser process, and queues creating a new Percy build which will run
-  // at a later time when uploads are deferred, or run immediately when not deferred.
+  } // Starts a local API server, a browser process, and internal queues.
 
 
   async *start() {
     // already starting or started
     if (this.readyState != null) return;
-    this.readyState = 0; // create a percy build as the first immediately queued task
-
-    let buildTask = this.#uploads.push('build/create', () => {
-      // pause other queued tasks until after the build is created
-      this.#uploads.stop();
-      this.build = {};
-      return this.client.createBuild().then(({
-        data: {
-          id,
-          attributes
-        }
-      }) => {
-        let url = attributes['web-url'];
-        let number = attributes['build-number'];
-        Object.assign(this.build, {
-          id,
-          url,
-          number
-        });
-        if (!this.delayUploads) this.#uploads.run();
-      });
-    }, 0); // handle deferred build errors
-
-    if (this.deferUploads) {
-      buildTask.catch(err => {
-        this.build = {
-          error: 'Failed to create build'
-        };
-        this.log.error(this.build.error);
-        this.log.error(err);
-        this.close();
-      });
-    }
+    this.readyState = 0;
 
     try {
-      var _this$server2;
-
-      // when not deferred, wait until the build is created first
-      if (!this.deferUploads) await buildTask; // maybe launch the discovery browser
+      // start the snapshots queue immediately when not delayed or deferred
+      if (!this.delayUploads && !this.deferUploads) yield this.#snapshots.start(); // do not start the discovery queue when not needed
 
-      if (!this.skipDiscovery) yield this.browser.launch(); // start the server after everything else is ready
+      if (!this.skipDiscovery) yield this.#discovery.start(); // start a local API server for SDK communication
 
-      yield (_this$server2 = this.server) === null || _this$server2 === void 0 ? void 0 : _this$server2.listen(); // mark instance as started
+      if (this.server) yield this.server.listen(); // log and mark this instance as started
 
       this.log.info('Percy has started!');
       this.readyState = 1;
     } catch (error) {
-      var _this$server3;
-
-      // on error, close any running server and browser
-      await ((_this$server3 = this.server) === null || _this$server3 === void 0 ? void 0 : _this$server3.close());
-      await this.browser.close(); // mark instance as closed
-
-      this.readyState = 3; // when uploads are deferred, cancel build creation on abort
+      var _this$server2;
 
-      if (this.deferUploads && error.name === 'AbortError') {
-        this.#uploads.cancel('build/create');
-        this.readyState = null;
-      } // throw an easier-to-understand error when the port is taken
+      // on error, close any running server and end queues
+      await ((_this$server2 = this.server) === null || _this$server2 === void 0 ? void 0 : _this$server2.close());
+      await this.#discovery.end();
+      await this.#snapshots.end(); // mark this instance as closed unless aborting
 
+      this.readyState = error.name !== 'AbortError' ? 3 : null; // throw an easier-to-understand error when the port is in use
 
       if (error.code === 'EADDRINUSE') {
         throw new Error('Percy is already running or the port is in use');
@@ -223,53 +168,36 @@ export class Percy {
         throw error;
       }
     }
-  } // Wait for currently queued snapshots then run and wait for resulting uploads
+  } // Resolves once snapshot and upload queues are idle
 
 
-  async *flush(close) {
-    try {
-      // wait until the next event loop for synchronous snapshots
-      yield new Promise(r => setImmediate(r)); // close the snapshot queue and wait for it to empty
-
-      if (this.#snapshots.size) {
-        if (close) this.#snapshots.close();
-        yield* this.#snapshots.flush(s => {
-          // do not log a count when not closing or if asset discovery is disabled
-          if (!close || this.skipDiscovery) return;
-          this.log.progress(`Processing ${s} snapshot${s !== 1 ? 's' : ''}...`, !!s);
-        });
-      } // run, close, and wait for the upload queue to empty
+  async *idle() {
+    yield* this.#discovery.idle();
+    yield* this.#snapshots.idle();
+  } // Wait for currently queued snapshots then run and wait for resulting uploads
 
 
-      if (!this.skipUploads && this.#uploads.size) {
-        if (close) this.#uploads.close(); // prevent creating an empty build when deferred
+  async *flush(options) {
+    if (!this.readyState || this.readyState > 2) return;
+    let callback = typeof options === 'function' ? options : null;
+    options && (options = !callback ? [].concat(options) : null); // wait until the next event loop for synchronous snapshots
 
-        if (!this.deferUploads || !this.#uploads.has('build/create') || this.#uploads.size > 1) {
-          if (this.build && !this.build.id) yield* this.#uploads.idle();
-          yield* this.#uploads.flush(s => {
-            // do not log a count when not closing or while creating a build
-            if (!close || this.#uploads.has('build/create')) return;
-            this.log.progress(`Uploading ${s} snapshot${s !== 1 ? 's' : ''}...`, !!s);
-          });
-        }
-      }
-    } catch (error) {
-      // reopen closed queues when aborted
+    yield new Promise(r => setImmediate(r)); // flush and log progress for discovery before snapshots
 
-      /* istanbul ignore else: all errors bubble */
-      if (close && error.name === 'AbortError') {
-        this.#snapshots.open();
-        this.#uploads.open();
-      }
+    if (!this.skipDiscovery && this.#discovery.size) {
+      if (options) yield* yieldAll(options.map(o => this.#discovery.process(o)));else yield* this.#discovery.flush(size => callback === null || callback === void 0 ? void 0 : callback('Processing', size));
+    } // flush and log progress for snapshot uploads
 
-      throw error;
+
+    if (!this.skipUploads && this.#snapshots.size) {
+      if (options) yield* yieldAll(options.map(o => this.#snapshots.process(o)));else yield* this.#snapshots.flush(size => callback === null || callback === void 0 ? void 0 : callback('Uploading', size));
     }
-  } // Stops the local API server and browser once snapshots have completed and finalizes the Percy
-  // build. Does nothing if not running. When `force` is true, any queued tasks are cleared.
+  } // Stops the local API server and closes the browser and internal queues once snapshots have
+  // completed. Does nothing if not running. When `force` is true, any queued snapshots are cleared.
 
 
   async *stop(force) {
-    var _this$server4, _this$build, _this$build2;
+    var _this$server3;
 
     // not started, but the browser was launched
     if (!this.readyState && this.browser.isConnected()) {
@@ -279,16 +207,24 @@ export class Percy {
 
     if (!this.readyState || this.readyState > 2) return; // close queues asap
 
-    if (force) this.close(); // already stopping
+    if (force) {
+      this.#discovery.close(true);
+      this.#snapshots.close(true);
+    } // already stopping
+
 
     if (this.readyState === 2) return;
     this.readyState = 2; // log when force stopping
 
-    if (force) this.log.info('Stopping percy...');
+    if (force) this.log.info('Stopping percy...'); // used to log snapshot count information
+
+    let info = (state, size) => `${state} ` + `${size} snapshot${size !== 1 ? 's' : ''}`;
 
     try {
-      // process uploads and close queues
-      yield* this.yield.flush(true);
+      // flush discovery and snapshot queues
+      yield* this.yield.flush((state, size) => {
+        this.log.progress(`${info(state, size)}...`, !!size);
+      });
     } catch (error) {
       // reset ready state when aborted
 
@@ -298,81 +234,32 @@ export class Percy {
     } // if dry-running, log the total number of snapshots
 
 
-    if (this.dryRun && this.#uploads.size) {
-      let total = this.#uploads.size - 1; // subtract the build task
-
-      this.log.info(`Found ${total} snapshot${total !== 1 ? 's' : ''}`);
-    } // close any running server and browser
-
-
-    await ((_this$server4 = this.server) === null || _this$server4 === void 0 ? void 0 : _this$server4.close());
-    await this.browser.close(); // finalize and log build info
+    if (this.dryRun && this.#snapshots.size) {
+      this.log.info(info('Found', this.#snapshots.size));
+    } // close server and end queues
 
-    let meta = {
-      build: this.build
-    };
-
-    if ((_this$build = this.build) !== null && _this$build !== void 0 && _this$build.failed) {
-      // do not finalize failed builds
-      this.log.warn(`Build #${this.build.number} failed: ${this.build.url}`, meta);
-    } else if ((_this$build2 = this.build) !== null && _this$build2 !== void 0 && _this$build2.id) {
-      // finalize the build
-      await this.client.finalizeBuild(this.build.id);
-      this.log.info(`Finalized build #${this.build.number}: ${this.build.url}`, meta);
-    } else {
-      // no build was ever created (likely failed while deferred)
-      this.log.warn('Build not created', meta);
-    } // mark instance as stopped
 
+    await ((_this$server3 = this.server) === null || _this$server3 === void 0 ? void 0 : _this$server3.close());
+    await this.#discovery.end();
+    await this.#snapshots.end(); // mark instance as stopped
 
     this.readyState = 3;
-  } // Deprecated capture method
-
-
-  capture(options) {
-    this.log.deprecated('The #capture() method will be ' + 'removed in 1.0.0. Use #snapshot() instead.');
-    return this.snapshot(options);
-  } // 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 using
-  // various methods.
-  //
-  // snapshot(url|{url}|[...url|{url}])
-  // - requires fully qualified resolvable urls
-  // - snapshot options may be provided with the object syntax
-  //
-  // snapshot({snapshots:[...url|{url}]})
-  // - optional `baseUrl` prepended to snapshot urls
-  // - optional `options` apply to all or specific snapshots
-  //
-  // snapshot(sitemap|{sitemap})
-  // - required to be a fully qualified resolvable url ending in `.xml`
-  // - optional `include`/`exclude` to filter snapshots
-  // - optional `options` apply to all or specific snapshots
-  //
-  // snapshot({serve})
-  // - server address is prepended to snapshot urls
-  // - optional `baseUrl` used when serving pages
-  // - optional `rewrites`/`cleanUrls` to control snapshot urls
-  // - optional `include`/`exclude` to filter snapshots
-  // - optional `snapshots`, with fallback to built-in sitemap.xml
-  // - optional `options` apply to all or specific snapshots
-  //
-  // All available syntaxes will eventually push snapshots to the snapshot queue without the need to
-  // await on this method directly. This method resolves after the snapshot upload is queued, but
-  // does not await on the upload to complete.
+  } // Takes one or more snapshots of a page while discovering resources to upload with the resulting
+  // snapshots. Once asset discovery has completed for the provided snapshots, the queued task will
+  // resolve and an upload task will be queued separately.
 
 
   snapshot(options) {
-    var _this$build3;
+    var _this$build;
 
     if (this.readyState !== 1) {
       throw new Error('Not running');
-    } else if ((_this$build3 = this.build) !== null && _this$build3 !== void 0 && _this$build3.error) {
+    } else if ((_this$build = this.build) !== null && _this$build !== void 0 && _this$build.error) {
       throw new Error(this.build.error);
     } else if (Array.isArray(options)) {
       return yieldAll(options.map(o => this.yield.snapshot(o)));
-    }
+    } // accept a url for a sitemap or snapshot
+
 
     if (typeof options === 'string') {
       options = options.endsWith('.xml') ? {
@@ -385,104 +272,94 @@ export class Percy {
 
     options = validateSnapshotOptions(options);
     this.client.addClientInfo(options.clientInfo);
-    this.client.addEnvironmentInfo(options.environmentInfo); // return an async generator to allow cancelation
+    this.client.addEnvironmentInfo(options.environmentInfo); // without a discovery browser, capture is not possible
+
+    if (this.skipDiscovery && !this.dryRun && !options.domSnapshot) {
+      throw new Error('Cannot capture DOM snapshots when asset discovery is disabled');
+    } // return an async generator to allow cancelation
+
 
     return async function* () {
-      let server = 'serve' in options ? await createStaticServer(options).listen() : null;
+      let server;
 
       try {
-        if (server) {
-          // automatically set specific static server options
-          options.baseUrl = new URL(options.baseUrl || '', server.address()).href;
-          if (!options.snapshots) options.sitemap = new URL('sitemap.xml', options.baseUrl).href;
-        } // gather snapshots from options
-
-
-        let snapshots = yield* gatherSnapshots(this, options);
-
-        try {
-          // use a try-catch to cancel snapshots that haven't started when the error occurred
-          yield* yieldAll(snapshots.map(s => this._takeSnapshot(s)));
-        } catch (error) {
-          // cancel queued snapshots that may not have started
-          snapshots.map(s => this._cancelSnapshot(s));
-          throw error;
-        }
+        if ('serve' in options) {
+          // create and start a static server
+          let {
+            baseUrl,
+            snapshots
+          } = options;
+          server = yield createStaticServer(options).listen();
+          baseUrl = options.baseUrl = new URL(baseUrl || '', server.address()).href;
+          if (!snapshots) options.sitemap = new URL('sitemap.xml', baseUrl).href;
+        } // gather snapshots and discover snapshot resources
+
+
+        yield* discoverSnapshotResources(this.#discovery, {
+          skipDiscovery: this.skipDiscovery,
+          dryRun: this.dryRun,
+          snapshots: yield* gatherSnapshots(options, {
+            meta: {
+              build: this.build
+            },
+            config: this.config
+          })
+        }, snapshot => {
+          // push each finished snapshot to the snapshots queue
+          this.#snapshots.push(snapshot);
+        });
       } finally {
-        await (server === null || server === void 0 ? void 0 : server.close());
+        var _server;
+
+        // always close any created server
+        await ((_server = server) === null || _server === void 0 ? void 0 : _server.close());
       }
     }.call(this);
-  } // Cancel any pending snapshot or snapshot uploads
-
+  } // Uploads one or more snapshots directly to the current Percy build
 
-  _cancelSnapshot(snapshot) {
-    this.#snapshots.cancel(`snapshot/${snapshot.name}`);
 
-    for (let {
-      name
-    } of [snapshot, ...(snapshot.additionalSnapshots || [])]) {
-      this.#uploads.cancel(`upload/${name}`);
-    }
-  } // Resolves after asset discovery has finished and uploads have been queued
+  upload(options) {
+    if (this.readyState !== 1) {
+      throw new Error('Not running');
+    } else if (Array.isArray(options)) {
+      return yieldAll(options.map(o => this.yield.upload(o)));
+    } // validate comparison uploads and warn about any errors
 
 
-  _takeSnapshot(snapshot) {
-    // cancel any existing snapshot with the same name
-    this._cancelSnapshot(snapshot);
+    if ('tag' in options || 'tiles' in options) {
+      var _options$tag;
 
-    return this.#snapshots.push(`snapshot/${snapshot.name}`, async function* () {
-      try {
-        yield* discoverSnapshotResources(this, snapshot, (snap, resources) => {
-          if (!this.dryRun) this.log.info(`Snapshot taken: ${snap.name}`, snap.meta);
+      // throw when missing required snapshot or tag name
+      if (!options.name) throw new Error('Missing required snapshot name');
+      if (!((_options$tag = options.tag) !== null && _options$tag !== void 0 && _options$tag.name)) throw new Error('Missing required tag name for comparison'); // normalize, migrate, and remove certain properties from validating
 
-          this._scheduleUpload(snap.name, { ...snap,
-            resources
-          });
-        });
-      } catch (error) {
-        if (error.name === 'AbortError') {
-          this.log.error('Received a duplicate snapshot name, ' + `the previous snapshot was aborted: ${snapshot.name}`, snapshot.meta);
-        } else {
-          this.log.error(`Encountered an error taking snapshot: ${snapshot.name}`, snapshot.meta);
-          this.log.error(error, snapshot.meta);
-        }
-      }
-    }.bind(this));
-  } // Queues a snapshot upload with the provided options
+      options = PercyConfig.migrate(options, '/comparison');
+      let {
+        clientInfo,
+        environmentInfo,
+        ...comparison
+      } = options;
+      let errors = PercyConfig.validate(comparison, '/comparison');
 
+      if (errors) {
+        this.log.warn('Invalid upload options:');
 
-  _scheduleUpload(name, options) {
-    var _this$build4;
+        for (let e of errors) this.log.warn(`- ${e.path}: ${e.message}`);
+      }
+    } // add client & environment info
 
-    if ((_this$build4 = this.build) !== null && _this$build4 !== void 0 && _this$build4.error) throw new Error(this.build.error); // maybe process any existing delayed uploads
 
-    if (!this.skipUploads && this.delayUploads && (!this.build || this.build.id)) this.#uploads.run();
-    return this.#uploads.push(`upload/${name}`, async () => {
-      // when delayed, stop the queue before other uploads are processed
-      if (this.readyState < 2 && this.delayUploads) this.#uploads.stop();
+    this.client.addClientInfo(options.clientInfo);
+    this.client.addEnvironmentInfo(options.environmentInfo); // return an async generator to allow cancelation
 
+    return async function* () {
       try {
-        /* istanbul ignore if: useful for other internal packages */
-        if (typeof options === 'function') options = await options();
-        await this.client.sendSnapshot(this.build.id, options);
+        return yield* yieldTo(this.#snapshots.push(options));
       } catch (error) {
-        var _error$response;
-
-        let failed = ((_error$response = error.response) === null || _error$response === void 0 ? void 0 : _error$response.statusCode) === 422 && error.response.body.errors.find(e => {
-          var _e$source;
-
-          return ((_e$source = e.source) === null || _e$source === void 0 ? void 0 : _e$source.pointer) === '/data/attributes/build';
-        });
-        this.log.error(`Encountered an error uploading snapshot: ${name}`, options.meta);
-        this.log.error((failed === null || failed === void 0 ? void 0 : failed.detail) ?? error, options.meta); // build failed at some point, stop accepting snapshots
-
-        if (failed) {
-          this.build.error = failed.detail;
-          this.build.failed = true;
-          this.close();
-        }
+        this.#snapshots.cancel(options);
+        throw error;
       }
-    });
+    }.call(this);
   }
 
 }