reuse-surface/registry/capabilities/capability.infotech.headless-browser.md

---
id: capability.infotech.headless-browser
name: Headless Browser Automation
summary: >-
  Headless browser automation, screenshots and keyboard trials through rapp-playwright 0.1.0 (Playwright 1.64.0, Chromium 156.0.8078.4). Human and coding-agent managed trials passed on 2026-10-18 through the existing supervised workstation connection. Use the documented kubectl port-forward to 127.0.0.1:18081, then the pinned standalone Python client preflight/trial commands. No local browser installation. Independent per-caller managed admission remains pending; availability stays A5. Contract: https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/docs/consumer-contract.md.
owner: reuse-surface
status: reviewed
domain: infotech
tags: [headless, browser, automation, playwright, chromium, testing, screenshots, extraction, firefox, webkit, selenium, puppeteer]
maturity:
  discovery:
    current: D3
    target: D4
    confidence: medium
    rationale: >
      Inspected four implemented Playwright consumers and separated optional
      dependencies and plans from usage. No comprehensive alternatives benchmark.
  availability:
    current: A5
    target: A6
    confidence: medium
    rationale: >
      rapp-playwright 0.1.0 is a published immutable container with a versioned
      HTTP contract and standalone Python client, independently trialled locally.
      A5 describes deployable container availability, not managed operation (A6).
      The supervised managed build profile has real human/agent receipts; independent
      per-caller admission remains pending. Existing A2 source adaptation remains usable;
      no endpoint uptime or caller browser installation is implied.
external_evidence:
  completeness:
    level: C2
    confidence: medium
    basis: scope_vs_intent_and_consumer_expectations
    satisfied_expectations:
      - Identifies implemented consumers, browser engines and source entry points.
      - Gives a scoped default recommendation and a practical trial procedure.
      - Published provider client and container have independent fixture screenshots and keyboard receipts.
      - Actual managed human and coding-agent supported-command trials passed on 2026-10-18 under the stated supervised build profile.
    broken_expectations:
      - Independent per-caller managed admission is still pending; the supervised build connection must be established first.
      - Consumer application acceptance remains the consuming repo's responsibility.
    out_of_scope_expectations:
      - Exhaustive estate dependency inventory or comparative browser benchmark.
      - Browser service implementation or operation by reuse-surface.
      - Mandatory estate-wide technology policy.
  reliability:
    level: R2
    confidence: medium
    basis: consumer_quality_signals
    known_reliability_risks:
      - Browser binaries and system libraries must match the selected Playwright version.
      - Existing examples contain application-specific fixtures and assumptions.
      - Provider fixture receipts do not prove arbitrary target compatibility or independent per-caller identity.
      - Local provider endpoints are ephemeral; check preflight for each trial.
    evidence:
      satisfied_signals:
        - frontend-patterns navigation-history records a completed Chromium/Firefox experiment.
        - rapp-playwright independent final-release trial passed 14 steps across desktop and narrow viewports.
        - Independent provider evidence includes wrong-token, failed assertion and unavailable-service checks.
discovery:
  intent: >
    Help a worker select and reuse existing headless browser tooling instead of
    independently introducing another automation stack.
  includes:
    - Playwright automation with headless Chromium as the default starting point.
    - JavaScript UI tests, screenshots and page extraction examples.
    - Python visual-check example and Firefox experiment evidence.
    - Published rapp-playwright container, Python client and bounded HTTP fixture trials.
  excludes:
    - Browser hosting or workstation provisioning by reuse-surface.
    - Credential provisioning and permission to automate external targets.
    - Claims that a dependency declaration or a workplan proves executed browser usage.
  assumptions:
    - Source-adaptation consumers install matching browsers; provider clients need only Python 3.10+.
    - Provider consumers establish an available endpoint and run preflight before a trial.
  use_cases:
    - Find which working repos already use a headless browser and where to start reusing it.
    - Run a local UI assertion and screenshot in a target repo before adopting the tooling.
availability:
  current_level: A5
  target_level: A6
  current_artifacts:
    - forgejo.coulomb.social/coulomb/rapp-playwright@sha256:8d6fd5a8172cf906bb503642ed620761945c5138b86f6396c36f65cbe6def441
    - https://forgejo.coulomb.social/coulomb/rapp-playwright/raw/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/client/rapp_playwright.py
    - https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/releases/0.1.0.json
    - ../whynot-design/playwright.config.mjs
    - ../whynot-design/tests/visual/ui-kit.spec.mjs
    - ../coulomb-social/scripts/test-usecase-browser.mjs
    - ../core-hub/scripts/check_console_visual.py
    - ../frontend-patterns/research/experiments/navigation-history/experiment.mjs
  target_artifacts:
    - >-
      Managed Railiance deployment after platform admission, with consumer
      independent per-caller access and complete recovery/rollback acceptance; the
      supervised build pilot already has actual human/agent receipts.
  consumption_modes: [informational, source adaptation, JavaScript library, Python library, cli, service API, container]
