@percy/core 1.0.0 → 1.0.1

package/dist/snapshot.js

@@ -0,0 +1,433 @@
+import logger from '@percy/logger';
+import PercyConfig from '@percy/config';
+import micromatch from 'micromatch';
+import { configSchema } from './config.js';
+import { request, hostnameMatches, createRootResource, createPercyCSSResource, createLogResource } from './utils.js'; // Throw a better error message for missing or invalid urls
+
+export function validURL(url, base) {
+  if (!url) {
+    throw new Error('Missing required URL for snapshot');
+  }
+
+  try {
+    return new URL(url, base);
+  } catch (e) {
+    throw new Error(`Invalid snapshot URL: ${e.input}`);
+  }
+} // used to deserialize regular expression strings
+
+const RE_REGEXP = /^\/(.+)\/(\w+)?$/; // Returns true or false if a snapshot matches the provided include and exclude predicates. A
+// predicate can be an array of predicates, a regular expression, a glob pattern, or a function.
+
+export function snapshotMatches(snapshot, include, exclude) {
+  var _include, _include2;
+
+  // support an options object as the second argument
+  if ((_include = include) !== null && _include !== void 0 && _include.include || (_include2 = include) !== null && _include2 !== void 0 && _include2.exclude) ({
+    include,
+    exclude
+  } = include); // recursive predicate test function
+
+  let test = (predicate, fallback) => {
+    if (predicate && typeof predicate === 'string') {
+      // snapshot name matches exactly or matches a glob
+      let result = snapshot.name === predicate || micromatch.isMatch(snapshot.name, predicate, {
+        basename: !predicate.startsWith('/')
+      }); // snapshot might match a string-based regexp pattern
+
+      if (!result) {
+        try {
+          let [, parsed = predicate, flags] = RE_REGEXP.exec(predicate) || [];
+          result = new RegExp(parsed, flags).test(snapshot.name);
+        } catch {}
+      }
+
+      return result;
+    } else if (predicate instanceof RegExp) {
+      // snapshot matches a regular expression
+      return predicate.test(snapshot.name);
+    } else if (typeof predicate === 'function') {
+      // advanced matching
+      return predicate(snapshot);
+    } else if (Array.isArray(predicate) && predicate.length) {
+      // array of predicates
+      return predicate.some(p => test(p));
+    } else {
+      // default fallback
+      return fallback;
+    }
+  }; // nothing to match, return true
+
+
+  if (!include && !exclude) return true; // not excluded or explicitly included
+
+  return !test(exclude, false) && test(include, true);
+} // Accepts an array of snapshots to filter and map with matching options.
+
+export function mapSnapshotOptions(percy, snapshots, config) {
+  if (!(snapshots !== null && snapshots !== void 0 && snapshots.length)) return []; // reduce options into a single function
+
+  let applyOptions = [].concat((config === null || config === void 0 ? void 0 : config.options) || []).reduceRight((next, {
+    include,
+    exclude,
+    ...opts
+  }) => snap => next( // assign additional options to included snaphots
+  snapshotMatches(snap, include, exclude) ? Object.assign(snap, opts) : snap), s => getSnapshotConfig(percy, s)); // reduce snapshots with overrides
+
+  return snapshots.reduce((acc, snapshot) => {
+    var _snapshot;
+
+    // transform snapshot URL shorthand into an object
+    if (typeof snapshot === 'string') snapshot = {
+      url: snapshot
+    }; // normalize the snapshot url and use it for the default name
+
+    let url = validURL(snapshot.url, config === null || config === void 0 ? void 0 : config.baseUrl);
+    (_snapshot = snapshot).name || (_snapshot.name = `${url.pathname}${url.search}${url.hash}`);
+    snapshot.url = url.href; // use the snapshot when matching include/exclude
+
+    if (snapshotMatches(snapshot, config)) {
+      acc.push(applyOptions(snapshot));
+    }
+
+    return acc;
+  }, []);
+} // Returns an array of derived snapshot options
+
+export async function gatherSnapshots(percy, options) {
+  let {
+    baseUrl,
+    snapshots
+  } = options;
+  if ('url' in options) snapshots = [options];
+  if ('sitemap' in options) snapshots = await getSitemapSnapshots(options); // validate evaluated snapshots
+
+  if (typeof snapshots === 'function') {
+    ({
+      snapshots
+    } = validateSnapshotOptions({
+      baseUrl,
+      snapshots: await snapshots(baseUrl)
+    }));
+  } // map snapshots with snapshot options
+
+
+  snapshots = mapSnapshotOptions(percy, snapshots, options);
+  if (!snapshots.length) throw new Error('No snapshots found');
+  return snapshots;
+} // Validates and migrates snapshot options against the correct schema based on provided
+// properties. Eagerly throws an error when missing a URL for any snapshot, and warns about all
+// other invalid options which are also scrubbed from the returned migrated options.
+
+export function validateSnapshotOptions(options) {
+  let schema; // decide which schema to validate against
+
+  if ('domSnapshot' in options) {
+    schema = '/snapshot/dom';
+  } else if ('url' in options) {
+    schema = '/snapshot';
+  } else if ('sitemap' in options) {
+    schema = '/snapshot/sitemap';
+  } else if ('serve' in options) {
+    schema = '/snapshot/server';
+  } else if ('snapshots' in options) {
+    schema = '/snapshot/list';
+  } else {
+    schema = '/snapshot';
+  }
+
+  let {
+    // migrate and remove certain properties from validating
+    clientInfo,
+    environmentInfo,
+    snapshots,
+    ...migrated
+  } = PercyConfig.migrate(options, schema); // gather info for validating individual snapshot URLs
+
+  let isSnapshot = schema === '/snapshot/dom' || schema === '/snapshot';
+  let baseUrl = schema === '/snapshot/server' ? 'http://localhost' : options.baseUrl;
+  let snaps = isSnapshot ? [migrated] : Array.isArray(snapshots) ? snapshots : [];
+
+  for (let snap of snaps) validURL(typeof snap === 'string' ? snap : snap.url, baseUrl); // add back snapshots before validating and scrubbing; function snapshots are validated later
+
+
+  if (snapshots) migrated.snapshots = typeof snapshots === 'function' ? [] : snapshots;
+  let errors = PercyConfig.validate(migrated, schema);
+
+  if (errors) {
+    // warn on validation errors
+    let log = logger('core:snapshot');
+    log.warn('Invalid snapshot options:');
+
+    for (let e of errors) log.warn(`- ${e.path}: ${e.message}`);
+  } // add back the snapshots function if there was one
+
+
+  if (typeof snapshots === 'function') migrated.snapshots = snapshots; // add back an empty array if all server snapshots were scrubbed
+
+  if ('serve' in options && 'snapshots' in options) migrated.snapshots ?? (migrated.snapshots = []);
+  return {
+    clientInfo,
+    environmentInfo,
+    ...migrated
+  };
+} // Fetches a sitemap and parses it into a list of URLs for taking snapshots. Duplicate URLs,
+// including a trailing slash, are removed from the resulting list.
+
+export async function getSitemapSnapshots(options) {
+  return request(options.sitemap, (body, res) => {
+    // validate sitemap content-type
+    let [contentType] = res.headers['content-type'].split(';');
+
+    if (!/^(application|text)\/xml$/.test(contentType)) {
+      throw new Error('The sitemap must be an XML document, ' + `but the content-type was "${contentType}"`);
+    } // parse XML content into a list of URLs
+
+
+    let urls = body.match(/(?<=<loc>)(.*)(?=<\/loc>)/ig) ?? []; // filter out duplicate URLs that differ by a trailing slash
+
+    return urls.filter((url, i) => {
+      let match = urls.indexOf(url.replace(/\/$/, ''));
+      return match === -1 || match === i;
+    });
+  });
+} // Return snapshot options merged with defaults and global options.
+
+export function getSnapshotConfig(percy, options) {
+  return PercyConfig.merge([{
+    widths: configSchema.snapshot.properties.widths.default,
+    discovery: {
+      allowedHostnames: [validURL(options.url).hostname]
+    },
+    meta: {
+      snapshot: {
+        name: options.name
+      },
+      build: percy.build
+    }
+  }, percy.config.snapshot, {
+    // only specific discovery options are used per-snapshot
+    discovery: {
+      allowedHostnames: percy.config.discovery.allowedHostnames,
+      disallowedHostnames: percy.config.discovery.disallowedHostnames,
+      networkIdleTimeout: percy.config.discovery.networkIdleTimeout,
+      requestHeaders: percy.config.discovery.requestHeaders,
+      authorization: percy.config.discovery.authorization,
+      disableCache: percy.config.discovery.disableCache,
+      userAgent: percy.config.discovery.userAgent
+    }
+  }, options], (path, prev, next) => {
+    var _next;
+
+    switch (path.map(k => k.toString()).join('.')) {
+      case 'widths':
+        // dedup, sort, and override widths when not empty
+        return [path, (_next = next) !== null && _next !== void 0 && _next.length ? Array.from(new Set(next)).sort((a, b) => a - b) : prev];
+
+      case 'percyCSS':
+        // concatenate percy css
+        return [path, [prev, next].filter(Boolean).join('\n')];
+
+      case 'execute':
+        // shorthand for execute.beforeSnapshot
+        return Array.isArray(next) || typeof next !== 'object' ? [path.concat('beforeSnapshot'), next] : [path];
+
+      case 'discovery.disallowedHostnames':
+        // prevent disallowing the root hostname
+        return [path, (prev ?? []).concat(next).filter(h => !hostnameMatches(h, options.url))];
+    } // ensure additional snapshots have complete names
+
+
+    if (path[0] === 'additionalSnapshots' && path.length === 2) {
+      let {
+        prefix = '',
+        suffix = '',
+        ...n
+      } = next;
+      next = {
+        name: `${prefix}${options.name}${suffix}`,
+        ...n
+      };
+      return [path, next];
+    }
+  });
+} // Returns a complete and valid snapshot config object and logs verbose debug logs detailing various
+// snapshot options. When `showInfo` is true, specific messages will be logged as info logs rather
+// than debug logs.
+
+function debugSnapshotConfig(snapshot, showInfo) {
+  let log = logger('core:snapshot'); // log snapshot info
+
+  log.debug('---------', snapshot.meta);
+  if (showInfo) log.info(`Snapshot found: ${snapshot.name}`, snapshot.meta);else log.debug(`Handling snapshot: ${snapshot.name}`, snapshot.meta); // will log debug info for an object property if its value is defined
+
+  let debugProp = (obj, prop, format = String) => {
+    let val = prop.split('.').reduce((o, k) => o === null || o === void 0 ? void 0 : o[k], obj);
+
+    if (val != null) {
+      // join formatted array values with a space
+      val = [].concat(val).map(format).join(', ');
+      log.debug(`- ${prop}: ${val}`, snapshot.meta);
+    }
+  };
+
+  debugProp(snapshot, 'url');
+  debugProp(snapshot, 'widths', v => `${v}px`);
+  debugProp(snapshot, 'minHeight', v => `${v}px`);
+  debugProp(snapshot, 'enableJavaScript');
+  debugProp(snapshot, 'waitForTimeout');
+  debugProp(snapshot, 'waitForSelector');
+  debugProp(snapshot, 'execute.afterNavigation');
+  debugProp(snapshot, 'execute.beforeResize');
+  debugProp(snapshot, 'execute.afterResize');
+  debugProp(snapshot, 'execute.beforeSnapshot');
+  debugProp(snapshot, 'discovery.allowedHostnames');
+  debugProp(snapshot, 'discovery.disallowedHostnames');
+  debugProp(snapshot, 'discovery.requestHeaders', JSON.stringify);
+  debugProp(snapshot, 'discovery.authorization', JSON.stringify);
+  debugProp(snapshot, 'discovery.disableCache');
+  debugProp(snapshot, 'discovery.userAgent');
+  debugProp(snapshot, 'clientInfo');
+  debugProp(snapshot, 'environmentInfo');
+  debugProp(snapshot, 'domSnapshot', Boolean);
+
+  for (let added of snapshot.additionalSnapshots || []) {
+    if (showInfo) log.info(`Snapshot found: ${added.name}`, snapshot.meta);else log.debug(`Additional snapshot: ${added.name}`, snapshot.meta);
+    debugProp(added, 'waitForTimeout');
+    debugProp(added, 'waitForSelector');
+    debugProp(added, 'execute');
+  }
+} // Calls the provided callback with additional resources
+
+
+function handleSnapshotResources(snapshot, map, callback) {
+  let resources = [...map.values()]; // sort the root resource first
+
+  let [root] = resources.splice(resources.findIndex(r => r.root), 1);
+  resources.unshift(root); // inject Percy CSS
+
+  if (snapshot.percyCSS) {
+    let css = createPercyCSSResource(root.url, snapshot.percyCSS);
+    resources.push(css); // replace root contents and associated properties
+
+    Object.assign(root, createRootResource(root.url, root.content.replace(/(<\/body>)(?!.*\1)/is, `<link data-percy-specific-css rel="stylesheet" href="${css.pathname}"/>` + '$&')));
+  } // include associated snapshot logs matched by meta information
+
+
+  resources.push(createLogResource(logger.query(log => {
+    var _log$meta$snapshot;
+
+    return ((_log$meta$snapshot = log.meta.snapshot) === null || _log$meta$snapshot === void 0 ? void 0 : _log$meta$snapshot.name) === snapshot.meta.snapshot.name;
+  })));
+  return callback(snapshot, resources);
+} // Wait for a page's asset discovery network to idle
+
+
+function waitForDiscoveryNetworkIdle(page, options) {
+  let {
+    allowedHostnames,
+    networkIdleTimeout
+  } = options;
+
+  let filter = r => hostnameMatches(allowedHostnames, r.url);
+
+  return page.network.idle(filter, networkIdleTimeout);
+} // Used to cache resources across core instances
+
+
+const RESOURCE_CACHE_KEY = Symbol('resource-cache'); // Discovers resources for a snapshot using a browser page to intercept requests. The callback
+// function will be called with the snapshot name (for additional snapshots) and an array of
+// discovered resources. When additional snapshots are provided, the callback will be called once
+// for each snapshot.
+
+export async function* discoverSnapshotResources(percy, snapshot, callback) {
+  debugSnapshotConfig(snapshot, percy.dryRun); // when dry-running, invoke the callback for each snapshot and immediately return
+
+  let allSnapshots = [snapshot, ...(snapshot.additionalSnapshots || [])];
+  if (percy.dryRun) return allSnapshots.map(s => callback(s)); // keep a global resource cache across snapshots
+
+  let cache = percy[RESOURCE_CACHE_KEY] || (percy[RESOURCE_CACHE_KEY] = new Map()); // copy widths to prevent mutation later
+
+  let widths = snapshot.widths.slice(); // preload the root resource for existing dom snapshots
+
+  let resources = new Map(snapshot.domSnapshot && [createRootResource(snapshot.url, snapshot.domSnapshot)].map(resource => [resource.url, resource])); // open a new browser page
+
+  let page = yield percy.browser.page({
+    enableJavaScript: snapshot.enableJavaScript ?? !snapshot.domSnapshot,
+    networkIdleTimeout: snapshot.discovery.networkIdleTimeout,
+    requestHeaders: snapshot.discovery.requestHeaders,
+    authorization: snapshot.discovery.authorization,
+    userAgent: snapshot.discovery.userAgent,
+    meta: snapshot.meta,
+    // enable network inteception
+    intercept: {
+      enableJavaScript: snapshot.enableJavaScript,
+      disableCache: snapshot.discovery.disableCache,
+      allowedHostnames: snapshot.discovery.allowedHostnames,
+      disallowedHostnames: snapshot.discovery.disallowedHostnames,
+      getResource: u => resources.get(u) || cache.get(u),
+      saveResource: r => resources.set(r.url, r) && cache.set(r.url, r)
+    }
+  });
+
+  try {
+    var _snapshot$execute;
+
+    // set the initial page size
+    yield page.resize({
+      width: widths.shift(),
+      height: snapshot.minHeight
+    }); // navigate to the url
+
+    yield page.goto(snapshot.url);
+    yield page.evaluate((_snapshot$execute = snapshot.execute) === null || _snapshot$execute === void 0 ? void 0 : _snapshot$execute.afterNavigation); // trigger resize events for other widths
+
+    for (let width of widths) {
+      var _snapshot$execute2, _snapshot$execute3;
+
+      yield page.evaluate((_snapshot$execute2 = snapshot.execute) === null || _snapshot$execute2 === void 0 ? void 0 : _snapshot$execute2.beforeResize);
+      yield waitForDiscoveryNetworkIdle(page, snapshot.discovery);
+      yield page.resize({
+        width,
+        height: snapshot.minHeight
+      });
+      yield page.evaluate((_snapshot$execute3 = snapshot.execute) === null || _snapshot$execute3 === void 0 ? void 0 : _snapshot$execute3.afterResize);
+    }
+
+    if (snapshot.domSnapshot) {
+      // ensure discovery has finished and handle resources
+      yield waitForDiscoveryNetworkIdle(page, snapshot.discovery);
+      handleSnapshotResources(snapshot, resources, callback);
+    } else {
+      let {
+        enableJavaScript
+      } = snapshot; // capture snapshots sequentially
+
+      for (let snap of allSnapshots) {
+        // will wait for timeouts, selectors, and additional network activity
+        let {
+          url,
+          dom
+        } = yield page.snapshot({
+          enableJavaScript,
+          ...snap
+        });
+        let root = createRootResource(url, dom); // use the normalized root url to prevent duplicates
+
+        resources.set(root.url, root); // shallow merge with root snapshot options
+
+        handleSnapshotResources({ ...snapshot,
+          ...snap
+        }, resources, callback); // remove the previously captured dom snapshot
+
+        resources.delete(root.url);
+      }
+    } // page clean up
+
+
+    await page.close();
+  } catch (error) {
+    await page.close();
+    throw error;
+  }
+}

