2026-10-13 13:56:33 +02:00
---
id: capability.infotech.headless-browser
name: Headless Browser Automation
summary: >-
2026-10-13 20:48:05 +02:00
Headless browser automation, screenshots and keyboard trials through
rapp-playwright 0.1.0 (Playwright 1.64.0, Chromium 156.0.8078.4).
Published A5 local container; managed Railiance admission is pending.
Download the Python 3.10+ standalone client from
https://forgejo.coulomb.social/coulomb/rapp-playwright/raw/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/client/rapp_playwright.py
and run `python3 rapp_playwright.py --url http://127.0.0.1:18083 preflight` ,
then `python3 rapp_playwright.py --url http://127.0.0.1:18083 trial --out trial-01`
with a fresh output directory. This endpoint was verified locally on 2026-10-13
and is ephemeral; it installs no browser for the caller. If unreachable,
follow the local container setup in the capability card or adapt its A2 source
examples; this is an availability gap on the existing capability.
Contract: https://forgejo.coulomb.social/coulomb/rapp-playwright/src/commit/8831a05aeba5ce588f3b395ade676dde2a151c5d/docs/consumer-contract.md.
2026-10-13 13:56:33 +02:00
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:
2026-10-13 20:48:05 +02:00
current: A5
target: A6
2026-10-13 13:56:33 +02:00
confidence: medium
rationale: >
2026-10-13 20:48:05 +02:00
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).
Railiance admission is pending. Existing A2 source adaptation remains usable;
no endpoint uptime or caller browser installation is implied.
2026-10-13 13:56:33 +02:00
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.
2026-10-13 20:48:05 +02:00
- Published provider client and container have independent fixture screenshots and keyboard receipts.
2026-10-13 13:56:33 +02:00
broken_expectations:
2026-10-13 20:48:05 +02:00
- Managed admission and persistent platform endpoint are still pending.
- Consumer application acceptance remains the consuming repo's responsibility.
2026-10-13 13:56:33 +02:00
out_of_scope_expectations:
- Exhaustive estate dependency inventory or comparative browser benchmark.
2026-10-13 16:02:38 +02:00
- Browser service implementation or operation by reuse-surface.
- Mandatory estate-wide technology policy.
2026-10-13 13:56:33 +02:00
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.
2026-10-13 20:48:05 +02:00
- Local fixture receipts do not prove managed operation or arbitrary target compatibility.
- Local provider endpoints are ephemeral; check preflight for each trial.
2026-10-13 13:56:33 +02:00
evidence:
satisfied_signals:
- frontend-patterns navigation-history records a completed Chromium/Firefox experiment.
2026-10-13 20:48:05 +02:00
- 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.
2026-10-13 13:56:33 +02:00
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.
2026-10-13 20:48:05 +02:00
- Published rapp-playwright container, Python client and bounded HTTP fixture trials.
2026-10-13 13:56:33 +02:00
excludes:
2026-10-13 16:02:38 +02:00
- Browser hosting or workstation provisioning by reuse-surface.
- Credential provisioning and permission to automate external targets.
2026-10-13 13:56:33 +02:00
- Claims that a dependency declaration or a workplan proves executed browser usage.
assumptions:
2026-10-13 20:48:05 +02:00
- 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.
2026-10-13 13:56:33 +02:00
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:
2026-10-13 20:48:05 +02:00
current_level: A5
target_level: A6
2026-10-13 13:56:33 +02:00
current_artifacts:
2026-10-13 20:48:05 +02:00
- 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
2026-10-13 13:56:33 +02:00
- ../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
2026-10-13 16:02:38 +02:00
target_artifacts:
- >-
2026-10-13 20:48:05 +02:00
Managed Railiance deployment after platform admission, with consumer
access and live recovery/rollback evidence; not currently available.
consumption_modes: [informational, source adaptation, JavaScript library, Python library, cli, service API, container]
2026-10-13 13:56:33 +02:00
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
2026-10-13 20:48:05 +02:00
- 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
2026-10-13 16:02:38 +02:00
- intakes/REUSE-IN-0001-headless-browser-runnable-answer.md
2026-10-13 13:56:33 +02:00
tests:
2026-10-13 20:48:05 +02:00
- 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
2026-10-13 13:56:33 +02:00
- ../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
2026-10-13 16:02:38 +02:00
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.
2026-10-13 13:56:33 +02:00
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.
2026-10-13 16:02:38 +02:00
- >-
2026-10-13 20:48:05 +02:00
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.
2026-10-13 13:56:33 +02:00
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.
2026-10-13 20:48:05 +02:00
- 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
2026-10-13 13:56:33 +02:00
---
# 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.
2026-10-13 16:02:38 +02:00
## Service provider and delivery status
2026-10-13 20:48:05 +02:00
**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× and **390× 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.
### Conditional managed path
Only **after platform admission, deployment and caller access are confirmed** :
```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
```
No managed deployment or successful managed invocation is claimed here. 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 ).
2026-10-13 16:02:38 +02:00
2026-10-13 13:56:33 +02:00
## 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.
2026-10-13 20:48:05 +02:00
## Source-adaptation fallback for the consuming worker
2026-10-13 13:56:33 +02:00
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.
2026-10-13 20:48:05 +02:00
`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.
2026-10-13 13:56:33 +02:00
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.
