102 lines
4.7 KiB
Markdown
102 lines
4.7 KiB
Markdown
|
# 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
|