# tape-six-playwright

> Helper for [tape-six](https://github.com/uhop/tape-six) that runs test files in a headless browser via Playwright. Each test file runs in its own browser context (page + iframe) in Chromium, Firefox, or WebKit (default Chromium, selectable via `--browser`). Works with Node, Deno, and Bun.

## Install

```bash
npm i -D tape-six-playwright
```

Chromium is installed automatically via `postinstall`. Add Firefox/WebKit on demand with `npm run browser:all` (or `npx playwright install firefox webkit`).

## Quick start

1. Write tests using `tape-six` with browser APIs:

```js
import test from 'tape-six'

test('DOM test', t => {
  const el = document.createElement('div')
  el.textContent = 'hello'
  t.equal(el.textContent, 'hello', 'element works')
})
```

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

## Why use tape-six-playwright?

- **Real browser environment** — tests run in a headless engine (Chromium, Firefox, or WebKit) with full DOM and browser API access.
- **Per-context isolation** — each test file runs in its own browser context (isolated cookies/storage), in an iframe inside that context's page.
- **Multiple engines** — pick `chromium` (default), `firefox`, or `webkit` per run via `--browser` / `TAPE6_BROWSER`, or fan out over several in one invocation via `--browsers` / `TAPE6_BROWSERS` (catches cross-engine web-platform gaps).
- **Cross-runtime** — works with Node, Deno, and Bun using the same test files.
- **Drop-in companion** — uses the same configuration and test format as `tape6` and `tape6-proc`.

## CLI: tape6-playwright

```bash
tape6-playwright [options] [patterns...]
```

### Options

- `--flags FLAGS` (`-f`) — output control flags (same as tape6: F=failures only, T=time, B=banner, D=data, O=fail once, N=assert number, M=monochrome, C=don't capture console, H=hide streams). Can be specified multiple times.
- `--par N` (`-p`) — number of parallel iframes (default: all CPU cores).
- `--browser NAME` (`-b`) — browser engine: `chromium` (default), `firefox`, or `webkit` (env: `TAPE6_BROWSER`).
- `--browsers LIST` — fan out over several engines in one invocation: comma-separated names or `all` (env: `TAPE6_BROWSERS`; overrides `--browser`). Per-engine summaries + a final PASS/FAIL line per engine; non-zero exit if any engine fails.
- `--start-server` — auto-start `tape6-server` if not already running.
- `--h2` — HTTP/2 mode: implies an `https:` server URL; passed through to a self-launched server (env: `TAPE6_PROTOCOL=h2`).
- `--server-url URL` (`-u`) — server URL (overrides `TAPE6_SERVER_URL`); an `https:` URL enables TLS handling without `--h2`.
- `--self` — prints the path to `tape6-playwright.js` (for cross-runtime scripts).
- `--info` — prints runtime, reporter, flags, parallelism, and resolved test files, then exits.
- `--help` (`-h`) — shows help message and exits.
- `--version` (`-v`) — shows version and exits.
- No arguments: runs tests from configuration.
- Options accept `--flags FO` or `--flags=FO`. The `=` form does not support quoting.

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

## Server

Requires `tape6-server` (from `tape-six`) to serve test files. Use `--start-server` to auto-start it, or run `npx tape6-server` manually.

Server URL: `TAPE6_SERVER_URL` env var, or `HOST`/`PORT`, default `http://localhost:3000`.

HTTP/2 (tape-six 1.12+): `--h2` / `TAPE6_PROTOCOL=h2` / `tape6.server.protocol` config (flag > env > config, mirroring the server). Self-signed certificates are tolerated automatically: browser contexts get `ignoreHTTPSErrors`; the runner's control requests trust `TAPE6_CERT` when set, else the server's cached cert (`node_modules/.cache/tape6/`), else use relaxed verification scoped to those requests only. The h2 server mode is Node-only — under Bun/Deno the server child runs on `node`. HTTP/1.1 stays the default.

## Configuration

Same as `tape-six`. Reads from `tape6.json` or the `"tape6"` section of `package.json`:

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

## Environment variables

- `TAPE6_FLAGS` — flags string.
- `TAPE6_PAR` — number of parallel iframes.
- `TAPE6_TAP` — force TAP reporter.
- `TAPE6_JSONL` — force JSONL reporter.
- `TAPE6_MIN` — force minimal reporter.
- `TAPE6_SERVER_URL` — full server URL override.
- `TAPE6_PROTOCOL` — `h1` (default) or `h2`; overridden by `--h2`.
- `TAPE6_CERT` / `TAPE6_KEY` — TLS certificate/key paths (h2): passed to the server, and the certificate is trusted by the runner's control requests.
- `TAPE6_BROWSER` — browser engine: chromium|firefox|webkit (default chromium; overridden by `--browser`).
- `TAPE6_BROWSERS` — multi-engine fan-out list (comma-separated or `all`; overridden by `--browsers`; overrides `TAPE6_BROWSER`/`--browser`).
- `TAPE6_GRACE_TIMEOUT` — control channel: drain grace (ms) before a worker's context is force-closed (default 5000).
- `TAPE6_WORKER_TIMEOUT` — control channel: per-worker deadline (ms); 0 disables (default).

## Links

- Docs: https://github.com/uhop/tape-six-playwright/wiki
- npm: https://www.npmjs.com/package/tape-six-playwright
- tape-six: https://github.com/uhop/tape-six
- Full LLM reference: https://github.com/uhop/tape-six-playwright/blob/main/llms-full.txt