# E2E Test Suite

Playwright end-to-end tests for the PassDashboard merchant portal. These
tests drive the real, deployed application over HTTP - they don't run
against a local build - so this folder can be copied into any checkout of
the repo (even a newer one) and will keep working as long as the app's URLs
and selectors haven't changed.

## Folder structure

```
tests/
  helpers/
    environment.ts   # single source of truth for env + credential resolution
    auth.ts           # login()/loginAs() - reads TEST_CREDENTIALS from environment.ts
    navigation.ts     # navigateToX(page) helpers for each portal page
    allure.ts         # thin wrappers around Allure annotations (epic/feature/severity/tag)
  auth.spec.ts         # login, invalid credentials, required-field validation, logout
  dashboard.spec.ts    # stat cards, dropdown filter, date-range download, weekly sales chart
  transactions.spec.ts # search/filter, date range, details, export, pagination
  terminals.spec.ts    # details, pagination, download, cashier remove/reassign, add terminal
  refunds.spec.ts      # search/filter, date range, details, export, pagination
  discounts.spec.ts    # cross-checks Transactions-page totals against the Discounts page
  settlement.spec.ts   # download -> format -> upload -> run settlement workflow
  management.spec.ts   # Users/Branches tabs: add cashier/finance user, add branch, reports
  settings.spec.ts      # Discount Rate Configuration (Settings > Discount rates tab)
  roles.spec.ts         # creates Cashier/Finance/Terminal Manager users, logs in as each,
                         # verifies their actual restricted navigation menu
```

Each spec file corresponds to one page/feature area of the portal. Shared
logic (login, navigation, environment/credential resolution) lives in
`helpers/` so spec files stay focused on the feature they're testing.

## Running against dev / staging / production

Environment and credentials are resolved once, centrally, in
`helpers/environment.ts`. It reads an `ENV` variable (accepts branch names
`develop`/`staging`/`main` - what CI naturally has on hand - or semantic
names `dev`/`staging`/`production`) and picks the matching base URL and
credential pair. `playwright.config.ts` and `helpers/auth.ts` both import
from this one module, so there is nowhere else that needs updating to add
or change an environment.

### Local setup (one-time)

```bash
cp .env.test.example .env.test.local
# then fill in your real credentials in .env.test.local
```

`.env.test.local` is git-ignored (matches the `*.local` pattern already in
`.gitignore`) - it never gets committed, and CI doesn't use it at all (CI
sets the same variable names directly from GitHub Secrets - see
`CI-CD-SETUP.md`).

### Running tests

```bash
npm run test:e2e:dev       # https://devpro.babinnovations.com
npm run test:e2e:staging   # https://staging.babinnovations.com
npm run test:e2e:prod      # https://www.babinnovations.com/neopaas/portal

npm run test:e2e:ui        # Playwright's interactive UI mode (uses ENV/.env.test.local as-is)

# Run a single file or a single test by name, same as any Playwright project:
npx playwright test tests/refunds.spec.ts
npx playwright test -g "should paginate through transaction list"

# Watch it run in a real browser window instead of headless:
npx playwright test tests/dashboard.spec.ts --headed
```

### Adding a new environment or changing a URL

Edit `baseURLs` and/or `credentials` in `helpers/environment.ts` - that's
the only file that needs to change. Everything else (playwright.config.ts,
auth.ts, CI workflow) reads through it.

## Adding a new spec file

Playwright is configured with an explicit `testMatch` allowlist in
`playwright.config.ts` (not a wildcard glob) - **new spec files must be
added to that list** or they'll silently never run. This bit us once
already (`settings.spec.ts` and `roles.spec.ts` were invisible to the
runner until added).

## Known gaps / intentionally not covered

- **Reconciliation page** - out of scope for now
- **Bulk disable/enable** (Terminals page) - requires a genuinely active
  physical POS terminal to succeed server-side; not reliably reproducible
  in the dev environment, so it isn't automated
- **Terminals > Bulk Upload**, **Settings > Account/Response Timeout/
  Merchant Token/Trusted devices tabs**, **Dashboard notifications panel**,
  **Arabic/RTL rendering**, **Forgot Password / 2FA** - never explored yet
- **Discount rate creation** (Settings > Discount rates > Create) - blocked
  by a dev-environment data gap (the Card name dropdown has no options to
  select), flagged as a product issue rather than fixed in the test
- A separate Jest unit-test layer exists under `src/__tests__/` - unrelated
  to this Playwright suite and not covered by anything above