@percy/client 1.0.0 → 1.0.1

package/dist/client.js

@@ -0,0 +1,348 @@
+import fs from 'fs';
+import PercyEnv from '@percy/env';
+import { git } from '@percy/env/utils';
+import logger from '@percy/logger';
+import { pool, request, sha256hash, base64encode, getPackageJSON } from './utils.js'; // Default client API URL can be set with an env var for API development
+
+const {
+  PERCY_CLIENT_API_URL = 'https://percy.io/api/v1'
+} = process.env;
+const pkg = getPackageJSON(import.meta.url); // Validate build ID arguments
+
+function validateBuildId(id) {
+  if (!id) throw new Error('Missing build ID');
+
+  if (!(typeof id === 'string' || typeof id === 'number')) {
+    throw new Error('Invalid build ID');
+  }
+} // Validate project path arguments
+
+
+function validateProjectPath(path) {
+  if (!path) throw new Error('Missing project path');
+
+  if (!/^[^/]+?\/.+/.test(path)) {
+    throw new Error(`Invalid project path. Expected "org/project" but received "${path}"`);
+  }
+} // PercyClient is used to communicate with the Percy API to create and finalize
+// builds and snapshot. Uses @percy/env to collect environment information used
+// during build creation.
+
+
+export class PercyClient {
+  log = logger('client');
+  env = new PercyEnv(process.env);
+  clientInfo = new Set();
+  environmentInfo = new Set();
+
+  constructor({
+    // read or write token, defaults to PERCY_TOKEN environment variable
+    token,
+    // initial user agent info
+    clientInfo,
+    environmentInfo,
+    // versioned api url
+    apiUrl = PERCY_CLIENT_API_URL
+  } = {}) {
+    Object.assign(this, {
+      token,
+      apiUrl
+    });
+    this.addClientInfo(clientInfo);
+    this.addEnvironmentInfo(environmentInfo);
+  } // Adds additional unique client info.
+
+
+  addClientInfo(info) {
+    for (let i of [].concat(info)) {
+      if (i) this.clientInfo.add(i);
+    }
+  } // Adds additional unique environment info.
+
+
+  addEnvironmentInfo(info) {
+    for (let i of [].concat(info)) {
+      if (i) this.environmentInfo.add(i);
+    }
+  } // Stringifies client and environment info.
+
+
+  userAgent() {
+    let client = new Set([`Percy/${/\w+$/.exec(this.apiUrl)}`].concat(`${pkg.name}/${pkg.version}`, ...this.clientInfo).filter(Boolean));
+    let environment = new Set([...this.environmentInfo].concat(`node/${process.version}`, this.env.info).filter(Boolean));
+    return `${[...client].join(' ')} (${[...environment].join('; ')})`;
+  } // Checks for a Percy token and returns it.
+
+
+  getToken() {
+    let token = this.token || this.env.token;
+    if (!token) throw new Error('Missing Percy token');
+    return token;
+  } // Returns common headers used for each request with additional
+  // headers. Throws an error when the token is missing, which is a required
+  // authorization header.
+
+
+  headers(headers) {
+    return Object.assign({
+      Authorization: `Token token=${this.getToken()}`,
+      'User-Agent': this.userAgent()
+    }, headers);
+  } // Performs a GET request for an API endpoint with appropriate headers.
+
+
+  get(path) {
+    return request(`${this.apiUrl}/${path}`, {
+      headers: this.headers(),
+      method: 'GET'
+    });
+  } // Performs a POST request to a JSON API endpoint with appropriate headers.
+
+
+  post(path, body = {}) {
+    return request(`${this.apiUrl}/${path}`, {
+      headers: this.headers({
+        'Content-Type': 'application/vnd.api+json'
+      }),
+      method: 'POST',
+      body
+    });
+  } // Creates a build with optional build resources. Only one build can be
+  // created at a time per instance so snapshots and build finalization can be
+  // done more seemlessly without manually tracking build ids
+
+
+  async createBuild({
+    resources = []
+  } = {}) {
+    this.log.debug('Creating a new build...');
+    return this.post('builds', {
+      data: {
+        type: 'builds',
+        attributes: {
+          branch: this.env.git.branch,
+          'target-branch': this.env.target.branch,
+          'target-commit-sha': this.env.target.commit,
+          'commit-sha': this.env.git.sha,
+          'commit-committed-at': this.env.git.committedAt,
+          'commit-author-name': this.env.git.authorName,
+          'commit-author-email': this.env.git.authorEmail,
+          'commit-committer-name': this.env.git.committerName,
+          'commit-committer-email': this.env.git.committerEmail,
+          'commit-message': this.env.git.message,
+          'pull-request-number': this.env.pullRequest,
+          'parallel-nonce': this.env.parallel.nonce,
+          'parallel-total-shards': this.env.parallel.total,
+          partial: this.env.partial
+        },
+        relationships: {
+          resources: {
+            data: resources.map(r => ({
+              type: 'resources',
+              id: r.sha || sha256hash(r.content),
+              attributes: {
+                'resource-url': r.url,
+                'is-root': r.root || null,
+                mimetype: r.mimetype || null
+              }
+            }))
+          }
+        }
+      }
+    });
+  } // Finalizes the active build. When `all` is true, `all-shards=true` is
+  // added as a query param so the API finalizes all other build shards.
+
+
+  async finalizeBuild(buildId, {
+    all = false
+  } = {}) {
+    validateBuildId(buildId);
+    let qs = all ? 'all-shards=true' : '';
+    this.log.debug(`Finalizing build ${buildId}...`);
+    return this.post(`builds/${buildId}/finalize?${qs}`);
+  } // Retrieves build data by id. Requires a read access token.
+
+
+  async getBuild(buildId) {
+    validateBuildId(buildId);
+    this.log.debug(`Get build ${buildId}`);
+    return this.get(`builds/${buildId}`);
+  } // Retrieves project builds optionally filtered. Requires a read access token.
+
+
+  async getBuilds(project, filters = {}) {
+    validateProjectPath(project);
+    let qs = Object.keys(filters).map(k => Array.isArray(filters[k]) ? filters[k].map(v => `filter[${k}][]=${v}`).join('&') : `filter[${k}]=${filters[k]}`).join('&');
+    this.log.debug(`Fetching builds for ${project}`);
+    return this.get(`projects/${project}/builds?${qs}`);
+  } // Resolves when the build has finished and is no longer pending or
+  // processing. By default, will time out if no update after 10 minutes.
+
+
+  waitForBuild({
+    build,
+    project,
+    commit,
+    timeout = 10 * 60 * 1000,
+    interval = 1000
+  }, onProgress) {
+    if (commit && !project) {
+      throw new Error('Missing project path for commit');
+    } else if (!commit && !build) {
+      throw new Error('Missing build ID or commit SHA');
+    } else if (project) {
+      validateProjectPath(project);
+    }
+
+    let sha = commit && (git(`rev-parse ${commit}`) || commit);
+
+    let fetchData = async () => build ? (await this.getBuild(build)).data : (await this.getBuilds(project, {
+      sha
+    })).data[0];
+
+    this.log.debug(`Waiting for build ${build || `${project} (${commit})`}...`); // recursively poll every second until the build finishes
+
+    return new Promise((resolve, reject) => async function poll(last, t) {
+      try {
+        let data = await fetchData();
+        let state = data === null || data === void 0 ? void 0 : data.attributes.state;
+        let pending = !state || state === 'pending' || state === 'processing';
+        let updated = JSON.stringify(data) !== JSON.stringify(last); // new data received
+
+        if (updated) {
+          t = Date.now(); // no new data within the timeout
+        } else if (Date.now() - t >= timeout) {
+          throw new Error('Timeout exceeded without an update');
+        } // call progress every update after the first update
+
+
+        if ((last || pending) && updated) {
+          onProgress === null || onProgress === void 0 ? void 0 : onProgress(data);
+        } // not finished, poll again
+
+
+        if (pending) {
+          return setTimeout(poll, interval, data, t); // build finished
+        } else {
+          // ensure progress is called at least once
+          if (!last) onProgress === null || onProgress === void 0 ? void 0 : onProgress(data);
+          resolve({
+            data
+          });
+        }
+      } catch (err) {
+        reject(err);
+      }
+    }(null, Date.now()));
+  } // Uploads a single resource to the active build. If `filepath` is provided,
+  // `content` is read from the filesystem. The sha is optional and will be
+  // created from `content` if one is not provided.
+
+
+  async uploadResource(buildId, {
+    url,
+    sha,
+    filepath,
+    content
+  } = {}) {
+    validateBuildId(buildId);
+    this.log.debug(`Uploading resource: ${url}...`);
+    if (filepath) content = fs.readFileSync(filepath);
+    return this.post(`builds/${buildId}/resources`, {
+      data: {
+        type: 'resources',
+        id: sha || sha256hash(content),
+        attributes: {
+          'base64-content': base64encode(content)
+        }
+      }
+    });
+  } // Uploads resources to the active build concurrently, two at a time.
+
+
+  async uploadResources(buildId, resources) {
+    validateBuildId(buildId);
+    this.log.debug(`Uploading resources for ${buildId}...`);
+    return pool(function* () {
+      for (let resource of resources) {
+        yield this.uploadResource(buildId, resource);
+      }
+    }, this, 2);
+  } // Creates a snapshot for the active build using the provided attributes.
+
+
+  async createSnapshot(buildId, {
+    name,
+    widths,
+    minHeight,
+    enableJavaScript,
+    clientInfo,
+    environmentInfo,
+    resources = []
+  } = {}) {
+    validateBuildId(buildId);
+    this.addClientInfo(clientInfo);
+    this.addEnvironmentInfo(environmentInfo);
+
+    if (!this.clientInfo.size || !this.environmentInfo.size) {
+      this.log.warn('Warning: Missing `clientInfo` and/or `environmentInfo` properties');
+    }
+
+    this.log.debug(`Creating snapshot: ${name}...`);
+    return this.post(`builds/${buildId}/snapshots`, {
+      data: {
+        type: 'snapshots',
+        attributes: {
+          name: name || null,
+          widths: widths || null,
+          'minimum-height': minHeight || null,
+          'enable-javascript': enableJavaScript || null
+        },
+        relationships: {
+          resources: {
+            data: resources.map(r => ({
+              type: 'resources',
+              id: r.sha || sha256hash(r.content),
+              attributes: {
+                'resource-url': r.url || null,
+                'is-root': r.root || null,
+                mimetype: r.mimetype || null
+              }
+            }))
+          }
+        }
+      }
+    });
+  } // Finalizes a snapshot.
+
+
+  async finalizeSnapshot(snapshotId) {
+    if (!snapshotId) throw new Error('Missing snapshot ID');
+    this.log.debug(`Finalizing snapshot ${snapshotId}...`);
+    return this.post(`snapshots/${snapshotId}/finalize`);
+  } // Convenience method for creating a snapshot for the active build, uploading
+  // missing resources for the snapshot, and finalizing the snapshot.
+
+
+  async sendSnapshot(buildId, options) {
+    var _snapshot$data$relati, _snapshot$data$relati2;
+
+    let snapshot = await this.createSnapshot(buildId, options);
+    let missing = (_snapshot$data$relati = snapshot.data.relationships) === null || _snapshot$data$relati === void 0 ? void 0 : (_snapshot$data$relati2 = _snapshot$data$relati['missing-resources']) === null || _snapshot$data$relati2 === void 0 ? void 0 : _snapshot$data$relati2.data;
+
+    if (missing !== null && missing !== void 0 && missing.length) {
+      let resources = options.resources.reduce((acc, r) => Object.assign(acc, {
+        [r.sha]: r
+      }), {});
+      await this.uploadResources(buildId, missing.map(({
+        id
+      }) => resources[id]));
+    }
+
+    await this.finalizeSnapshot(snapshot.data.id);
+    return snapshot;
+  }
+
+}
+export default PercyClient;

