# tape-six-playwright [![NPM version][npm-img]][npm-url]

[npm-img]: https://img.shields.io/npm/v/tape-six-playwright.svg
[npm-url]: https://npmjs.org/package/tape-six-playwright

`tape-six-playwright` is a helper for [tape-six](https://www.npmjs.com/package/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

```bash
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](https://www.npmjs.com/package/tape-six) that use browser APIs:

```js
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`:

```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:

```bash
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):

```bash
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):

```bash
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:

```json
{
  "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

```json
{
  "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](https://github.com/uhop/tape-six-playwright/wiki) for full documentation.
`tape-six` has its own [wiki](https://github.com/uhop/tape-six/wiki).

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

### Command-line utilities

- [tape6-playwright](https://github.com/uhop/tape-six-playwright/wiki/Utility-‐-tape6‐playwright) — the main utility of this package to run browser tests.

## AI agents

If you are an AI coding agent, see [AGENTS.md](./AGENTS.md) for project conventions, commands, and architecture.

LLM-friendly documentation is available:

- [llms.txt](./llms.txt) — concise reference.
- [llms-full.txt](./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](https://github.com/uhop/tape-six-playwright/wiki/Release-notes) for details.