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

id	name	summary	owner	status	domain	tags	maturity	external_evidence	discovery	availability	relations	evidence	consumer_guidance	promotion_history
capability.infotech.headless-browser	Headless Browser Automation	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: 8831a05aeb/docs/consumer-contract.md.	reuse-surface	reviewed	infotech	headless browser automation playwright chromium testing screenshots extraction firefox webkit selenium puppeteer	discovery availability current target confidence rationale D3 D4 medium Inspected four implemented Playwright consumers and separated optional dependencies and plans from usage. No comprehensive alternatives benchmark. current target confidence rationale A5 A6 medium 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.	completeness reliability level confidence basis satisfied_expectations broken_expectations out_of_scope_expectations C2 medium scope_vs_intent_and_consumer_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. 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. Exhaustive estate dependency inventory or comparative browser benchmark. Browser service implementation or operation by reuse-surface. Mandatory estate-wide technology policy. level confidence basis known_reliability_risks evidence R2 medium consumer_quality_signals 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. 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.	intent includes excludes assumptions use_cases Help a worker select and reuse existing headless browser tooling instead of independently introducing another automation stack. 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. 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. 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. 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.	current_level target_level current_artifacts target_artifacts consumption_modes A5 A6 forgejo.coulomb.social/coulomb/rapp-playwright@sha256:8d6fd5a8172cf906bb503642ed620761945c5138b86f6396c36f65cbe6def441 8831a05aeb/client/rapp_playwright.py 8831a05aeb/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 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. informational source adaptation JavaScript library Python library cli service API container	depends_on supports related_to	documentation tests consumer_feedback https://playwright.dev/docs/browsers ../frontend-patterns/research/experiments/navigation-history/README.md ../test-driver/SCOPE.md ../testdrive-jsui/pyproject.toml 8831a05aeb/docs/consumer-contract.md 8831a05aeb/docs/evidence/2026-10-13-publication.md intakes/REUSE-IN-0001-headless-browser-runnable-answer.md 8831a05aeb/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 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.	recommended_for not_recommended_for known_limitations 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. 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. 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.	date dimension from to rationale author 2026-10-13 availability A2 A5 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. 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; 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 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:

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:

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:

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, agent receipt, and profile/commands 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.
• Release manifest and publication/pull evidence.
• Independent consumer evidence, 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.

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, visual tests, dependency/scripts
coulomb-social — 5c32757b987ab1610cdb46a808d56c75f569f581	JavaScript Playwright scripts launching headless Chromium for browser tests and extraction	Use-case test, script dependency
core-hub — a69ad325271485afe284a6db85673dfa30d9d4ad	Python synchronous Playwright visual checks launching Chromium with the default headless mode	Visual-check script, development dependency
frontend-patterns — 047a6a2d314ff5a9d2a87d5bc987d7d84835f682	Playwright experiments using Chromium and Firefox, with retained execution receipts	Runner, setup and limitations, result

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 declare it at 701341d7fa520f860245e28eb16d44b767fd116b. A declaration alone does not establish an implemented or passing browser workflow.
• 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 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.