relations:
  depends_on: []
  supports: []
  related_to: []
evidence:
  documentation:
    - https://playwright.dev/docs/browsers
    - ../frontend-patterns/research/experiments/navigation-history/README.md
    - ../test-driver/SCOPE.md
    - ../testdrive-jsui/pyproject.toml
    - https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/docs/consumer-contract.md
    - https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/docs/evidence/2026-10-13-publication.md
    - intakes/REUSE-IN-0001-headless-browser-runnable-answer.md
  tests:
    - https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/docs/evidence/2026-10-13-independent-local-consumer.md
    - docs/evidence/2026-10-13-browser-discovery.md
    - ../whynot-design/tests/visual/ui-kit.spec.mjs
    - ../coulomb-social/scripts/test-usecase-browser.mjs
    - ../core-hub/scripts/check_console_visual.py
    - ../frontend-patterns/research/experiments/navigation-history/result.json
  consumer_feedback:
    - >-
      2026-10-13 content-explorer, REUSE-IN-0001: published source examples did not
      provide a verified runnable path for screenshots and keyboard interaction.
      The false-new plan-check verdict is a registry discovery issue, not evidence
      that a new browser stack is needed. Browser delivery belongs to the provider.
consumer_guidance:
  recommended_for:
    - Use Playwright with headless Chromium for a new repo's general UI automation trial.
    - Reuse whynot-design for JavaScript visual tests and core-hub for Python visual checks.
    - Reuse coulomb-social for JavaScript browser scripts and frontend-patterns for multi-engine experiments.
    - >-
      For bounded screenshot and keyboard jobs, use the published rapp-playwright
      Python client against an available local provider and run preflight first.
      Use the immutable container to reproduce the provider; managed Railiance
      access requires admission and a working tunnel before consumption.
  not_recommended_for:
    - Treating this recommendation as an approved mandatory estate standard.
    - Selecting test-driver as an implemented JavaScript-capable browser engine.
    - Introducing Selenium or Puppeteer merely because their names match a discovery query.
  known_limitations:
    - This is a dated source inspection; run the target-repo trial before claiming adoption success.
    - Firefox is evidenced in frontend-patterns; WebKit is supported upstream but unverified in this inspection.
    - Selenium is an optional testdrive-jsui dependency, not verified execution; Puppeteer has no verified example here.
    - Local provider availability is verified but ephemeral; managed admission and platform operation remain pending.
    - Provider fixture success does not establish consumer target reachability or application acceptance.
promotion_history:
  - date: "2026-10-13"
    dimension: availability
    from: A2
    to: A5
    rationale: >-
      Published immutable rapp-playwright 0.1.0 container, versioned client/contract
      and independent local release receipts satisfy deployable-container availability.
      This is not an A6 managed-platform claim. D3, C2 and R2 remain conservative
      assessments pending broader target and operational evidence.
    author: codex
---

# Headless Browser Automation

## Recommendation

Start with **Playwright controlling headless Chromium** for general browser
automation, UI tests, screenshots and JavaScript-rendered page extraction.
This follows implemented usage in four working repos. Playwright is the automation
library; Chromium is the browser engine. Use `@playwright/test` for a JavaScript
test suite, the `playwright` library for standalone JavaScript scripts, or Python
`playwright` when the consumer is Python.

This is a reuse recommendation reviewed against source on **2026-10-13**, not a
mandatory estate standard or a benchmark verdict against Selenium/Puppeteer.
reuse-surface maintains this discovery record; the example repos maintain their
implementations and the upstream Playwright project maintains the library.

## Service provider and delivery status

**rapp-playwright 0.1.0 is published and verified as a local container provider.**
The current vector is **D3 / A5 / C2 / R2**. A5 means a deployable container under
[the maturity standard](../../specs/CapabilityMaturityStandard.md); managed
platform operation is A6 and remains **pending Railiance admission**. Source
examples remain available at A2. No browser is installed on the caller's machine
by discovery or by running the Python client.

`rapp-playwright` owns the browser service; `railiance-platform` owns managed
lifecycle admission. `reuse-surface` owns this record, discovery, consumption
guidance and evidence assessment. The
[content-explorer intake](../../intakes/REUSE-IN-0001-headless-browser-runnable-answer.md)
concerns registry relevance and availability clarity; CONTENT-WP-0000-T04
acceptance remains with the consumer.

### Verified client path

Only Python 3.10+ is needed by the consumer. Download the single revision-pinned
client into a working directory; a sibling checkout is not required:

```sh
curl -fL --output rapp_playwright.py https://forgejo.coulomb.social/coulomb/rapp-playwright/raw/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/client/rapp_playwright.py
python3 rapp_playwright.py --url http://127.0.0.1:18083 preflight
python3 rapp_playwright.py --url http://127.0.0.1:18083 trial --out trial-01
```

Use a fresh output directory for each run. Port **18083** was verified on this
workstation on **2026-10-13**; it is an ephemeral local provider, not a permanent
or remotely reachable endpoint. Preflight must report `available: true`, API 1,
service 0.1.0, Playwright **1.64.0**, Chromium **156.0.8078.4**, and the expected
release/location. Connection failure means the provider or tunnel is unavailable,
not that another browser capability is needed. Use the local setup below or the
source-adaptation fallback. Repeat `--url` on later status/download commands.

The fixture trial checks Tab focus, Enter activation and the counter assertion
across **1280×800** and **390×844** viewports, then downloads screenshots and a
receipt. It does not inspect or accept the consumer's own UI. `run.json` is a
private run handle and must not be published. For `trial`/`run`, exit 0 means
passed, 2 means UI assertion failed, and 3 means infrastructure/setup or another
unsuccessful result; `status` exit 0 only means retrieval succeeded.

### Reproduce the local provider

The published release targets **linux/amd64**. With Docker and image pull access,
start the immutable container in one terminal, then point the client at port
**18081** in another:

```sh
docker run --rm --name rapp-playwright-local --read-only \
  --tmpfs /tmp:rw,size=512m --shm-size=256m --memory=1g --cpus=1 \
  --cap-drop ALL --security-opt no-new-privileges \
  --mount type=volume,src=rapp-playwright-local-data,dst=/data \
  -p 127.0.0.1:18081:8080 -e HOST=0.0.0.0 \
  -e EXECUTION_LOCATION=workstation-container \
  -e RELEASE_ID=sha256:8d6fd5a8172cf906bb503642ed620761945c5138b86f6396c36f65cbe6def441 \
  forgejo.coulomb.social/coulomb/rapp-playwright@sha256:8d6fd5a8172cf906bb503642ed620761945c5138b86f6396c36f65cbe6def441
python3 rapp_playwright.py --url http://127.0.0.1:18081 preflight
python3 rapp_playwright.py --url http://127.0.0.1:18081 trial --out trial-local-01
```

This is the provider's documented local setup with the published digest pinned;
it was not redeployed by this registry review. Existing independent final-release
receipts and the fresh discovery trial use the same digest. The default fixture
requires no external target grant. The provider supports trusted/synthetic pages,
not hostile-page or mutually untrusted tenant execution.

### Supervised managed development path — verified 2026-10-18

The existing private deployment was used by one actual human and one coding
agent, each completing 14 keyboard/responsive steps with downloaded screenshots.
This build profile uses an existing authenticated workstation connection;
independent per-caller identity, transport and final managed admission remain open.
Establish that existing connection, then use the same supported provider client:

```sh
kubectl -n playwright port-forward deployment/playwright 18081:8080 --address 127.0.0.1
# In another terminal, while the tunnel remains running:
python3 rapp_playwright.py preflight
python3 rapp_playwright.py trial --out trial-managed-01
```