package/dist/index.js

@@ -0,0 +1 @@
+export { default, PercyClient } from './client.js';

package/dist/proxy.js

@@ -0,0 +1,205 @@
+import net from 'net';
+import tls from 'tls';
+import http from 'http';
+import https from 'https';
+import logger from '@percy/logger';
+const CRLF = '\r\n';
+const STATUS_REG = /^HTTP\/1.[01] (\d*)/; // Returns true if the URL hostname matches any patterns
+
+export function hostnameMatches(patterns, url) {
+  let subject = new URL(url);
+  /* istanbul ignore next: only strings are provided internally by the client proxy; core (which
+   * borrows this util) sometimes provides an array of patterns or undefined */
+
+  patterns = typeof patterns === 'string' ? patterns.split(/[\s,]+/) : [].concat(patterns);
+
+  for (let pattern of patterns) {
+    if (pattern === '*') return true;
+    if (!pattern) continue; // parse pattern
+
+    let {
+      groups: rule
+    } = pattern.match(/^(?<hostname>.+?)(?::(?<port>\d+))?$/); // missing a hostname or ports do not match
+
+    if (!rule.hostname || rule.port && rule.port !== subject.port) {
+      continue;
+    } // wildcards are treated the same as leading dots
+
+
+    rule.hostname = rule.hostname.replace(/^\*/, ''); // hostnames are equal or end with a wildcard rule
+
+    if (rule.hostname === subject.hostname || rule.hostname.startsWith('.') && subject.hostname.endsWith(rule.hostname)) {
+      return true;
+    }
+  }
+
+  return false;
+} // Returns the port number of a URL object. Defaults to port 443 for https
+// protocols or port 80 otherwise.
+
+export function port(options) {
+  if (options.port) return options.port;
+  return options.protocol === 'https:' ? 443 : 80;
+} // Returns a string representation of a URL-like object
+
+export function href(options) {
+  let {
+    protocol,
+    hostname,
+    path,
+    pathname,
+    search,
+    hash
+  } = options;
+  return `${protocol}//${hostname}:${port(options)}` + (path || `${pathname || ''}${search || ''}${hash || ''}`);
+}
+; // Returns the proxy URL for a set of request options
+
+export function getProxy(options) {
+  let proxyUrl = options.protocol === 'https:' && (process.env.https_proxy || process.env.HTTPS_PROXY) || process.env.http_proxy || process.env.HTTP_PROXY;
+  let shouldProxy = !!proxyUrl && !hostnameMatches(process.env.no_proxy || process.env.NO_PROXY, href(options));
+
+  if (shouldProxy) {
+    proxyUrl = new URL(proxyUrl);
+    let isHttps = proxyUrl.protocol === 'https:';
+
+    if (!isHttps && proxyUrl.protocol !== 'http:') {
+      throw new Error(`Unsupported proxy protocol: ${proxyUrl.protocol}`);
+    }
+
+    let proxy = {
+      isHttps
+    };
+    proxy.auth = !!proxyUrl.username && 'Basic ' + (proxyUrl.password ? Buffer.from(`${proxyUrl.username}:${proxyUrl.password}`) : Buffer.from(proxyUrl.username)).toString('base64');
+    proxy.host = proxyUrl.hostname;
+    proxy.port = port(proxyUrl);
+
+    proxy.connect = () => (isHttps ? tls : net).connect({
+      rejectUnauthorized: options.rejectUnauthorized,
+      host: proxy.host,
+      port: proxy.port
+    });
+
+    return proxy;
+  }
+} // Proxified http agent
+
+export class ProxyHttpAgent extends http.Agent {
+  // needed for https proxies
+  httpsAgent = new https.Agent({
+    keepAlive: true
+  });
+
+  addRequest(request, options) {
+    var _request$outputData;
+
+    let proxy = getProxy(options);
+    if (!proxy) return super.addRequest(request, options);
+    logger('client:proxy').debug(`Proxying request: ${options.href}`); // modify the request for proxying
+
+    request.path = href(options);
+
+    if (proxy.auth) {
+      request.setHeader('Proxy-Authorization', proxy.auth);
+    } // regenerate headers since we just changed things
+
+
+    delete request._header;
+
+    request._implicitHeader();
+
+    if (((_request$outputData = request.outputData) === null || _request$outputData === void 0 ? void 0 : _request$outputData.length) > 0) {
+      let first = request.outputData[0].data;
+      let endOfHeaders = first.indexOf(CRLF.repeat(2)) + 4;
+      request.outputData[0].data = request._header + first.substring(endOfHeaders);
+    } // coerce the connection to the proxy
+
+
+    options.port = proxy.port;
+    options.host = proxy.host;
+    delete options.path;
+
+    if (proxy.isHttps) {
+      // use the underlying https agent to complete the connection
+      request.agent = this.httpsAgent;
+      return this.httpsAgent.addRequest(request, options);
+    } else {
+      return super.addRequest(request, options);
+    }
+  }
+
+} // Proxified https agent
+
+export class ProxyHttpsAgent extends https.Agent {
+  constructor(options) {
+    // default keep-alive
+    super({
+      keepAlive: true,
+      ...options
+    });
+  }
+
+  createConnection(options, callback) {
+    let proxy = getProxy(options);
+    if (!proxy) return super.createConnection(options, callback);
+    logger('client:proxy').debug(`Proxying request: ${href(options)}`); // generate proxy connect message
+
+    let host = `${options.hostname}:${port(options)}`;
+    let connectMessage = [`CONNECT ${host} HTTP/1.1`, `Host: ${host}`];
+
+    if (proxy.auth) {
+      connectMessage.push(`Proxy-Authorization: ${proxy.auth}`);
+    }
+
+    connectMessage = connectMessage.join(CRLF);
+    connectMessage += CRLF.repeat(2); // start the proxy connection and setup listeners
+
+    let socket = proxy.connect();
+
+    let handleError = err => {
+      socket.destroy(err);
+      callback(err);
+    };
+
+    let handleClose = () => handleError(new Error('Connection closed while sending request to upstream proxy'));
+
+    let buffer = '';
+
+    let handleData = data => {
+      var _buffer$match;
+
+      buffer += data.toString(); // haven't received end of headers yet, keep buffering
+
+      if (!buffer.includes(CRLF.repeat(2))) return; // stop listening after end of headers
+
+      socket.off('data', handleData);
+
+      if (((_buffer$match = buffer.match(STATUS_REG)) === null || _buffer$match === void 0 ? void 0 : _buffer$match[1]) !== '200') {
+        return handleError(new Error('Error establishing proxy connection. ' + `Response from server was: ${buffer}`));
+      }
+
+      options.socket = socket;
+      options.servername = options.hostname; // callback not passed in so not to be added as a listener
+
+      callback(null, super.createConnection(options));
+    }; // send and handle the connect message
+
+
+    socket.on('error', handleError).on('close', handleClose).on('data', handleData).write(connectMessage);
+  }
+
+}
+export function proxyAgentFor(url, options) {
+  let cache = proxyAgentFor.cache || (proxyAgentFor.cache = new Map());
+  let {
+    protocol,
+    hostname
+  } = new URL(url);
+  let cachekey = `${protocol}//${hostname}`;
+
+  if (!cache.has(cachekey)) {
+    cache.set(cachekey, protocol === 'https:' ? new ProxyHttpsAgent(options) : new ProxyHttpAgent(options));
+  }
+
+  return cache.get(cachekey);
+}