package/dist/utils.js

@@ -0,0 +1,127 @@
+import { sha256hash } from '@percy/client/utils';
+export { request, getPackageJSON, hostnameMatches } from '@percy/client/utils'; // Returns the hostname portion of a URL.
+
+export function hostname(url) {
+  return new URL(url).hostname;
+} // Normalizes a URL by stripping hashes to ensure unique resources.
+
+export function normalizeURL(url) {
+  let {
+    protocol,
+    host,
+    pathname,
+    search
+  } = new URL(url);
+  return `${protocol}//${host}${pathname}${search}`;
+} // Creates a local resource object containing the resource URL, mimetype, content, sha, and any
+// other additional resources attributes.
+
+export function createResource(url, content, mimetype, attrs) {
+  return { ...attrs,
+    sha: sha256hash(content),
+    mimetype,
+    content,
+    url
+  };
+} // Creates a root resource object with an additional `root: true` property. The URL is normalized
+// here as a convenience since root resources are usually created outside of asset discovery.
+
+export function createRootResource(url, content) {
+  return createResource(normalizeURL(url), content, 'text/html', {
+    root: true
+  });
+} // Creates a Percy CSS resource object.
+
+export function createPercyCSSResource(url, css) {
+  let {
+    href,
+    pathname
+  } = new URL(`/percy-specific.${Date.now()}.css`, url);
+  return createResource(href, css, 'text/css', {
+    pathname
+  });
+} // Creates a log resource object.
+
+export function createLogResource(logs) {
+  return createResource(`/percy.${Date.now()}.log`, JSON.stringify(logs), 'text/plain');
+} // Creates a thennable, cancelable, generator instance
+
+export function generatePromise(gen) {
+  var _gen, _gen2;
+
+  // ensure a generator is provided
+  if (typeof gen === 'function') gen = gen();
+  if (typeof ((_gen = gen) === null || _gen === void 0 ? void 0 : _gen.then) === 'function') return gen;
+  if (typeof ((_gen2 = gen) === null || _gen2 === void 0 ? void 0 : _gen2.next) !== 'function' || !(typeof gen[Symbol.iterator] === 'function' || typeof gen[Symbol.asyncIterator] === 'function')) return Promise.resolve(gen); // used to trigger cancelation
+
+  class Canceled extends Error {
+    name = 'Canceled';
+    canceled = true;
+  } // recursively runs the generator, maybe throwing an error when canceled
+
+
+  let handleNext = async (g, last) => {
+    let canceled = g.cancel.triggered;
+    let {
+      done,
+      value
+    } = canceled ? await g.throw(canceled) : await g.next(last);
+    if (canceled) delete g.cancel.triggered;
+    return done ? value : handleNext(g, value);
+  }; // handle cancelation errors by calling any cancel handlers
+
+
+  let cancelable = async function* () {
+    try {
+      return yield* gen;
+    } catch (error) {
+      if (error.canceled) {
+        let cancelers = cancelable.cancelers || [];
+
+        for (let c of cancelers) await c(error);
+      }
+
+      throw error;
+    }
+  }(); // augment the cancelable generator with promise-like and cancel methods
+
+
+  return Object.assign(cancelable, {
+    run: () => cancelable.promise || (cancelable.promise = handleNext(cancelable)),
+    then: (resolve, reject) => cancelable.run().then(resolve, reject),
+    catch: reject => cancelable.run().catch(reject),
+    cancel: message => {
+      cancelable.cancel.triggered = new Canceled(message);
+      return cancelable;
+    },
+    canceled: handler => {
+      (cancelable.cancelers || (cancelable.cancelers = [])).push(handler);
+      return cancelable;
+    }
+  });
+} // Resolves when the predicate function returns true within the timeout. If an idle option is
+// provided, the predicate will be checked again before resolving, after the idle period. The poll
+// option determines how often the predicate check will be run.
+
+export function waitFor(predicate, options) {
+  let {
+    poll = 10,
+    timeout,
+    idle
+  } = Number.isInteger(options) ? {
+    timeout: options
+  } : options || {};
+  return generatePromise(async function* check(start, done) {
+    while (true) {
+      if (timeout && Date.now() - start >= timeout) {
+        throw new Error(`Timeout of ${timeout}ms exceeded.`);
+      } else if (!predicate()) {
+        yield new Promise(r => setTimeout(r, poll, done = false));
+      } else if (idle && !done) {
+        yield new Promise(r => setTimeout(r, idle, done = true));
+      } else {
+        return;
+      }
+    }
+  }(Date.now()));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,10 +14,10 @@
     "node": ">=14"
   },
   "files": [
-    "./dist",
-    "./post-install.js",
-    "./types/index.d.ts",
-    "./test/helpers/server.js"
+    "dist",
+    "post-install.js",
+    "types/index.d.ts",
+    "test/helpers/server.js"
   ],
   "main": "./dist/index.js",
   "types": "types/index.d.ts",
