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