package/dist/utils.js

@@ -0,0 +1,204 @@
+import os from 'os';
+import fs from 'fs';
+import url from 'url';
+import path from 'path';
+import crypto from 'crypto'; // Returns a sha256 hash of a string.
+
+export function sha256hash(content) {
+  return crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
+} // Returns a base64 encoding of a string or buffer.
+
+export function base64encode(content) {
+  return Buffer.from(content).toString('base64');
+} // Returns the package.json content at the package path.
+
+export function getPackageJSON(rel) {
+  /* istanbul ignore else: sanity check */
+  if (rel.startsWith('file:')) rel = url.fileURLToPath(rel);
+  let pkg = path.join(rel, 'package.json');
+  if (fs.existsSync(pkg)) return JSON.parse(fs.readFileSync(pkg));
+  let dir = path.dirname(rel);
+  /* istanbul ignore else: sanity check */
+
+  if (dir !== rel && dir !== os.homedir()) return getPackageJSON(dir);
+} // Creates a concurrent pool of promises created by the given generator.
+// Resolves when the generator's final promise resolves and rejects when any
+// generated promise rejects.
+
+export function pool(generator, context, concurrency) {
+  return new Promise((resolve, reject) => {
+    let iterator = generator.call(context);
+    let queue = 0;
+    let ret = [];
+    let err; // generates concurrent promises
+
+    let proceed = () => {
+      while (queue < concurrency) {
+        let {
+          done,
+          value: promise
+        } = iterator.next();
+
+        if (done || err) {
+          if (!queue && err) reject(err);
+          if (!queue) resolve(ret);
+          return;
+        }
+
+        queue++;
+        promise.then(value => {
+          queue--;
+          ret.push(value);
+          proceed();
+        }).catch(error => {
+          queue--;
+          err = error;
+          proceed();
+        });
+      }
+    }; // start generating promises
+
+
+    proceed();
+  });
+} // Returns a promise that resolves or rejects when the provided function calls
+// `resolve` or `reject` respectively. The third function argument, `retry`,
+// will recursively call the function at the specified interval until retries
+// are exhausted, at which point the promise will reject with the last error
+// passed to `retry`.
+
+export function retry(fn, {
+  retries = 5,
+  interval = 50
+}) {
+  return new Promise((resolve, reject) => {
+    let run = () => fn(resolve, reject, retry); // wait an interval to try again or reject with the error
+
+
+    let retry = err => {
+      if (retries-- > 0) {
+        setTimeout(run, interval);
+      } else {
+        reject(err);
+      }
+    }; // start trying
+
+
+    run();
+  });
+} // Used by the request util when retrying specific errors
+
+const RETRY_ERROR_CODES = ['ECONNREFUSED', 'ECONNRESET', 'EPIPE', 'EHOSTUNREACH', 'EAI_AGAIN']; // Proxified request function that resolves with the response body when the request is successful
+// and rejects when a non-successful response is received. The rejected error contains response data
+// and any received error details. Server 500 errors are retried up to 5 times at 50ms intervals by
+// default, and 404 errors may also be optionally retried. If a callback is provided, it is called
+// with the parsed response body and response details. If the callback returns a value, that value
+// will be returned in the final resolved promise instead of the response body.
+
+export async function request(url, options = {}, callback) {
+  // accept `request(url, callback)`
+  if (typeof options === 'function') [options, callback] = [{}, options]; // gather request options
+
+  let {
+    body,
+    headers,
+    retries,
+    retryNotFound,
+    interval,
+    noProxy,
+    ...requestOptions
+  } = options;
+  let {
+    protocol,
+    hostname,
+    port,
+    pathname,
+    search,
+    hash
+  } = new URL(url); // reference the default export so tests can mock it
+
+  let {
+    default: http
+  } = await import(protocol === 'https:' ? 'https' : 'http');
+  let {
+    proxyAgentFor
+  } = await import('./proxy.js'); // automatically stringify body content
+
+  if (body && typeof body !== 'string') {
+    headers = {
+      'Content-Type': 'application/json',
+      ...headers
+    };
+    body = JSON.stringify(body);
+  } // combine request options
+
+
+  Object.assign(requestOptions, {
+    agent: requestOptions.agent || !noProxy && proxyAgentFor(url) || null,
+    path: pathname + search + hash,
+    protocol,
+    hostname,
+    headers,
+    port
+  });
+  return retry((resolve, reject, retry) => {
+    let handleError = error => {
+      if (handleError.handled) return;
+      handleError.handled = true; // maybe retry 404s, always retry 500s, or retry specific errors
+
+      let shouldRetry = error.response ? retryNotFound && error.response.statusCode === 404 || error.response.statusCode >= 500 && error.response.statusCode < 600 : !!error.code && RETRY_ERROR_CODES.includes(error.code);
+      return shouldRetry ? retry(error) : reject(error);
+    };
+
+    let handleFinished = async (body, res) => {
+      let {
+        statusCode,
+        headers
+      } = res;
+      let raw = body; // attempt to parse the body as json
+
+      try {
+        body = JSON.parse(body);
+      } catch (e) {}
+
+      try {
+        if (statusCode >= 200 && statusCode < 300) {
+          var _callback;
+
+          resolve((await ((_callback = callback) === null || _callback === void 0 ? void 0 : _callback(body, res))) ?? body);
+        } else {
+          var _body, _body$errors, _body$errors$find;
+
+          let err = (_body = body) === null || _body === void 0 ? void 0 : (_body$errors = _body.errors) === null || _body$errors === void 0 ? void 0 : (_body$errors$find = _body$errors.find(e => e.detail)) === null || _body$errors$find === void 0 ? void 0 : _body$errors$find.detail;
+          throw new Error(err || `${statusCode} ${res.statusMessage || raw}`);
+        }
+      } catch (error) {
+        let response = {
+          statusCode,
+          headers,
+          body
+        };
+        handleError(Object.assign(error, {
+          response
+        }));
+      }
+    };
+
+    let handleResponse = res => {
+      let body = '';
+      res.setEncoding('utf-8');
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => handleFinished(body, res));
+      res.on('error', handleError);
+    };
+
+    let req = http.request(requestOptions);
+    req.on('response', handleResponse);
+    req.on('error', handleError);
+    req.end(body);
+  }, {
+    retries,
+    interval
+  });
+}
+export { hostnameMatches, ProxyHttpAgent, ProxyHttpsAgent, proxyAgentFor } from './proxy.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/client",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,8 +14,8 @@
     "node": ">=14"
   },
   "files": [
-    "./dist",
-    "./test/helpers.js"
+    "dist",
+    "test/helpers.js"
   ],
   "main": "./dist/index.js",
   "type": "module",