@@ -38,10 +38,10 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/client": "1.0.0",
-    "@percy/config": "1.0.0",
-    "@percy/dom": "1.0.0",
-    "@percy/logger": "1.0.0",
+    "@percy/client": "1.0.1",
+    "@percy/config": "1.0.1",
+    "@percy/dom": "1.0.1",
+    "@percy/logger": "1.0.1",
     "content-disposition": "^0.5.4",
     "cross-spawn": "^7.0.3",
     "extract-zip": "^2.0.1",
@@ -52,5 +52,5 @@
     "rimraf": "^3.0.2",
     "ws": "^8.0.0"
   },
-  "gitHead": "6df509421a60144e4f9f5d59dc57a5675372a0b2"
+  "gitHead": "38917e6027299d6cd86008e2ccd005d90bbf89c0"
 }

package/post-install.js

@@ -0,0 +1,20 @@
+import fs from 'fs';
+
+try {
+  if (process.env.PERCY_POSTINSTALL_BROWSER) {
+    // Automatically download and install Chromium if PERCY_POSTINSTALL_BROWSER is set
+    await import('./dist/install.js').then(install => install.chromium());
+  } else if (!process.send && fs.existsSync('./src')) {
+    // In development, fork this script with the development loader and always install
+    await import('child_process').then(cp => cp.fork('./post-install.js', {
+      execArgv: ['--no-warnings', '--loader=../../scripts/loader.js'],
+      env: { PERCY_POSTINSTALL_BROWSER: true }
+    }));
+  }
+} catch (error) {
+  const { logger } = await import('@percy/logger');
+  const log = logger('core:post-install');
+
+  log.error('Encountered an error while installing Chromium');
+  log.error(error);
+}

