> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 0068 — Platform acceptance tests with Playwright and Gherkin

Status: Accepted. Date: 31 October 2026. Integration clarified: 3 November 2026.

## Context

Pharos needs repeatable evidence that researchers can discover public resources,
sign in, obtain resources, work with repositories, run actions and access an HPC
login node. Product stakeholders must be able to read and review those expectations.
The existing service, browser and provider checks cover individual boundaries;
the complete acceptance journey needs its own scenario catalogue and evidence.

The retained Themelio experience is the initial target.
[PR #976](https://github.com/pharos-ai-factory/pharos-platform/pull/976)
(`split/governance-legacy-ui`) restores API-owned AAI sessions, onboarding,
the browser shell and SSH settings above the backend in #995.
The base acceptance suite landed on `main` in
[PR #987](https://github.com/pharos-ai-factory/pharos-platform/pull/987).
`feat/canonical-project-run-ui` adds canonical Project, repository and Run views
and adapts the suite to their identities, paths and cleanup commands.
Its live target needs all three layers. Scenario generation, TypeScript checks and
harness unit tests can run before that deployment exists. Some requested
capabilities remain demonstrations, require separate deployment activation or
have incomplete user-facing contracts. Their implementation status must be visible.

## Decision

Use **Playwright Test, TypeScript and Gherkin through `playwright-bdd`** for the
Pharos Platform Acceptance Suite. Start with **ad hoc runs** against an explicitly
configured deployment containing that working UI and its matching API/backend.
This decision introduces no automatic CI job, schedule or release gate.
Live failures caused by unavailable application capabilities do not block merging
the suite; reports must retain those failures until the target supports the journeys.

1. Stakeholders review `.feature` files as the acceptance specification. TypeScript
   step definitions connect the business language to browser and protocol helpers.
   Playwright remains the test runner; `playwright-bdd` generates its executable
   tests. Pin both dependencies and keep generated test output ignored.
2. Exercise the user interface for the behaviour being accepted. Use real Git and
   SSH clients for those protocols and supported APIs for preparation, cleanup and
   additional observations. Test data and observer code have no owner-database
   access. Mocked harness checks remain distinct from live acceptance evidence.
3. Keep scenarios independently runnable with explicit prerequisites, unique data
   and owned cleanup. Start with one worker and zero automatic retries. Missing
   prerequisites and cleanup failures fail the selected scenario. Planned
   specifications stay outside executable discovery and outside pass counts.
4. Use dedicated test identities and disposable Projects, scoped credentials and
   verified HTTPS/SSH trust. Keep credentials and session state out of source and
   reports. Disable credential-bearing browser captures by default. Administrator
   setup remains in the existing administrative tools.
5. Record the target, deployed revision, test revision, scenario result and duration.
   Provide Playwright diagnostics and a Gherkin HTML report. Distinguish local
   AAI from external federation, UI notification from email delivery, and SSH
   login from Slurm execution. A shorter suite establishes only its named scope.
6. Preserve valid behavioural scenarios as implementation moves to the replacement
   services. Update owner/UI helpers at the public boundaries. Intentional changes
   to accepted behaviour require scenario review.

The <a href="/source/acceptance/README.md.txt">suite guide</a> owns commands, prerequisites,
coverage and extension conventions. [TESTING.md](/reference/TESTING.md) links to that
guide alongside the existing verification lanes.

## Alternatives considered

- **Plain Playwright TypeScript with named steps:** fewer dependencies, but the
  stakeholder specification remains embedded in executable code.
- **Cucumber.js with the Playwright browser library:** supports Gherkin, but uses a
  separate runner and needs its own lifecycle/reporting integration. The selected
  adaptor retains Playwright Test's fixtures and tooling.
- **pytest with Playwright or Robot Framework:** viable for Python-owned or
  keyword-driven automation. TypeScript extends the browser tooling already in
  this repository.
- **One complete serial journey:** useful as a later small release selection;
  independent scenarios provide more precise failure evidence and selective runs.

## Consequences and follow-up

The suite adds a community-maintained dependency and a step-definition vocabulary.
Engineers must keep these mappings meaningful and review runner compatibility on
upgrades. Gherkin readability depends on shared review and concrete assertions.

Runtime budgets remain unmeasured until repeated live runs are available. A later
decision can select a fast, reliable subset for CI and define release acceptance
requirements using measured duration, infrastructure availability and failure
rates. The full requested journey remains explicitly tracked while capabilities
and their executable scenarios are completed.

## References

- [Playwright Test](https://playwright.dev/docs/intro)
- [Playwright-BDD](https://github.com/vitalets/playwright-bdd)
- [Gherkin reference](https://cucumber.io/docs/gherkin/reference/)

<details class="page-source"><summary>Page source</summary>

<a href="/source/docs/decisions/0068-platform-acceptance-tests.md.txt">Source snapshot</a> · Revision `f928834c8`.

</details>