✨ Add --debug discovery flag (#492)

* ✨ Add core option to skip uploads

* ♻ Move build task creation out of try-catch block

This particular piece of code will not throw an error since it is not awaited on until later, still
within the try-catch block

* ✨ Add common --debug discovery flag

* 📝 Update readmes

packages/cli-command/src/command.js

@@ -66,6 +66,7 @@ export default class PercyCommand extends Command {
 
  // set config: false to prevent core from reloading config
  return Object.assign(config, {
+ skipUploads: this.flags.debug,
  config: false
  });
  }

packages/cli-command/src/flags.js

@@ -18,22 +18,25 @@ const logging = {
  })
 };
 
-// Common asset discovery flags mapped to config options.
+// Common asset discovery flags.
 const discovery = {
  'allowed-hostname': flags.string({
  char: 'h',
- description: 'allowed hostnames',
+ description: 'allowed hostnames to capture in asset discovery',
  multiple: true,
  percyrc: 'discovery.allowedHostnames'
  }),
  'network-idle-timeout': flags.integer({
  char: 't',
- description: 'asset discovery idle timeout',
+ description: 'asset discovery network idle timeout',
  percyrc: 'discovery.networkIdleTimeout'
  }),
  'disable-cache': flags.boolean({
  description: 'disable asset discovery caches',
  percyrc: 'discovery.disableCache'
+ }),
+ debug: flags.boolean({
+ description: 'debug asset discovery and do not upload snapshots'
  })
 };
 

packages/cli-command/test/command.test.js

