@percy/core 1.0.0 → 1.0.3

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;
+}

package/dist/browser.js

@@ -0,0 +1,292 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import spawn from 'cross-spawn';
+import EventEmitter from 'events';
+import WebSocket from 'ws';
+import rimraf from 'rimraf';
+import logger from '@percy/logger';
+import install from './install.js';
+import Session from './session.js';
+import Page from './page.js';
+export class Browser extends EventEmitter {
+  log = logger('core:browser');
+  sessions = new Map();
+  readyState = null;
+  closed = false;
+  #callbacks = new Map();
+  #lastid = 0;
+  args = [// disable the translate popup
+  '--disable-features=Translate', // disable several subsystems which run network requests in the background
+  '--disable-background-networking', // disable task throttling of timer tasks from background pages
+  '--disable-background-timer-throttling', // disable backgrounding renderer processes
+  '--disable-renderer-backgrounding', // disable backgrounding renderers for occluded windows (reduce nondeterminism)
+  '--disable-backgrounding-occluded-windows', // disable crash reporting
+  '--disable-breakpad', // disable client side phishing detection
+  '--disable-client-side-phishing-detection', // disable default component extensions with background pages for performance
+  '--disable-component-extensions-with-background-pages', // disable installation of default apps on first run
+  '--disable-default-apps', // work-around for environments where a small /dev/shm partition causes crashes
+  '--disable-dev-shm-usage', // disable extensions
+  '--disable-extensions', // disable hang monitor dialogs in renderer processes
+  '--disable-hang-monitor', // disable inter-process communication flooding protection for javascript
+  '--disable-ipc-flooding-protection', // disable web notifications and the push API
+  '--disable-notifications', // disable the prompt when a POST request causes page navigation
+  '--disable-prompt-on-repost', // disable syncing browser data with google accounts
+  '--disable-sync', // disable site-isolation to make network requests easier to intercept
+  '--disable-site-isolation-trials', // disable the first run tasks, whether or not it's actually the first run
+  '--no-first-run', // disable the sandbox for all process types that are normally sandboxed
+  '--no-sandbox', // enable indication that browser is controlled by automation
+  '--enable-automation', // specify a consistent encryption backend across platforms
+  '--password-store=basic', // use a mock keychain on Mac to prevent blocking permissions dialogs
+  '--use-mock-keychain', // enable remote debugging on the first available port
+  '--remote-debugging-port=0'];
+
+  constructor({
+    executable = process.env.PERCY_BROWSER_EXECUTABLE,
+    timeout = 30000,
+    headless = true,
+    cookies = [],
+    args = []
+  }) {
+    super();
+    this.launchTimeout = timeout;
+    this.executable = executable;
+    this.headless = headless;
+    /* istanbul ignore next: only false for debugging */
+
+    if (this.headless) this.args.push('--headless', '--hide-scrollbars', '--mute-audio');
+
+    for (let a of args) if (!this.args.includes(a)) this.args.push(a); // transform cookies object to an array of cookie params
+
+
+    this.cookies = Array.isArray(cookies) ? cookies : Object.entries(cookies).map(([name, value]) => ({
+      name,
+      value
+    }));
+  }
+
+  async launch() {
+    // already launching or launched
+    if (this.readyState != null) return;
+    this.readyState = 0; // check if any provided executable exists
+
+    if (this.executable && !fs.existsSync(this.executable)) {
+      this.log.error(`Browser executable not found: ${this.executable}`);
+      this.executable = null;
+    } // download and install the browser if not already present
+
+
+    this.executable || (this.executable = await install.chromium()); // create a temporary profile directory
+
+    this.profile = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'percy-browser-')); // spawn the browser process detached in its own group and session
+
+    let args = this.args.concat(`--user-data-dir=${this.profile}`);
+    this.log.debug('Launching browser');
+    this.process = spawn(this.executable, args, {
+      detached: process.platform !== 'win32'
+    }); // connect a websocket to the devtools address
+
+    this.ws = new WebSocket(await this.address(), {
+      perMessageDeflate: false
+    }); // wait until the websocket has connected
+
+    await new Promise(resolve => this.ws.once('open', resolve));
+    this.ws.on('message', data => this._handleMessage(data)); // get version information
+
+    this.version = await this.send('Browser.getVersion');
+    this.log.debug(`Browser connected [${this.process.pid}]: ${this.version.product}`);
+    this.readyState = 1;
+  }
+
+  isConnected() {
+    var _this$ws;
+
+    return ((_this$ws = this.ws) === null || _this$ws === void 0 ? void 0 : _this$ws.readyState) === WebSocket.OPEN;
+  }
+
+  async close() {
+    var _this$process, _this$ws2;
+
+    // not running, already closed, or closing
+    if (this._closed) return this._closed;
+    this.readyState = 2;
+    this.log.debug('Closing browser'); // resolves when the browser has closed
+
+    this._closed = Promise.all([new Promise(resolve => {
+      /* istanbul ignore next: race condition paranoia */
+      if (!this.process || this.process.exitCode) resolve();else this.process.on('exit', resolve);
+    }), new Promise(resolve => {
+      /* istanbul ignore next: race condition paranoia */
+      if (!this.isConnected()) resolve();else this.ws.on('close', resolve);
+    })]).then(() => {
+      /* istanbul ignore next:
+       *   this might fail on some systems but ultimately it is just a temp file */
+      if (this.profile) {
+        // attempt to clean up the profile directory
+        return new Promise((resolve, reject) => {
+          rimraf(this.profile, e => e ? reject(e) : resolve());
+        }).catch(error => {
+          this.log.debug('Could not clean up temporary browser profile directory.');
+          this.log.debug(error);
+        });
+      }
+    }).then(() => {
+      this.log.debug('Browser closed');
+      this.readyState = 3;
+    }); // reject any pending callbacks
+
+    for (let callback of this.#callbacks.values()) {
+      callback.reject(Object.assign(callback.error, {
+        message: `Protocol error (${callback.method}): Browser closed.`
+      }));
+    } // trigger rejecting pending session callbacks
+
+
+    for (let session of this.sessions.values()) {
+      session._handleClose();
+    } // clear own callbacks and sessions
+
+
+    this.#callbacks.clear();
+    this.sessions.clear();
+    /* istanbul ignore next:
+     *   difficult to test failure here without mocking private properties */
+
+    if ((_this$process = this.process) !== null && _this$process !== void 0 && _this$process.pid && !this.process.killed) {
+      // always force close the browser process
+      try {
+        this.process.kill('SIGKILL');
+      } catch (error) {
+        throw new Error(`Unable to close the browser: ${error.stack}`);
+      }
+    } // close the socket connection
+
+
+    (_this$ws2 = this.ws) === null || _this$ws2 === void 0 ? void 0 : _this$ws2.close(); // wait for the browser to close
+
+    return this._closed;
+  }
+
+  async page(options = {}) {
+    let {
+      targetId
+    } = await this.send('Target.createTarget', {
+      url: ''
+    });
+    let {
+      sessionId
+    } = await this.send('Target.attachToTarget', {
+      targetId,
+      flatten: true
+    });
+    let page = new Page(this.sessions.get(sessionId), options);
+    await page._handleAttachedToTarget();
+    return page;
+  }
+
+  async send(method, params) {
+    /* istanbul ignore next:
+     *   difficult to test failure here without mocking private properties */
+    if (!this.isConnected()) throw new Error('Browser not connected'); // every command needs a unique id
+
+    let id = ++this.#lastid;
+
+    if (!params && typeof method === 'object') {
+      // allow providing a raw message as the only argument and return the id
+      this.ws.send(JSON.stringify({ ...method,
+        id
+      }));
+      return id;
+    } else {
+      // send the message payload
+      this.ws.send(JSON.stringify({
+        id,
+        method,
+        params
+      })); // will resolve or reject when a matching response is received
+
+      return new Promise((resolve, reject) => {
+        this.#callbacks.set(id, {
+          error: new Error(),
+          resolve,
+          reject,
+          method
+        });
+      });
+    }
+  } // Returns the devtools websocket address. If not already known, will watch the browser's
+  // stderr and resolves when it emits the devtools protocol address or rejects if the process
+  // exits for any reason or if the address does not appear after the timeout.
+
+
+  async address(timeout = this.launchTimeout) {
+    this._address || (this._address = await new Promise((resolve, reject) => {
+      let stderr = '';
+
+      let handleData = chunk => {
+        stderr += chunk = chunk.toString();
+        let match = chunk.match(/^DevTools listening on (ws:\/\/.*)$/m);
+        if (match) cleanup(() => resolve(match[1]));
+      };
+
+      let handleExitClose = () => handleError();
+
+      let handleError = error => cleanup(() => reject(new Error(`Failed to launch browser. ${(error === null || error === void 0 ? void 0 : error.message) ?? ''}\n${stderr}'\n\n`)));
+
+      let cleanup = callback => {
+        clearTimeout(timeoutId);
+        this.process.stderr.off('data', handleData);
+        this.process.stderr.off('close', handleExitClose);
+        this.process.off('exit', handleExitClose);
+        this.process.off('error', handleError);
+        callback();
+      };
+
+      let timeoutId = setTimeout(() => handleError(new Error(`Timed out after ${timeout}ms`)), timeout);
+      this.process.stderr.on('data', handleData);
+      this.process.stderr.on('close', handleExitClose);
+      this.process.on('exit', handleExitClose);
+      this.process.on('error', handleError);
+    }));
+    return this._address;
+  }
+
+  _handleMessage(data) {
+    data = JSON.parse(data);
+
+    if (data.method === 'Target.attachedToTarget') {
+      // create a new session reference when attached to a target
+      let session = new Session(this, data);
+      this.sessions.set(session.sessionId, session);
+    } else if (data.method === 'Target.detachedFromTarget') {
+      // remove the old session reference when detached from a target
+      let session = this.sessions.get(data.params.sessionId);
+      this.sessions.delete(data.params.sessionId);
+      session === null || session === void 0 ? void 0 : session._handleClose();
+    }
+
+    if (data.sessionId) {
+      // message was for a specific session that sent it
+      let session = this.sessions.get(data.sessionId);
+      session === null || session === void 0 ? void 0 : session._handleMessage(data);
+    } else if (data.id && this.#callbacks.has(data.id)) {
+      // resolve or reject a pending promise created with #send()
+      let callback = this.#callbacks.get(data.id);
+      this.#callbacks.delete(data.id);
+      /* istanbul ignore next: races with page._handleMessage() */
+
+      if (data.error) {
+        callback.reject(Object.assign(callback.error, {
+          message: `Protocol error (${callback.method}): ${data.error.message}` + ('data' in data.error ? `: ${data.error.data}` : '')
+        }));
+      } else {
+        callback.resolve(data.result);
+      }
+    } else {
+      // emit the message as an event
+      this.emit(data.method, data.params);
+    }
+  }
+
+}
+export default Browser;