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');
});

2. 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/"
      }
    }
  }
}

3. 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.

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"
  }
}

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

See the wiki for full documentation. 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.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.