tegwick
ccf46d8c59
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a13590-a16f-7f60-be60-fd71627bc99d
94 lines
5.1 KiB
Markdown
94 lines
5.1 KiB
Markdown
# INTENT — rapp-playwright
|
|
|
|
## Why this repo exists
|
|
|
|
`rapp-playwright` provides and operates a reusable Playwright and headless
|
|
Chromium environment on Railiance so coding agents can arrange UI testing
|
|
without assembling a browser stack or copying another application's fixtures.
|
|
An agent should be able to discover availability, follow one documented command
|
|
path, exercise a target UI, and retrieve inspectable evidence of the result.
|
|
|
|
The initial demand is content-explorer's `CONTENT-WP-0000-T04`: responsive
|
|
screenshots and a keyboard interaction walkthrough. Its environment lacked a
|
|
browser launcher, and discovery of existing source examples did not supply a
|
|
verified runnable path. [Demand evidence](docs/demand-and-reuse.md) separates
|
|
this delivery gap from reuse-surface's search and ranking defects.
|
|
|
|
## What it owns
|
|
|
|
- The agent consumption contract: availability/preflight, submission or session
|
|
setup, target reachability, execution, results, cleanup, and actionable failures.
|
|
- A reproducible Playwright/Chromium runtime with compatible pinned versions,
|
|
browser dependencies, immutable release identification, and upgrade checks.
|
|
- The thin service and client integration needed to expose that runtime through
|
|
a supported command path, with a minimal consumer-independent example.
|
|
- Per-run isolation, bounded concurrency and duration, cancellation, abandoned
|
|
run cleanup, and artifact lifecycle. Consumers must not see each other's
|
|
browser state or results.
|
|
- The Railiance workload package, health/readiness checks, resource envelope,
|
|
deployment evidence, recovery and rollback instructions.
|
|
- Evidence-backed availability reports and consumption references supplied to
|
|
reuse-surface when the service changes.
|
|
|
|
## Consumer outcome
|
|
|
|
From a fresh agent environment, a documented trial must say whether execution
|
|
is available **now** and where the browser runs. A local browser is not required
|
|
for the intended managed service path. Any required client setup must be named,
|
|
versioned and verified; an optional local fallback must be labeled separately.
|
|
|
|
The trial opens a supplied reachable page, checks a meaningful rendered state,
|
|
captures desktop and narrow-viewport screenshots, and records a short keyboard
|
|
interaction with its observed result. It returns machine-readable status and
|
|
artifact references, plus the exact command, target, package/browser versions,
|
|
timestamps and assertion outcomes. Infrastructure/setup failures must be
|
|
distinguishable from failed UI assertions. A failed run must remain diagnosable.
|
|
|
|
The contract must explain how a remote browser reaches a consumer's development
|
|
server; a workstation's `localhost` is not a remote browser's `localhost`.
|
|
Unreachable targets should produce a useful diagnosis and a supported setup path.
|
|
|
|
## Ownership boundaries
|
|
|
|
Consumers own their applications, fixtures, assertions, target authorization,
|
|
visual baseline decisions, and acceptance of their own tasks. This repo supplies
|
|
execution and evidence; it does not mark content-explorer's task done.
|
|
|
|
Playwright owns its upstream browser automation APIs. Existing consumer examples
|
|
are reuse inputs, not service dependencies or an estate-wide technology mandate.
|
|
Reuse-surface owns capability discovery, relevance, maturity assessment, and the
|
|
existing `capability.infotech.headless-browser` record. This repo owns the
|
|
provider contract and runtime, not a competing registry or a second browser stack.
|
|
|
|
Railiance platform owners govern cluster admission, shared networking and access
|
|
policy. Credential custody and identity stay with their established owners.
|
|
Service access and test authentication must use those lanes when required;
|
|
credentials and browser storage state must not enter ordinary result logs.
|
|
|
|
## Initial scope and later decisions
|
|
|
|
Start with Chromium, one consumer-independent trial, and the content-explorer
|
|
pilot. Native Playwright compatibility is the starting point. The consumption contract decides whether remote sessions, submitted jobs, or a
|
|
combination best satisfies agent use and artifact retrieval. Transport, endpoint, deployment
|
|
binding, package versions, and access mechanism are not selected by this intent.
|
|
|
|
Multi-browser coverage, a general browser farm, unrestricted script execution,
|
|
arbitrary external-site automation, and a visual-baseline approval product are
|
|
outside the initial increment. They require demonstrated demand and explicit
|
|
scope decisions.
|
|
|
|
## Success and availability
|
|
|
|
Success means an independent coding agent follows the published instructions
|
|
without copying sibling fixtures, completes the screenshot/keyboard trial,
|
|
retrieves evidence, and can distinguish a service outage from a UI failure.
|
|
Isolation, timeouts and cleanup must have executed negative-case evidence.
|
|
|
|
Planning, registration, image publication and a successful health check alone do
|
|
not prove this outcome. Availability advances only with runtime and consumer
|
|
receipts. Claims must distinguish a verified local runtime from an admitted managed
|
|
endpoint; neither image publication nor local proof establishes Railiance
|
|
availability.
|
|
|
|
See [SCOPE.md](SCOPE.md) for current facts and [workplans](workplans/README.md)
|
|
for the staged implementation and verification gates.
|