# Frontend Automation

Playwright end-to-end test suite for the **PassDashboard** merchant portal
(NeoPass), extracted into its own repository so it can be run and deployed
independently of the application.

The tests drive the real, deployed application over HTTP — there is no
application code, build step, or local dev server in this repo. That is what
makes standalone operation possible: point the suite at a URL, give it
credentials, and run.

> The Jest unit tests under `src/__tests__/` in the app repo are **not** part
> of this suite. They import application source directly (`AuthContext`,
> `ProtectedRoute`, `cryptoUtils`, `api`) and therefore have to live alongside
> that source. They remain in the PassDashboard repo.

## Quick start

```bash
npm ci
npx playwright install --with-deps chromium

cp .env.test.example .env.test.local   # then fill in real credentials
npm run test:e2e:dev
```

## Environments

Environment and credentials are resolved in one place —
[tests/helpers/environment.ts](tests/helpers/environment.ts). It reads an `ENV`
variable and picks the matching base URL and credential pair. Both
[playwright.config.ts](playwright.config.ts) and
[tests/helpers/auth.ts](tests/helpers/auth.ts) read through it, so adding or
changing an environment is a one-file edit.

`ENV` accepts either branch-style names (`develop` / `staging` / `main`) or
semantic names (`dev` / `staging` / `production`) — they map to the same thing.

| Command | Target |
| --- | --- |
| `npm run test:e2e:dev` | `DEV_URL` (falls back to the shared staging URL) |
| `npm run test:e2e:staging` | `https://stagingenv.babinnovations.com` |
| `npm run test:e2e:prod` | `https://www.babinnovations.com/neopaas/portal` |
| `npm run test:e2e:ui` | Playwright UI mode, using `ENV` / `.env.test.local` as-is |

Set `BASE_URL` to override the resolved URL entirely.

## Running a subset

```bash
npx playwright test tests/refunds.spec.ts
npx playwright test -g "should paginate through transaction list"
npx playwright test tests/dashboard.spec.ts --headed
npm run report          # open the last HTML report
```

## Credentials

`.env.test.local` is git-ignored via the `*.local` pattern and is only read for
local runs. CI never uses it — the workflow sets the same variable names from
Gitea Actions secrets. See [.env.test.example](.env.test.example) for the full
list and the fallback behaviour.

Required secrets in **Settings → Actions → Secrets** for CI:

| Secret | Needed for |
| --- | --- |
| `DEV_URL`, `DEV_USERNAME`, `DEV_PASSWORD` | `ENV=develop` |
| `TEST_USERNAME`, `TEST_PASSWORD` | shared fallback for dev and staging |
| `STAGING_TEST_USERNAME`, `STAGING_TEST_PASSWORD` | `ENV=staging` (optional; falls back to `TEST_*`) |
| `PROD_TEST_USERNAME`, `PROD_TEST_PASSWORD` | `ENV=main` — required, never falls back |

Production credentials are deliberately kept separate so a dev credential pair
can never accidentally run against production.

## CI

[.gitea/workflows/e2e-tests.yml](.gitea/workflows/e2e-tests.yml) runs on Gitea
Actions. Because this repo has no per-environment branches, the target is an
explicit `workflow_dispatch` input rather than being derived from the branch
name; scheduled and push runs default to `develop`. The Playwright HTML report
and Allure results are uploaded as build artifacts.

Requires a Gitea Actions runner with the `ubuntu-latest` label. If your runner
uses a different label, change `runs-on` in the workflow.

## Suite layout

See [tests/README.md](tests/README.md) for the per-spec breakdown, the helper
modules, and the list of known gaps / intentionally uncovered areas.

**When adding a spec file:** `playwright.config.ts` uses an explicit
`testMatch` allowlist, not a wildcard glob. A new spec file that isn't added to
that list will silently never run.