@@ -66,6 +66,8 @@ describe('PercyCommand', () => {
  expect(logger.loglevel()).toBe('warn');
  await TestPercyCommand.run(['--silent']);
  expect(logger.loglevel()).toBe('silent');
+ await TestPercyCommand.run(['--debug']);
+ expect(logger.loglevel()).toBe('debug');
  });
 
  it('logs errors to the logger and exits', async () => {
@@ -127,12 +129,14 @@ describe('PercyCommand', () => {
  '--allowed-hostname', '*.percy.io',
  '--network-idle-timeout', '150',
  '--disable-cache',
+ '--debug',
  'foo', 'bar'
  ])).toBeResolved();
 
  expect(results[0].percyrc()).toEqual({
  version: 2,
  config: false,
+ skipUploads: true,
  snapshot: {
  widths: [375, 1280],
  minHeight: 1024,

packages/cli-exec/README.md

@@ -20,10 +20,11 @@ USAGE
 OPTIONS
  -P, --port=port [default: 5338] server port
  -c, --config=config configuration file path
- -h, --allowed-hostname=allowed-hostname allowed hostnames
+ -h, --allowed-hostname=allowed-hostname allowed hostnames to capture in asset discovery
  -q, --quiet log errors only
- -t, --network-idle-timeout=network-idle-timeout asset discovery idle timeout
+ -t, --network-idle-timeout=network-idle-timeout asset discovery network idle timeout
  -v, --verbose log everything
+ --debug debug asset discovery and do not upload snapshots
  --disable-cache disable asset discovery caches
  --parallel marks the build as one of many parallel builds
  --partial marks the build as a partial build
@@ -60,10 +61,11 @@ USAGE
 OPTIONS
  -P, --port=port [default: 5338] server port
  -c, --config=config configuration file path
- -h, --allowed-hostname=allowed-hostname allowed hostnames
+ -h, --allowed-hostname=allowed-hostname allowed hostnames to capture in asset discovery
  -q, --quiet log errors only
- -t, --network-idle-timeout=network-idle-timeout asset discovery idle timeout
+ -t, --network-idle-timeout=network-idle-timeout asset discovery network idle timeout
  -v, --verbose log everything
+ --debug debug asset discovery and do not upload snapshots
  --disable-cache disable asset discovery caches
  --silent log nothing
 

packages/cli-snapshot/README.md

@@ -21,11 +21,12 @@ OPTIONS
  -b, --base-url=base-url the base url pages are hosted at when snapshotting
  -c, --config=config configuration file path
  -d, --dry-run prints a list of pages to snapshot without snapshotting
- -h, --allowed-hostname=allowed-hostname allowed hostnames
+ -h, --allowed-hostname=allowed-hostname allowed hostnames to capture in asset discovery
  -q, --quiet log errors only
- -t, --network-idle-timeout=network-idle-timeout asset discovery idle timeout
+ -t, --network-idle-timeout=network-idle-timeout asset discovery network idle timeout
  -v, --verbose log everything
  --clean-urls rewrite static index and filepath URLs to be clean
+ --debug debug asset discovery and do not upload snapshots
  --disable-cache disable asset discovery caches
 
  --files=files [default: **/*.{html,htm}] one or more globs matching static file

packages/core/README.md

@@ -38,6 +38,7 @@ const percy = await Percy.start(percyOptions)
 - `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
 

packages/core/src/percy.js

@@ -36,8 +36,10 @@ export default class Percy {
  constructor({
  // initial log level
  loglevel,
- // upload snapshots eagerly by default
- deferUploads = false,
+ // do not eagerly upload snapshots
+ deferUploads,
+ // run without uploading anything
+ skipUploads,
  // configuration filepath
  config,
  // provided to @percy/client
@@ -52,7 +54,8 @@ export default class Percy {
  ...options
  } = {}) {
  if (loglevel) this.loglevel(loglevel);
- this.deferUploads = deferUploads;
+ this.deferUploads = skipUploads || deferUploads;
+ this.skipUploads = skipUploads;
 
  this.config = PercyConfig.load({
  overrides: options,
@@ -99,7 +102,7 @@ export default class Percy {
  // Waits for snapshot idle and flushes the upload queue
  async dispatch() {
  await this.#snapshots.idle();
- await this.#uploads.flush();
+ if (!this.skipUploads) await this.#uploads.flush();
  }
 
  // Immediately stops all queues, preventing any more tasks from running
@@ -111,40 +114,36 @@ export default class Percy {
  // 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.
  async start() {
- // throws when the token is missing
- this.client.getToken();
-
  // already starting or started
  if (this.readyState != null) return;
  this.readyState = 0;
 
- try {
- // 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();
-
- return this.client.createBuild()
- .then(({ data: { id, attributes } }) => {
- this.build = { id };
- this.build.number = attributes['build-number'];
- this.build.url = attributes['web-url'];
- this.#uploads.run();
- });
- }, 0);
-
- if (!this.deferUploads) {
- // when not deferred, wait until the build is created
- await buildTask;
- } else {
- // handle deferred build errors
- buildTask.catch(err => {
- this.log.error('Failed to create build');
- this.log.error(err);
- this.close();
+ // 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();
+
+ return this.client.createBuild()
+ .then(({ data: { id, attributes } }) => {
+ this.build = { id };
+ this.build.number = attributes['build-number'];
+ this.build.url = attributes['web-url'];
+ this.#uploads.run();
  });
- }
+ }, 0);
+
+ // handle deferred build errors
+ if (this.deferUploads) {
+ buildTask.catch(err => {
+ this.log.error('Failed to create build');
+ this.log.error(err);
+ this.close();
+ });
+ }
 
+ try {
+ // when not deferred, wait until the build is created first
+ if (!this.deferUploads) await buildTask;
  // launch the discovery browser
  await this.browser.launch(this.config.discovery.launchOptions);
  // if there is a server, start listening
@@ -194,7 +193,7 @@ export default class Percy {
  }
 
  // run, close, and wait for the upload queue to empty
- if (this.#uploads.run().close().length) {
+ if (!this.skipUploads && this.#uploads.run().close().length) {
  await this.#uploads.empty(len => {
  this.log.progress(`Uploading ${len}` + (
  ` snapshot${len !== 1 ? 's' : ''}...`), !!len);

packages/core/test/percy.test.js

@@ -207,6 +207,26 @@ describe('Percy', () => {
  expect(mockAPI.requests['/builds']).toBeDefined();
  });
 
+ it('does not create a build when uploads are skipped', async () => {
+ percy = new Percy({ token: 'PERCY_TOKEN', skipUploads: true });
+ await expectAsync(percy.start()).toBeResolved();
+ expect(mockAPI.requests['/builds']).toBeUndefined();
+
+ // attempt to dispatch differed uploads
+ await percy.dispatch();
+
+ expect(mockAPI.requests['/builds']).toBeUndefined();
+
+ // stopping should also skip uploads
+ await percy.stop();
+
+ expect(mockAPI.requests['/builds']).toBeUndefined();
+
+ expect(logger.stderr).toEqual([
+ '[percy] Build not created'
+ ]);
+ });
+
  it('stops accepting snapshots when a queued build fails to be created', async () => {
  server = await createTestServer({
  default: () => [200, 'text/html', '<p>Snapshot</p>']

packages/logger/src/index.js

@@ -14,7 +14,8 @@ Object.assign(logger, {
  connect: (...args) => new Logger().connect(...args),
  remote: (...args) => new Logger().remote(...args),
  loglevel(level, flags = {}) {
- if (flags.verbose) level = 'debug';
+ if (flags.debug) level = 'debug';
+ else if (flags.verbose) level = 'debug';
  else if (flags.quiet) level = 'warn';
  else if (flags.silent) level = 'silent';
  return new Logger().loglevel(level);

packages/logger/test/logger.test.js

@@ -171,6 +171,8 @@ describe('logger', () => {
  });
 
  it('can be controlled by a secondary flags argument', () => {
+ logger.loglevel('info', { debug: true });
+ expect(logger.loglevel()).toEqual('debug');
  logger.loglevel('info', { verbose: true });
  expect(logger.loglevel()).toEqual('debug');
  logger.loglevel('info', { quiet: true });
@@ -267,7 +269,7 @@ describe('logger', () => {
  expect(helpers.stderr).toEqual([
  jasmine.stringMatching('Warn log \\(\\dms\\)'),
  jasmine.stringMatching('Error log \\(\\dms\\)'),
- jasmine.stringMatching('Debug log \\((9[0-9]|1[01][0-9])ms\\)'),
+ jasmine.stringMatching('Debug log \\(\\d{2,3}ms\\)'),
  jasmine.stringMatching('Final log \\(\\dms\\)')
  ]);
  });