tape-six-playwright

tape-six-playwright is a helper for tape-six to run tests in a headless browser via Playwright. Each test file runs in its own browser context — a separate page and iframe with isolated cookies and storage — in a headless engine. Chromium runs by default; Firefox and WebKit are available via --browser.

Why?

The standard tape6 runner uses worker threads. tape6-playwright launches a headless browser (Chromium, Firefox, or WebKit) and runs each test file in its own browser context, giving tests access to real DOM, browser APIs, and the full web platform. Tests can be .js/.mjs modules or .html files.

Install

npm i -D tape-six-playwright

Playwright's bundled Chromium is installed automatically via postinstall. Firefox and WebKit are optional — add them with npm run browser:all (or npx playwright install firefox webkit) when you want to run on those engines.

Quick start

1. Write tests using tape-six that use browser APIs:

import test from 'tape-six';

test('DOM works', t => {
  const el = document.createElement('div');
  el.textContent = 'hello';
  document.body.appendChild(el);
  t.equal(document.body.lastChild.textContent, 'hello', 'element created');
});

1. Configure tests in package.json:

{
  "scripts": {
    "test": "tape6-playwright --start-server --flags FO"
  },
  "tape6": {
    "browser": ["/tests/test-*.html"],
    "tests": ["/tests/test-*.*js"],
    "importmap": {
      "imports": {
        "tape-six": "/node_modules/tape-six/index.js",
        "tape-six/": "/node_modules/tape-six/src/"
      }
    }
  }
}

1. Run:

npm test

Server

tape6-playwright requires tape6-server (from tape-six) to serve test files to the browser.

• Auto-start: use --start-server to launch it automatically.
• Manual: run npx tape6-server in a separate terminal, then run tests without --start-server.
• Custom URL: use --server-url URL (-u), or set TAPE6_SERVER_URL or HOST/PORT environment variables.

HTTP/2

tape6-server (tape-six 1.12+) can serve HTTPS with HTTP/2 (HTTP/1.1 is still accepted via ALPN). Opt in with --h2, TAPE6_PROTOCOL=h2, or the sticky tape6.server.protocol config — the runner mirrors the server's flag > env > config resolution:

tape6-playwright --h2 --start-server --flags FO
tape6-playwright -u https://localhost:3000 --flags FO   # external h2 server

--h2 implies an https: server URL and is passed through to a self-launched server. Certificates are handled automatically: browser contexts run with ignoreHTTPSErrors, and the runner's own control requests trust TAPE6_CERT when set (e.g. an mkcert certificate), else the server's cached auto-generated certificate (node_modules/.cache/tape6/), else fall back to relaxed verification scoped to those requests only — never process-wide.

HTTP/1.1 remains the default: h2 means TLS, and a self-signed certificate blocks service-worker registration even after an interstitial click-through. Opt in per suite for features that require h2 — e.g. fetch() request-body streaming (duplex: 'half'), which Chromium supports over h2/h3 only. The h2 server mode is Node-only; under Bun or Deno the runner starts the server child with node from PATH.

Choosing a browser engine

Tests run on Chromium by default. Select another engine with --browser (-b) or the TAPE6_BROWSER environment variable — chromium, firefox, or webkit (CLI overrides env, which overrides the default):

tape6-playwright --start-server --browser firefox --flags FO
TAPE6_BROWSER=webkit tape6-playwright --start-server --flags FO

Only Chromium is installed by postinstall. Install the others on demand (a run that requests a missing or unrunnable engine fails with an install hint):

npx playwright install firefox webkit   # or: npm run browser:all
# on Linux you may also need: npx playwright install-deps

Run several engines with one script each:

{
  "scripts": {
    "test": "tape6-playwright --start-server --flags FO",
    "test:firefox": "tape6-playwright --start-server --browser firefox --flags FO",
    "test:webkit": "tape6-playwright --start-server --browser webkit --flags FO"
  }
}

Or fan out over several engines in one invocation with --browsers (comma-separated, or all; env TAPE6_BROWSERS; overrides --browser). Each engine runs the full suite and prints its own summary, followed by a per-engine verdict; the run fails if any engine fails:

tape6-playwright --start-server --browsers all --flags FO
tape6-playwright --start-server --browsers chromium,webkit --flags FO

Browser: chromium
  ♥️   tests: 10, asserts: 24, passed: 24, ...
Browser: firefox
  ♥️   tests: 10, asserts: 24, passed: 24, ...

Browsers: chromium PASS, firefox PASS

This is the cheap way to catch cross-engine web-platform gaps (e.g. a Web Streams method one engine hasn't shipped) that single-engine testing can't see.

Cross-runtime usage

{
  "scripts": {
    "test": "tape6-playwright --start-server --flags FO",
    "test:bun": "bun run `tape6-playwright --self` --start-server --flags FO",
    "test:deno": "deno run -A `tape6-playwright --self` --start-server --flags FO"
  }
}

Docs

Full documentation is in the wiki — browse the index, or search it by name. tape-six has its own wiki.

tape-six-playwright uses the same test configuration and CLI conventions as tape-six.

Command-line utilities

• tape6-playwright — the main utility of this package to run browser tests.

AI agents

If you are an AI coding agent, see AGENTS.md for project conventions, commands, and architecture.

LLM-friendly documentation is available:

• llms.txt — concise reference.
• llms-full.txt — full reference with architecture details.

Release notes

The most recent releases:

• 1.2.2 Adopted tape-six's shared browser-driver kit (requires tape-six 1.15+). Updated dependencies.
• 1.2.1 Fixed server readiness probing. Updated dependencies.
• 1.2.0 Added HTTP/2 mode and multi-engine fan-out.
• 1.1.0 Added browser-engine selection (--browser chromium|firefox|webkit). Implemented the terminate protocol. Updated dependencies.
• 1.0.3 Replaced process.exit() with process.exitCode to prevent truncated output.
• 1.0.2 Added --help/-h and --version/-v CLI options.
• 1.0.1 Updated dependencies, added npm run browser script, improved workflows.
• 1.0.0 The first official release.

See the full release notes for details.