@zombieland/tallahassee 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-04-22
+
+Initial release.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Jonas Waldén
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# Tallahassee
+
+A browser module around JSDOM for testing a web application as opposed to a document. Navigation with headers, cookies, clicks and form submits.
+
+> I really want the name Tallahassee to remain, although Columbus sounds more _browsery_.
+
+## Table of Contents
+
+- [Basic usage](#basic-usage)
+- [API](#api)
+  - [Browser](#browser)
+    - [new Browser(origin[, cookieJar])](#new-browserorigin-cookiejar)
+    - [browser.navigateTo(resource[, fetchOptions, loadOptions])](#browsernavigatetoResource-fetchoptions-loadoptions)
+    - [browser.fetch(resource[, options])](#browserfetchresource-options)
+    - [browser.load(resource[, options])](#browserloadresource-options)
+    - [browser.captureNavigation(dom[, follow])](#browsercapturenavigationdom-follow)
+  - [ReverseProxy](#reverseproxy)
+    - [new ReverseProxy(proxyOrigin, upstreamOrigin[, headers])](#new-reverseproxyproxyorigin-upstreamorigin-headers)
+    - [reverseProxy.modifyUpstreamRequest(req)](#reverseproxymodifyupstreamrequestreq)
+    - [reverseProxy.clear()](#reverseproxyclear)
+
+## Basic usage
+
+```js
+import assert from 'node:assert/strict';
+import { Browser } from '@zombieland/tallahassee';
+
+let browser;
+before('a browser with a default origin', () => {
+	browser = new Browser('http://localhost:7411');
+});
+
+test('simple navigation', () => {
+	const dom = await browser.navigateTo('/');
+	assert.equal(dom.window.document.title, 'Zombieland');
+});
+
+test('detailed navigation', () => {
+	const response = await browser.fetch('/', {
+		headers: { 'Cookie': 'signed-in=1' },
+	});
+	assert.equal(response.status, 200);
+
+	const dom = await browser.load(response, { runScripts: 'dangerously' });
+	assert.equal(dom.window.document.title, 'Zombieland');
+});
+```
+
+## API
+
+### `Browser`
+
+A module for testing navigation within an origin
+
+```js
+import { Browser } from '@zombieland/tallahassee';
+```
+
+#### `new Browser(origin[, cookieJar])`
+
+Creates a new browser instance
+
+- `origin` `<string>` Base URL used by `browser.fetch`
+- `cookieJar` `<CookieJar>` A [jar of cookies](https://github.com/jsdom/jsdom/blob/main/README.md#cookie-jars) to be used by `browser.fetch` method. **Default** `new CookieJar()`
+
+#### `browser.navigateTo(resource[, fetchOptions, loadOptions])`
+
+Fetches a document and loads a DOM
+
+- `resource` Passed on to `browser.fetch`
+- `fetchOptions` Passed on to `browser.fetch`
+- `loadOptions` Passed on to `browser.load`.
+- Returns: `<Promise>` Fulfills with a `JSDOM` on success
+
+```js
+const dom = await browser.navigateTo(
+	'/',
+	{ headers: { 'Cookie'; 'some-cookie=value' } },
+	{ runScripts: 'dangerously' }
+);
+```
+
+#### `browser.fetch(resource[, options])`
+
+Fetches a document. Useful for inspecting response details before loading DOM with `browser.load()`.
+
+- `resource` `<string>` | `<URL>` | `<Request>` path (relative to the browser origin) / URL to a document or a request object
+- `options` `<Object>` A `RequestInit` dictionary
+- Returns: `<Promise>` Fulfills with a `Response` on success
+
+```js
+const pendingResponse = browser.fetch('/', {
+	headers: { 'Cookie'; 'some-cookie=value' }
+});
+```
+
+Any request `Cookie` header will be applied to `browser.cookieJar` before actual `fetch()`.
+
+Any response `Set-Cookie` will be applied to `browser.cookieJar` before creating `new JSDOM()`.
+
+Redirects are followed manually with recursive calls to `browser.fetch` in order to properly set/get cookies from `browser.cookieJar`.
+
+#### `browser.load(resource[, options])`
+
+Loads a DOM from a document string or response
+
+- `resource` `<string>` | `<Response>` | `<Promise>` A document string or response string to load into JSDOM
+- `options` `<Object>` `{[painter, resources, ...jsdomOptions]}`
+	- `painter`: `<Painter>` Little Rock `Painter` instance
+	- `resources`: `<Resources>` Wichita `Resources` instance
+	- `jsdomOptions`: `<Object>` [Options to be passed onto JSDOM](https://github.com/jsdom/jsdom/blob/main/README.md#customizing-jsdom)
+		- **Default**:
+			- `runScripts`: `'outside-only'` if `options.painter`
+			- `pretendToBeVisual`: `true` if `options.painter`
+		- **Fixed values**:
+			- `url`: `url` from `resource` if instance of `Response`
+			- `contentType`: `Content-Type` response header from `resource` if instance of `Response`
+			- `cookieJar`: `cookieJar` from `browser` instance
+			- `beforeParse`: A function that will run:
+				- `options.painter?.beforeParse`: From a Little Rock `Painter` instance
+				- `options.resources?.beforeParse`: From a Wichita `Resources` instance
+				- `options.beforeParse`
+- Returns: `<Promise>` Fulfills with a `JSDOM` on success
+
+```js
+const dom = await browser.load(pendingResponse, {
+	runScripts: 'dangerously'
+});
+```
+
+If using Little Rock and/or Wichita their `beforeParse` methods will be run automatically if passed into `options`:
+
+```js
+import { Browser } from "@zombieland/tallahassee";
+import { Painter } from "@zombieland/little-rock";
+import { ResourceLoader } from "@zombieland/wichita";
+
+const browser = new Browser(…);
+const pendingResponse = browser.fetch('/');
+const dom = await browser.load(pendingResponse, {
+	painter: new Painter(…),
+	resources: new ResourceLoader(…),
+});
+```
+
+#### `browser.captureNavigation(dom[, follow])`
+
+Captures navigation from link clicks and form submits.
+
+- `dom` `<JSDOM>` A DOM to observe
+- `follow` `<Boolean>` To follow request or not. **Default** `false`
+- Returns: `<Promise>` Resolves with a `<Request>` or `<Response>` from `fetch` if `follow: true`. Rejects with an `Event` which blocked the navigation.
+
+```js
+const linkOrFormSubmit = dom.window.querySelector('a, button[type=submit]');
+
+const pendingNavigation = browser.captureNavigation(dom, false);
+linkOrFormSubmit.click();
+const request = await pendingNavigation;
+assert(request instanceof Request);
+```
+
+Or with `follow: true` to perform a call to `browser.fetch()`
+
+```js
+const pendingNavigation = browser.captureNavigation(dom, true);
+linkOrFormSubmit.click();
+const response = await pendingNavigation;
+assert(request instanceof Response);
+```
+
+Navigation will fail if stopped by:
+- Prevented default action of link `click` / form `submit` event using `preventDefault()`
+- Form element `invalid` event
+
+```js
+await assert.reject(pendingNavigation, (event) => {
+	assert.equal(event.type, 'invalid');
+	assert.equal(event.target, form.elements[1]);
+	return true;
+})
+```
+
+Navigation is intercepted at the `window` level using event listeners. Promise will not settle if event propagation is stopped or if form submit is triggered without event, e.g. with the `submit` method.
+
+### `ReverseProxy`
+
+A module for emulating a CDN like reverse proxy. Basically a wrapper around `nock`.
+
+```js
+import { ReverseProxy } from '@zombieland/tallahassee';
+```
+
+#### `new ReverseProxy(proxyOrigin, upstreamOrigin[, headers])`
+
+Creates HTTP interceptor for a _public_ proxy origin and proxies request to a _local_ upstream origin.
+
+- `proxyOrigin` `<string>` Public URL origin
+- `upstreamOrigin` `<string>` Server URL origin
+- `headers` `<Object>` | `<Headers>` Headers to pass along to server. **Default** Standard forwarding headers (`Forwarded`, `X-Forwarded-Proto`, `X-Forwarded-Host`) derived from `proxyOrigin`
+- Returns: `<ReverseProxy>`
+
+```js
+import http from 'node:http';
+import { Browser, ReverseProxy } from '@zombieland/tallahassee';
+
+http.createServer(…).listen(7411);
+const reverseProxy = new ReverseProxy('https://tallahassee.zl', 'http://localhost:7411')
+const browser = new Browser('https://tallahassee.zl');
+const dom = await browser.navigateTo('/safe-house');
+assert.equal(dom.window.location, 'https://tallahassee.zl/safe-house');
+```
+
+#### `reverseProxy.modifyUpstreamRequest(req)`
+
+Modifies the upstream request before it is sent to the upstream origin. This method can be overridden to customize request headers or other properties.
+
+The default implementation applies the `headers` supplied to the constructor.
+
+- `req` `<Request>` The request object to be sent to the upstream origin
+- Returns: `<Request>` The modified request object
+
+```js
+class CustomReverseProxy extends ReverseProxy {
+	modifyUpstreamRequest(req) {
+		req = super.modifyUpstreamRequest(req);
+
+		const forwarded = req.headers.get('forwarded');
+		req.headers.set('forwarded', `for=192.168.0.1;${forwarded}`);
+		req.headers.set('Via', '1.1 MyProxy');
+		
+		return req;
+	}
+}
+```
+
+#### `reverseProxy.clear()`
+
+Clears nocked responses for `proxyOrigin`
+
+- Returns: `undefined`
+
+```js
+reverseProxy.clear();
+```
+
+## Todo
+
+- [ ] Reloading page
+- [ ] Unload browser and all its active jsdom instances
+- [ ] Expose network requests
+- [x] Use node `fetch` / `Response` / `Request`
+	- [x] Stable version of Nock
+- [x] In-page navigation (clicking links etc.)
+- [x] Containing requests to the app is currently done by setting up a `nock` scope around app origin which intercepts all reqs and proxies them through `supertest`. Not ideal for a bunch of reasons:
+	- [x] There is no built in way to clear a specific scope - [creative workaround](https://github.com/nock/nock/issues/1495#issuecomment-499594455)
+- [x] Scrap use of SuperTest. It's incorrectly used as an HTTP lib because of its ability to _make requests to a server_. Not having a listening server makes handling of client side requests messy. Calls to `XMLHttpRequest` needs to be intercepted and cookies will need to be handled manually. Also having the consumer starting / stopping their server once per test process would be more performant than doing it adhoc for each request.

package/browser.js

@@ -0,0 +1,150 @@
+import jsdom from 'jsdom';
+
+export default class Browser {
+	constructor (origin, cookieJar) {
+		this.origin = origin;
+		this.cookieJar = cookieJar || new jsdom.CookieJar();
+	}
+
+	async navigateTo (resource, fetchOptions, loadOptions) {
+		const response = this.fetch(resource, fetchOptions);
+		return this.load(response, loadOptions);
+	}
+
+	async fetch (resource, options = {}) {
+		resource = typeof resource === 'string' ? new URL(resource, this.origin) : resource;
+		const isRequest = resource instanceof Request;
+		const request = isRequest ? resource : new Request(resource, {
+			...options,
+			redirect: 'manual'
+		});
+
+		this.#persistCookies(request.url, request.headers);
+		request.headers.delete('cookie');
+		request.headers.set('cookie', this.cookieJar.getCookieStringSync(request.url));
+
+		const response = await fetch(request);
+
+		this.#persistCookies(response.url, null, response.headers);
+
+		if (![ 301, 302, 303, 307, 308 ].includes(response.status))
+			return response;
+
+		const redirectOptions = { ...options, headers: undefined };
+		if (response.status <= 303) {
+			delete redirectOptions.method;
+			delete redirectOptions.body;
+		}
+
+		return this.fetch(response.headers.get('location'), redirectOptions);
+	}
+
+	async load (resource, options = {}) {
+		resource = await resource;
+		const isResponse = resource instanceof Response;
+		const document = isResponse ? await resource.text() : resource;
+
+		return new jsdom.JSDOM(document, {
+			pretendToBeVisual: Boolean(options?.painter),
+			runScripts: options.resources && 'outside-only',
+			...options,
+			...(isResponse && {
+				url: resource.url || undefined,
+				contentType: resource.headers.get('content-type') || undefined,
+			}),
+			cookieJar: this.cookieJar,
+			beforeParse: window => {
+				options.painter?.beforeParse(window);
+				options.resources?.beforeParse?.(window);
+				options.beforeParse?.(window);
+			}
+		});
+	}
+
+	captureNavigation (dom, follow) {
+		const browser = this;
+
+		return new Promise((resolve, reject) => {
+			dom.window.addEventListener('click', captureLinkClick);
+			dom.window.addEventListener('submit', captureFormSubmit);
+			for (const form of dom.window.document.forms)
+				for (const element of form.elements)
+					element.addEventListener('invalid', captureFormElementInvalid);
+
+			function captureLinkClick (event) {
+				const link = event.target.closest('a');
+				if (!link) return;
+
+				runDefault(event, link.href);
+			}
+
+			function captureFormSubmit (event) {
+				const form = event.target;
+				const submitter = event.submitter;
+				const method = submitter?.formMethod || form.method;
+				const action = new URL(submitter?.formAction || form.action);
+				const body = new dom.window.FormData(form, submitter);
+
+				if (method === 'post') {
+					const enctype = submitter?.formEnctype || form.enctype;
+
+					return runDefault(event, action, {
+						method,
+						headers: { 'content-type': enctype },
+						body,
+					});
+				}
+
+				for (const [ key, value ] of body) {
+					action.searchParams.set(key, value);
+				}
+
+				runDefault(event, action);
+			}
+
+			function captureFormElementInvalid (event) {
+				cleanUp();
+				return reject(event);
+			}
+
+			function runDefault (event, url, options) {
+				cleanUp();
+				if (event.defaultPrevented) {
+					return reject(event);
+				}
+
+				event.preventDefault();
+				if (!follow) {
+					return resolve(new Request(url, options));
+				}
+
+				dom.window.dispatchEvent(new dom.window.Event('pagehide'));
+				dom.window.close();
+				resolve(browser.fetch(url, options));
+			}
+
+			function cleanUp () {
+				dom.window.removeEventListener('click', captureLinkClick);
+				dom.window.removeEventListener('submit', captureFormSubmit);
+				for (const form of dom.window.document.forms)
+					for (const element of form.elements)
+						element.removeEventListener('invalid', captureFormElementInvalid);
+			}
+		});
+	}
+
+	#persistCookies (url, reqHeaders, resHeaders) {
+		let directives;
+		if (reqHeaders)
+			directives = reqHeaders.get('cookie')
+				?.split(';')
+				.map(d => d.trim())
+				.filter(Boolean);
+		else if (resHeaders)
+			directives = resHeaders.getSetCookie();
+
+		for (const directive of directives || []) {
+			this.cookieJar.setCookieSync(directive, url);
+		}
+	}
+};

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@zombieland/tallahassee",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "",
+  "main": "tallahassee.js",
+  "scripts": {
+    "test": "mocha"
+  },
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "jsdom": "^27.4.0"
+  },
+  "devDependencies": {
+    "nock": "^14.0.12"
+  }
+}

package/reverse-proxy.js

@@ -0,0 +1,65 @@
+import nock from 'nock';
+
+const httpVerbs = [ 'DELETE', 'GET', 'HEAD', 'MERGE', 'OPTIONS', 'PATCH', 'POST', 'PUT' ];
+
+export default class ReverseProxy {
+	#interceptors = [];
+
+	constructor (proxyOrigin, upstreamOrigin, headers) {
+		this.proxyOrigin = proxyOrigin;
+		this.upstreamOrigin = upstreamOrigin;
+		this.headers = new Headers(headers || (url => {
+			const { protocol, hostname } = url;
+			const proto = protocol.slice(0, -1);
+			return {
+				'forwarded': `proto=${proto};host=${hostname}`,
+				'x-forwarded-proto': proto,
+				'x-forwarded-host': hostname,
+			};
+		})(new URL(proxyOrigin)));
+
+		const proxy = this;
+		for (const verb of httpVerbs) {
+			const interceptor = nock(proxyOrigin)
+				.persist()
+				.intercept(/.*/, verb);
+			interceptor.reply(function (path, body, callback) {
+				proxy.#forward.call(proxy, this.req, path, body, callback);
+			});
+			this.#interceptors.push(interceptor);
+		}
+	}
+
+	clear () {
+		for (const interceptor of this.#interceptors)
+			nock.removeInterceptor(interceptor);
+	}
+
+	modifyUpstreamRequest (req) {
+		for (const [ key, value ] of this.headers.entries())
+			req.headers.set(key, value);
+		return req;
+	}
+
+	async #forward (req, path, body, callback) {
+		try {
+			const { method, headers } = req;
+			const bereq = this.modifyUpstreamRequest(
+				new Request(new URL(path, this.upstreamOrigin), {
+					method,
+					headers,
+					body: body || undefined,
+				})
+			);
+			const beres = await fetch(bereq);
+			callback(null, [
+				beres.status,
+				await beres.text(),
+				Object.fromEntries(beres.headers.entries())
+			]);
+		}
+		catch (error) {
+			callback(error);
+		}
+	}
+};

package/tallahassee.js

@@ -0,0 +1,2 @@
+export { default as Browser } from './browser.js';
+export { default as ReverseProxy } from './reverse-proxy.js';

package/test/browser-test.js

@@ -0,0 +1,467 @@
+import assert from 'node:assert/strict';
+import Browser from '../browser.js';
+import nock from 'nock';
+import parseFormData from '../../../helpers/parse-form-data.js';
+
+describe('Browser', () => {
+	before(() => nock.disableNetConnect());
+	beforeEach(() => nock.cleanAll());
+
+	const url = new URL('http://example.com/');
+	let browser;
+	beforeEach(() => browser = new Browser(url.origin));
+	after(() => nock.enableNetConnect());
+
+	describe('.navigateTo()', () => {
+		it('navigates to document with URL', async () => {
+			nock(url.origin)
+				.get('/')
+				.reply(200, '<title>Document from URL');
+
+			const dom = await browser.navigateTo('/');
+			assert(dom.window.document.title, 'Document from URL');
+		});
+	});
+
+	describe('.fetch()', () => {
+		it('fetches resource with url and options', async () => {
+			nock(url.origin)
+				.post(url.pathname)
+				.reply(function (path, body) {
+					assert.equal(this.req.headers['req-header'], 'value');
+					assert.equal(body, 'request body');
+					return [ 200, 'response body', { 'res-header': 'value' } ];
+				});
+
+			const response = await browser.fetch(url, {
+				method: 'post',
+				headers: { 'req-header': 'value' },
+				body: 'request body',
+			});
+
+			assert.equal(response.status, 200);
+			assert.equal(response.headers.get('res-header'), 'value');
+
+			const responseBody = await response.text();
+			assert.equal(responseBody, 'response body');
+		});
+
+		it('fetches resource with request', async () => {
+			nock(url.origin)
+				.post(url.pathname)
+				.reply(function (path, body) {
+					assert.equal(this.req.headers['req-header'], 'value');
+					assert.equal(body, 'request body');
+					return [ 200, 'response body', { 'res-header': 'value' } ];
+				});
+
+			const request = new Request(url, {
+				method: 'post',
+				headers: { 'req-header': 'value' },
+				body: 'request body',
+			});
+			const response = await browser.fetch(request);
+
+			assert.equal(response.status, 200);
+			assert.equal(response.headers.get('res-header'), 'value');
+
+			const responseBody = await response.text();
+			assert.equal(responseBody, 'response body');
+		});
+
+		[
+			[ 301, 'moved-permanently' ],
+			[ 302, 'found' ],
+			[ 303, 'see-other' ],
+		].forEach(([ status, location ]) => {
+			it(`follows ${status} redirect`, async () => {
+				nock(url.origin)
+					.post(url.pathname)
+					.reply(status, undefined, { location: `/${location}` })
+					.get(`/${location}`)
+					.reply(function (path, body) {
+						const { headers } = this.req;
+						assert.equal(headers['initial-request-header'], undefined);
+						assert.equal(body, '');
+						return [ 200 ];
+					});
+
+				const response = await browser.fetch(url, {
+					method: 'post',
+					headers: { 'initial-request-header': 'value' },
+					body: 'initial request body',
+				});
+
+				assert.equal(response.status, 200);
+			});
+		});
+
+		[
+			[ 307, 'temporary-redirect' ],
+			[ 308, 'permanent-redirect' ],
+		].forEach(([ status, location ]) => {
+			it(`follows ${status} redirect with method and body unchanged`, async () => {
+				nock(url.origin)
+					.post(url.pathname)
+					.reply(status, undefined, { location: `/${location}` })
+					.post(`/${location}`)
+					.reply(function (path, body) {
+						const { headers } = this.req;
+						assert.equal(headers['initial-request-header'], undefined);
+						assert.equal(body, 'initial request body');
+						return [ 200 ];
+					});
+
+				const response = await browser.fetch(url, {
+					method: 'post',
+					headers: { 'initial-request-header': 'value' },
+					body: 'initial request body',
+				});
+
+				assert.equal(response.status, 200);
+			});
+		});
+
+		it('persists request cookies to cookie jar', async () => {
+			nock(url.origin)
+				.get('/requires-authentication')
+				.times(2)
+				.reply(function () {
+					assert.equal(this.req.headers.cookie, 'logged-in=1');
+					return [ 200, 'OK' ];
+				});
+
+			await browser.fetch(
+				'/requires-authentication',
+				{ headers: { cookie: 'logged-in=1' } }
+			);
+
+			const response = await browser.fetch('/requires-authentication');
+			assert.equal(response.status, 200);
+		});
+
+		it('persists response cookies to cookie jar', async () => {
+			nock(url.origin)
+				.post('/login')
+				.reply(200, 'OK', { 'set-cookie': 'logged-in=1' })
+				.get('/requires-authentication')
+				.reply(function () {
+					assert.equal(this.req.headers.cookie, 'logged-in=1');
+					return [ 200, 'OK' ];
+				});
+
+			await browser.fetch('/login', { method: 'post' });
+			const response = await browser.fetch('/requires-authentication');
+			assert.equal(response.status, 200);
+		});
+
+		it('persists cookies through redirect chain', async () => {
+			nock(url.origin)
+				.post('/login')
+				.reply(function () {
+					return this.req.headers.cookie === 'user=zombie' ?
+						[ 401, 'Unauthorized' ] :
+						[ 302, 'Found', {
+							'set-cookie': 'logged-in=1',
+							'location': '/requires-authentication'
+						} ];
+				})
+				.get('/requires-authentication')
+				.reply(function () {
+					assert.equal(this.req.headers.cookie, 'user=person; logged-in=1');
+					return [ 200, 'OK' ];
+				});
+
+			const response = await browser.fetch('/login', {
+				method: 'post',
+				headers: { cookie: 'user=person' }
+			});
+
+			assert.equal(response.status, 200);
+		});
+	});
+
+	describe('.load()', () => {
+		it('loads document from string', async () => {
+			const dom = await browser.load('<title>Document from string');
+			assert(dom.window.document.title, 'Document from string');
+		});
+
+		it('loads document from response', async () => {
+			nock(url.origin)
+				.post('/secure')
+				.reply((path, body) => {
+					return body === 'password' ?
+						[ 200, '<title>Welcome' ] :
+						[ 401, '<title>Get out' ];
+				});
+
+			const response = await browser.fetch('/secure', {
+				method: 'post',
+				body: 'password'
+			});
+
+			assert.equal(response.status, 200);
+
+			const dom = await browser.load(response);
+			assert(dom.window.document.title, 'Welcome');
+		});
+
+		it('loads document with details from response', async () => {
+			nock(url.origin)
+				.get('/xml-document')
+				.reply(
+					200,
+					'<xml><land><zombie /></land></xml>',
+					{ 'content-type': 'application/xml' }
+				);
+
+			const pendingResponse = browser.fetch('/xml-document');
+			const dom = await browser.load(pendingResponse);
+			assert.equal(dom.window.location.href, url.origin + '/xml-document');
+			assert.equal(dom.window.document.contentType, 'application/xml');
+		});
+	});
+
+	describe('.captureNavigation()', () => {
+		describe('links', () => {
+			let dom;
+			beforeEach('a page with a link', async () => {
+				nock(url.origin)
+					.get('/')
+					.reply(200, '<a href="/about">About</a>');
+
+				dom = await browser.navigateTo('/');
+			});
+
+			it('captures navigation from link', async () => {
+				const link = dom.window.document.querySelector('a');
+				assert.ok(link, 'expected link');
+
+				const pendingRequest = browser.captureNavigation(dom);
+				assert(pendingRequest instanceof Promise, 'expected promise return value');
+
+				link.click();
+
+				const request = await pendingRequest;
+				assert(request instanceof Request, 'expected request');
+				assert.equal(request.url, link.href);
+			});
+
+			it('captures and follows navigation from link', async () => {
+				nock(url.origin)
+					.get('/about')
+					.reply(200, '<title>About</title>');
+
+				const link = dom.window.document.querySelector('a');
+				assert.ok(link, 'expected link');
+
+				const pendingResponse = browser.captureNavigation(dom, true);
+				assert(pendingResponse instanceof Promise, 'expected promise return value');
+
+				link.click();
+
+				const response = await pendingResponse;
+				assert(response instanceof Response, 'expected response');
+				assert.equal(response.status, 200);
+
+				const body = await response.text();
+				assert.equal(body, '<title>About</title>');
+			});
+
+			it('fails on prevented navigation', async () => {
+				const link = dom.window.document.querySelector('a');
+				assert.ok(link, 'expected link');
+
+				link.addEventListener('click', event => event.preventDefault());
+
+				const pendingRequest = browser.captureNavigation(dom);
+				link.click();
+
+				await assert.rejects(pendingRequest, event => {
+					assert.ok(event instanceof dom.window.Event);
+					assert.equal(event.type, 'click');
+					assert.equal(event.target, link);
+					return true;
+				});
+			});
+		});
+
+		describe('forms', () => {
+			let dom;
+			beforeEach(async () => {
+				nock(url.origin)
+					.get('/')
+					.times(2)
+					.reply(function () {
+						if (this.req.headers.cookie === 'logged-in=1') {
+							return [ 200, '<title>Welcome</title>' ];
+						}
+
+						return [ 200, `
+							<title>Log in</title>
+							<form method="post" action="/login">
+								<input type="text" name="username" />
+								<input type="password" name="password" />
+								<button type="submit">Log in</button>
+							</form>
+						` ];
+					});
+
+				dom = await browser.navigateTo('/');
+			});
+
+			it('captures navigation from form', async () => {
+				assert.equal(dom.window.document.title, 'Log in');
+				const [ form ] = dom.window.document.forms;
+				assert.ok(form, 'expected form');
+
+				const [ username, password, submit ] = form.children;
+				username.value = 'person';
+				password.value = 'password';
+
+				const pendingRequest = browser.captureNavigation(dom);
+				assert(pendingRequest instanceof Promise, 'expected promise return value');
+				submit.click();
+
+				const request = await pendingRequest;
+				assert(request instanceof Request, 'expected request');
+				assert.equal(request.method, 'POST');
+				assert.equal(request.url, url.origin + '/login');
+				assert.equal(request.headers.get('content-type'), 'application/x-www-form-urlencoded');
+				assert(request.body instanceof ReadableStream);
+			});
+
+			it('captures navigation from form with submitter', async () => {
+				assert.equal(dom.window.document.title, 'Log in');
+				const [ form ] = dom.window.document.forms;
+				assert.ok(form, 'expected form');
+
+				const [ username, password, submit ] = form.children;
+				username.value = 'person';
+				password.value = 'password';
+
+				const { method, action, enctype } = form;
+
+				form.method = 'get';
+				form.action = '/search';
+				form.enctype = 'text/plain';
+
+				submit.formMethod = method;
+				submit.formAction = action;
+				submit.formEnctype = enctype;
+
+				const pendingRequest = browser.captureNavigation(dom);
+				submit.click();
+
+				const request = await pendingRequest;
+				assert.equal(request.method, 'POST');
+				assert.equal(request.url, url.origin + '/login');
+				assert.equal(request.headers.get('content-type'), 'application/x-www-form-urlencoded');
+			});
+
+			it('captures navigation from simple form', async () => {
+				dom = await browser.load(`
+					<form action="/search">
+						<input type="search" name="query" />
+						<button>Search</button>
+					</form>
+				`, { url });
+				const [ form ] = dom.window.document.forms;
+				assert.ok(form, 'expected form');
+
+				const [ query, submit ] = form.children;
+				query.value = 'Twinkies (not snowballs)';
+
+				const pendingRequest = browser.captureNavigation(dom);
+				assert(pendingRequest instanceof Promise, 'expected promise return value');
+				submit.click();
+
+				const request = await pendingRequest;
+				assert(request instanceof Request, 'expected request');
+				assert.equal(request.method, 'GET');
+				assert.equal(request.url, url.origin + '/search?query=Twinkies+%28not+snowballs%29');
+				assert.equal(request.headers.get('content-type'), null);
+			});
+
+			it('captures and follows navigation from form', async () => {
+				nock(url.origin)
+					.post('/login')
+					.reply(async function (path, body) {
+						const formData = await parseFormData(body, this.req.headers['content-type']);
+						const loggedIn = formData.username === 'person' &&
+							formData.password === 'password';
+
+						return [ 303, undefined, {
+							'location': '/',
+							'set-cookie': 'logged-in=' + Number(loggedIn),
+						} ];
+					});
+
+				assert.equal(dom.window.document.title, 'Log in');
+				const [ form ] = dom.window.document.forms;
+				assert.ok(form, 'expected form');
+
+				const [ username, password, submit ] = form.children;
+				username.value = 'person';
+				password.value = 'password';
+
+				const pendingResponse = browser.captureNavigation(dom, true);
+				assert(pendingResponse instanceof Promise, 'expected promise return value');
+				submit.click();
+
+				const response = await pendingResponse;
+				assert(response instanceof Response, 'expected response');
+				assert.equal(response.status, 200);
+
+				const body = await response.text();
+				assert.equal(body, '<title>Welcome</title>');
+			});
+
+			it('fails on invalid submit', async () => {
+				assert.equal(dom.window.document.title, 'Log in');
+				const [ form ] = dom.window.document.forms;
+				assert.ok(form, 'expected form');
+
+				form.addEventListener('submit', event => event.preventDefault());
+
+				const [ username, password, submit ] = form.children;
+				username.required = true;
+				password.required = true;
+
+				const pendingRequest = browser.captureNavigation(dom);
+				submit.click();
+
+				await assert.rejects(pendingRequest, event => {
+					assert.ok(event instanceof dom.window.Event);
+					assert.equal(event.type, 'invalid');
+					assert.equal(event.target, username);
+					return true;
+				});
+			});
+
+			it('fails on prevented navigation', async () => {
+				assert.equal(dom.window.document.title, 'Log in');
+				const [ form ] = dom.window.document.forms;
+				assert.ok(form, 'expected form');
+
+				form.addEventListener('submit', event => event.preventDefault());
+
+				const [ username, password, submit ] = form.children;
+				username.value = 'person';
+				password.value = 'password';
+
+				const pendingRequest = browser.captureNavigation(dom);
+				submit.click();
+
+				await assert.rejects(pendingRequest, event => {
+					assert.ok(event instanceof dom.window.Event);
+					assert.equal(event.type, 'submit');
+					assert.equal(event.target, form);
+					assert.equal(event.defaultPrevented, true);
+					return true;
+				});
+			});
+		});
+	});
+});

package/test/reverse-proxy-test.js

@@ -0,0 +1,218 @@
+import assert from 'node:assert/strict';
+import Browser from '../browser.js';
+import nock from 'nock';
+import ReverseProxy from '../reverse-proxy.js';
+
+describe('ReverseProxy', () => {
+	before(() => nock.disableNetConnect());
+	beforeEach(() => nock.cleanAll());
+	after(() => nock.enableNetConnect());
+
+	const proxyOrigin = 'https://tallahassee.zl';
+	const upstreamOrigin = 'http://localhost';
+
+	it('proxies request to upstream origin', async () => {
+		nock(upstreamOrigin)
+			.get('/resource')
+			.reply(200, 'response from upstream');
+
+		// eslint-disable-next-line no-new
+		new ReverseProxy(proxyOrigin, upstreamOrigin);
+
+		const response = await fetch(proxyOrigin + '/resource');
+		assert.equal(response.status, 200);
+
+		const responseBody = await response.text();
+		assert.equal(responseBody, 'response from upstream');
+	});
+
+	it('proxies request with forwarding headers', async () => {
+		nock(upstreamOrigin)
+			.get('/resource')
+			.reply(function () {
+				const { headers } = this.req;
+				assert.equal(headers.host, 'tallahassee.zl');
+				assert.equal(headers.forwarded, 'proto=https;host=tallahassee.zl');
+				assert.equal(headers['x-forwarded-proto'], 'https');
+				assert.equal(headers['x-forwarded-host'], 'tallahassee.zl');
+				assert.equal(headers['req-header'], 'value');
+				return [ 200 ];
+			});
+
+		// eslint-disable-next-line no-new
+		new ReverseProxy(proxyOrigin, upstreamOrigin);
+
+		const response = await fetch(proxyOrigin + '/resource', {
+			headers: { 'req-header': 'value' },
+		});
+		assert.equal(response.status, 200);
+	});
+
+	it('proxies request with additional headers', async () => {
+		nock(upstreamOrigin)
+			.get('/resource')
+			.reply(function () {
+				const { headers } = this.req;
+				assert.equal(headers.host, 'tallahassee.zl');
+				assert.equal(headers.via, '1.1 ZL');
+				assert.equal(headers['req-header'], 'value');
+				assert.equal(headers.forwarded, undefined);
+				assert.equal(headers['x-forwarded-proto'], undefined);
+				assert.equal(headers['x-forwarded-host'], undefined);
+				return [ 200 ];
+			});
+
+		// eslint-disable-next-line no-new
+		new ReverseProxy(proxyOrigin, upstreamOrigin, new Headers({
+			via: '1.1 ZL'
+		}));
+
+		const response = await fetch(proxyOrigin + '/resource', {
+			headers: { 'req-header': 'value' },
+		});
+		assert.equal(response.status, 200);
+	});
+
+	it('proxies modified request', async () => {
+		nock(upstreamOrigin)
+			.get('/resource')
+			.reply(function () {
+				const { headers } = this.req;
+				assert.equal(headers.host, 'tallahassee.zl');
+				assert.equal(headers.via, '1.1 ZL');
+				assert.equal(headers['req-header'], 'value');
+				assert.equal(headers.forwarded, 'for=192.168.0.1;proto=https;host=tallahassee.zl');
+				assert.equal(headers['x-forwarded-proto'], undefined);
+				assert.equal(headers['x-forwarded-host'], undefined);
+				return [ 200 ];
+			});
+
+		class CustomReverseProxy extends ReverseProxy {
+			modifyUpstreamRequest (req) {
+				assert(!req.headers.get('forwarded'));
+
+				req = super.modifyUpstreamRequest(req);
+				assert(req.headers.get('forwarded'));
+
+				req.headers.set('via', '1.1 ZL');
+				req.headers.set('forwarded', 'for=192.168.0.1;' + req.headers.get('forwarded'));
+				req.headers.delete('x-forwarded-proto');
+				req.headers.delete('x-forwarded-host');
+				return req;
+			}
+		}
+
+		// eslint-disable-next-line no-new
+		new CustomReverseProxy(proxyOrigin, upstreamOrigin);
+
+		const response = await fetch(proxyOrigin + '/resource', {
+			headers: { 'req-header': 'value' },
+		});
+		assert.equal(response.status, 200);
+	});
+
+	it('proxies request with body', async () => {
+		nock(upstreamOrigin)
+			.post('/resource')
+			.reply((path, body) => {
+				assert.equal(body, 'request body');
+				return [ 200 ];
+			});
+
+		// eslint-disable-next-line no-new
+		new ReverseProxy(proxyOrigin, upstreamOrigin);
+
+		const response = await fetch(proxyOrigin + '/resource', {
+			method: 'post',
+			body: 'request body',
+		});
+		assert.equal(response.status, 200);
+	});
+
+	[
+		'DELETE',
+		'GET',
+		'HEAD',
+		'MERGE',
+		'OPTIONS',
+		'PATCH',
+		'POST',
+		'PUT'
+	].forEach(method => {
+		it(`proxies request with method ${method}`, async () => {
+			nock(upstreamOrigin)
+				.intercept('/resource', method)
+				.reply(200);
+
+			// eslint-disable-next-line no-new
+			new ReverseProxy(proxyOrigin, upstreamOrigin);
+
+			const response = await fetch(proxyOrigin + '/resource', { method });
+			assert.equal(response.status, 200);
+		});
+	});
+
+	it('proxies requests until cleared', async () => {
+		nock(upstreamOrigin)
+			.get('/resource')
+			.reply(200)
+			.persist();
+
+		const proxy = new ReverseProxy(proxyOrigin, upstreamOrigin);
+
+		for (let i = 0; i < 3; i++) {
+			const response = await fetch(proxyOrigin + '/resource');
+			assert.equal(response.status, 200);
+		}
+
+		proxy.clear();
+
+		await assert.rejects(fetch(proxyOrigin + '/resource'));
+
+		const upstreamResponse = await fetch(upstreamOrigin + '/resource');
+		assert.equal(upstreamResponse.status, 200);
+	});
+
+	it('proxies requests from browser, document and web page', async () => {
+		nock(upstreamOrigin)
+			.get('/document')
+			.reply(200, `
+				<!doctype html>
+				<title>Document from upstream</title>
+				<iframe src="/sub-document"></iframe>
+				<script>
+					const req = new XMLHttpRequest();
+					req.open("GET", "/data");
+					req.addEventListener("load", function () {
+						const data = JSON.parse(this.responseText);
+						document.title += ', ' + data.title;
+						window.dispatchEvent(new Event("fetchresponse"));
+					});
+					req.send();
+				</script>
+			`)
+			.get('/sub-document')
+			.reply(200, `
+				<!doctype html>
+				<title>Sub-document from upstream</title>
+			`)
+			.get('/data')
+			.reply(200, { title: 'Data from upstream' });
+
+		// eslint-disable-next-line no-new
+		new ReverseProxy(proxyOrigin, upstreamOrigin);
+		const browser = new Browser(proxyOrigin);
+		const dom = await browser.navigateTo('/document', {}, {
+			resources: 'usable',
+			runScripts: 'dangerously',
+		});
+		await Promise.all([
+			new Promise(r => dom.window.addEventListener('load', r)),
+			new Promise(r => dom.window.addEventListener('fetchresponse', r)),
+		]);
+
+		assert.equal(dom.window.location.href, proxyOrigin + '/document');
+		assert.equal(dom.window.document.title, 'Document from upstream, Data from upstream');
+		assert.equal(dom.window.frames[0].document.title, 'Sub-document from upstream');
+	});
+});