package/test/helpers/server.js

@@ -0,0 +1,33 @@
+// aliased to src for coverage during tests without needing to compile this file
+import Server from '../../dist/server.js';
+
+export function createTestServer({ default: defaultReply, ...replies }, port = 8000) {
+  let server = new Server();
+
+  // alternate route handling
+  let handleReply = reply => async (req, res) => {
+    let [status, headers, body] = typeof reply === 'function' ? await reply(req) : reply;
+    if (!Buffer.isBuffer(body) && typeof body !== 'string') body = JSON.stringify(body);
+    return res.send(status, headers, body);
+  };
+
+  // map replies to alternate route handlers
+  server.reply = (p, reply) => (replies[p] = handleReply(reply), null);
+  for (let [p, reply] of Object.entries(replies)) server.reply(p, reply);
+  if (defaultReply) defaultReply = handleReply(defaultReply);
+
+  // track requests and route replies
+  server.requests = [];
+  server.route(async (req, res, next) => {
+    let pathname = req.url.pathname;
+    if (req.url.search) pathname += req.url.search;
+    server.requests.push(req.body ? [pathname, req.body] : [pathname]);
+    let reply = replies[req.url.pathname] || defaultReply;
+    return reply ? await reply(req, res) : next();
+  });
+
+  // automatically listen
+  return server.listen(port);
+};
+
+export default createTestServer;