Both managed trials passed against the deployed release digest already listed
above. The client is byte-identical to the pinned published commit.
[Human receipt](https://forgejo.coulomb.social/coulomb/the-custodian/src/commit/17635cb0a76e5595ec06421ab7419ae889f6d731/docs/changes/netkingdom-target-2026-10-18/wp80-build-mode-r1/playwright-human/receipt.json),
[agent receipt](https://forgejo.coulomb.social/coulomb/the-custodian/src/commit/17635cb0a76e5595ec06421ab7419ae889f6d731/docs/changes/netkingdom-target-2026-10-18/wp80-build-mode-r1/playwright-agent/receipt.json),
and [profile/commands](https://forgejo.coulomb.social/coulomb/the-custodian/src/commit/17635cb0a76e5595ec06421ab7419ae889f6d731/docs/changes/netkingdom-target-2026-10-18/wp80-build-mode-r1/README.md)
state the exact scope. Use a fresh output directory; keep the run capability
private. Do not distribute a kubeconfig or treat this receipt as a broader identity
acceptance. Stop the port-forward with Ctrl-C when finished. A remote browser's
localhost belongs to the provider. Consumer applications need a
provider-reachable, explicitly allowed origin; the browser API tunnel does not
forward a workstation app. See the provider contract before running a target
scenario.

### Pinned delivery evidence

All provider links below are pinned to published commit
`8831a05aeba5ce588f3b395ade676dde2a151c5d`:

- [Consumer contract](https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/docs/consumer-contract.md).
- [Release manifest](https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/releases/0.1.0.json)
  and [publication/pull evidence](https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/docs/evidence/2026-10-13-publication.md).
- [Independent consumer evidence](https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/docs/evidence/2026-10-13-independent-local-consumer.md),
  including final-release screenshots, keyboard assertions, wrong-token rejection,
  UI failure and unavailable-service results. These are retained provider-side
  reports; this review separately verified the fixture path.
- [Fresh registry review and trial](../../docs/evidence/2026-10-13-browser-discovery.md).

## Existing implementations

Paths in frontmatter are relative to the reuse-surface repository root. The links
below work with sibling checkouts. The cited files were clean at these revisions.

| Repo and inspected revision | What is implemented | Reuse starting point |
| --- | --- | --- |
| whynot-design — `a79a4d803e9aed13f66d072bf409b6f86000f01f` | Playwright Test, explicitly headless Chromium, screenshot comparisons | [Configuration](../../../whynot-design/playwright.config.mjs), [visual tests](../../../whynot-design/tests/visual/ui-kit.spec.mjs), [dependency/scripts](../../../whynot-design/package.json) |
| coulomb-social — `5c32757b987ab1610cdb46a808d56c75f569f581` | JavaScript Playwright scripts launching headless Chromium for browser tests and extraction | [Use-case test](../../../coulomb-social/scripts/test-usecase-browser.mjs), [script dependency](../../../coulomb-social/scripts/package.json) |
| core-hub — `a69ad325271485afe284a6db85673dfa30d9d4ad` | Python synchronous Playwright visual checks launching Chromium with the default headless mode | [Visual-check script](../../../core-hub/scripts/check_console_visual.py), [development dependency](../../../core-hub/pyproject.toml) |
| frontend-patterns — `047a6a2d314ff5a9d2a87d5bc987d7d84835f682` | Playwright experiments using Chromium and Firefox, with retained execution receipts | [Runner](../../../frontend-patterns/research/experiments/navigation-history/experiment.mjs), [setup and limitations](../../../frontend-patterns/research/experiments/navigation-history/README.md), [result](../../../frontend-patterns/research/experiments/navigation-history/result.json) |

These are source/retained-receipt observations, not newly executed test results.
The frontend-patterns example uses an explicit Chromium binary override; do not
copy its workstation paths as a portable browser installation recipe.

## Alternatives and misleading matches

- **Selenium:** [testdrive-jsui's optional development dependencies](../../../testdrive-jsui/pyproject.toml)
  declare it at `701341d7fa520f860245e28eb16d44b767fd116b`. A declaration alone
  does not establish an implemented or passing browser workflow.
- **test-driver:** [SCOPE.md](../../../test-driver/SCOPE.md) at
  `c3ad06e598057862cf500cbd46c7c8b6f83885ed` explicitly excludes a browser engine,
  JavaScript execution, screenshots and DOM timing. Historical Playwright plans
  are not an available implementation.
- **Puppeteer:** no verified implementation was found in this inspection. This
  is not a claim that every working repo has been exhaustively searched.
- **Firefox/WebKit:** Playwright supports both upstream. Firefox has retained
  experiment evidence here; WebKit has no verified local example in this record.

## Source-adaptation fallback for the consuming worker

1. Query this checkout with `python3 -m reuse_surface.cli query --keyword browser`
   from the reuse-surface root, then open this entry. If the CLI is installed,
   `reuse-surface query --keyword browser` is equivalent.
   `plan-check --intent "headless browser" --no-llm` ranks this entry first.
   Its reuse verdict describes relevance; provider preflight determines current
   runtime availability. Use source adaptation when the provider path is unsuitable.
2. Pick the example matching the target repo's language and task. Inspect its
   fixture/server assumptions before adapting the smallest useful test or script.
3. Use the target repo's package manager and lockfile. Select a compatible
   Playwright version and install its matching Chromium binary. For an installed
   Node dependency, use `npx playwright install chromium`; for an installed Python
   dependency, use `python -m playwright install chromium` in its environment.
   Follow the upstream [browser/system-dependency instructions](https://playwright.dev/docs/browsers)
   if system libraries are missing. No common estate version is established here.
4. Against a local fixture or the target repo's local development server, launch
   headless Chromium, load one page, assert one meaningful rendered element or
   interaction, save a screenshot if relevant, and close the browser. Exercise
   a JavaScript-driven change if JavaScript rendering is the reason for adoption.
5. Report the consumer repo, reference example, package/browser versions, exact
   command, assertion outcome, artifact paths and any setup failure. The trial
   remains unverified until this evidence exists; installation alone is not success.

The hosted service reads published repository indexes. A local edit does not
by itself make this entry available at `reuse.coulomb.social`; use the local query
above for an unpublished trial and verify the hosted entry after publication.