@@ -31,8 +31,8 @@
     "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
-    "@percy/env": "1.0.0",
-    "@percy/logger": "1.0.0"
+    "@percy/env": "1.0.1",
+    "@percy/logger": "1.0.1"
   },
-  "gitHead": "6df509421a60144e4f9f5d59dc57a5675372a0b2"
+  "gitHead": "38917e6027299d6cd86008e2ccd005d90bbf89c0"
 }

package/test/helpers.js

@@ -0,0 +1,152 @@
+import EventEmitter from 'events';
+import url from 'url';
+
+// Mock response class used for mock requests
+export class MockResponse extends EventEmitter {
+  constructor(options) {
+    Object.assign(super(), options);
+  }
+
+  resume() {}
+  setEncoding() {}
+  pipe = stream => this
+    .on('data', d => stream.write(d))
+    .on('end', () => stream.end());
+};
+
+// Mock request class automates basic mocking necessities
+export class MockRequest extends EventEmitter {
+  constructor(reply, url, opts, cb) {
+    // handle optional url string
+    if (url && typeof url === 'string') {
+      let { protocol, hostname, port, pathname, search, hash } = new URL(url);
+      opts = { ...opts, protocol, hostname, port, path: pathname + search + hash };
+    } else if (typeof url !== 'string') {
+      opts = url;
+    }
+
+    Object.assign(super(), opts, { reply });
+    if (cb) this.on('response', cb);
+  }
+
+  // useful for logs/tests
+  get url() {
+    return new URL(this.path, url.format(this)).href;
+  }
+
+  // kick off a reply response on request end
+  end(body) {
+    // process async but return sync
+    (async () => {
+      try { this.body = JSON.parse(body); } catch {}
+      let [statusCode, data = '', headers = {}] = await this.reply?.(this) ?? [];
+
+      if (data && typeof data !== 'string') {
+        // handle common json data
+        headers['content-type'] = headers['content-type'] || 'application/json';
+        data = JSON.stringify(data);
+      } else if (!statusCode) {
+        // no status code was mocked
+        data = `Not mocked ${this.url}`;
+        statusCode = 404;
+      }
+
+      // automate content-length header
+      if (data != null && !headers['content-length']) {
+        headers['content-length'] = Buffer.byteLength(data);
+      }
+
+      // create and trigger a mock response
+      let res = new MockResponse({ statusCode, headers });
+      this.emit('response', res);
+
+      // maybe delay response data
+      setTimeout(() => {
+        res.emit('data', data);
+        res.emit('end');
+      }, this.delay);
+    })();
+
+    return this;
+  }
+}
+
+// Mock request responses using jasmine spies
+export async function mockRequests(baseUrl, defaultReply = () => [200]) {
+  let { protocol, hostname, pathname } = new URL(baseUrl);
+  let { default: http } = await import(protocol === 'https:' ? 'https' : 'http');
+
+  if (!jasmine.isSpy(http.request)) {
+    spyOn(http, 'request').and.callFake((...a) => new MockRequest(null, ...a));
+    spyOn(http, 'get').and.callFake((...a) => new MockRequest(null, ...a).end());
+  }
+
+  let any = jasmine.anything();
+  let match = o => o.hostname === hostname &&
+    (o.path ?? o.pathname).startsWith(pathname);
+  let reply = jasmine.createSpy('reply').and.callFake(defaultReply);
+
+  http.request.withArgs({ asymmetricMatch: match })
+    .and.callFake((...a) => new MockRequest(reply, ...a));
+  http.get.withArgs({ asymmetricMatch: u => match(new URL(u)) }, any, any)
+    .and.callFake((...a) => new MockRequest(reply, ...a).end());
+
+  return reply;
+}
+
+// Group of helpers to mock Percy API requests
+export const api = {
+  DEFAULT_REPLIES: {
+    '/builds': () => [201, {
+      data: {
+        id: '123',
+        attributes: {
+          'build-number': 1,
+          'web-url': 'https://percy.io/test/test/123'
+        }
+      }
+    }],
+
+    '/builds/123/snapshots': ({ body }) => [201, {
+      data: {
+        id: '4567',
+        attributes: body.attributes,
+        relationships: {
+          'missing-resources': {
+            data: body.data.relationships.resources
+              .data.map(({ id }) => ({ id }))
+          }
+        }
+      }
+    }]
+  },
+
+  async mock({ delay = 10 } = {}) {
+    this.replies = {};
+    this.requests = {};
+
+    await mockRequests('https://percy.io/api/v1', req => {
+      let path = req.path.replace('/api/v1', '');
+
+      let reply = (this.replies[path] && (
+        this.replies[path].length > 1
+          ? this.replies[path].shift()
+          : this.replies[path][0]
+      )) || this.DEFAULT_REPLIES[path];
+
+      this.requests[path] = this.requests[path] || [];
+      this.requests[path].push(req);
+
+      if (delay) req.delay = delay;
+      return reply?.(req) ?? [200];
+    });
+  },
+
+  reply(path, handler) {
+    this.replies[path] = this.replies[path] || [];
+    this.replies[path].push(handler);
+    return this;
+  }
+};
+
+export default api;