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

---
id: capability.infotech.headless-browser
name: Headless Browser Automation
summary: >-
  Headless browser automation with Playwright and Chromium for UI testing,
  screenshots and page extraction; recommended default based on existing
  whynot-design, coulomb-social, core-hub and frontend-patterns implementations.
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: A2
    target: A2
    confidence: medium
    rationale: >
      Existing JavaScript and Python source examples can be adapted in a consumer
      repo. This entry does not deliver a shared wrapper or hosted browser service.
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.
    broken_expectations:
      - No shared package, standard configuration or consumer-independent trial receipt.
    out_of_scope_expectations:
      - Exhaustive estate dependency inventory or comparative browser benchmark.
      - Managed browser service or 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.
      - Browser launch and target-repo compatibility have not been tested by this registration.
    evidence:
      satisfied_signals:
        - frontend-patterns navigation-history records a completed Chromium/Firefox experiment.
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.
  excludes:
    - Browser hosting, credential provisioning and permission to automate external targets.
    - Claims that a dependency declaration or a workplan proves executed browser usage.
  assumptions:
    - The consumer chooses a version compatible with its runtime and installs matching browsers.
  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: A2
  target_level: A2
  current_artifacts:
    - ../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
  consumption_modes: [informational, source adaptation, JavaScript library, Python library]
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
  tests:
    - ../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: []
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.
  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.
promotion_history: []
---

# 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.

## 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.

## Practical trial 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` also includes this candidate,
   but its token-overlap thresholds and maturity tie-breaking currently return
   `new` for this short query. That verdict does not establish absence of reuse;
   use the explicit keyword query and read the evidence for this trial.
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.