# admin-web E2E tests (Playwright)

End-to-end tests that drive the admin panel (`apps/admin-web`) through real
browser workflows. Long, multi-step tasks run sequentially in a **single
browser instance** (one worker, one page), mirroring how an admin works.

## Setup

1. Install Playwright + the browser (one time, from the repo root):

   ```bash
   npm i -D @playwright/test
   npx playwright install chromium
   ```

2. Start the admin panel and note its URL (defaults to `http://localhost:4175`):

   ```bash
   npm run admin-web:dev
   ```

3. Configure credentials — copy the template and fill it in:

   ```bash
   cp tests/.env.test.example tests/.env.test
   # then set TEST_STAFF_NAME / TEST_STAFF_PASSWORD (and TEST_BASE_URL if needed)
   ```

   `tests/.env.test` is gitignored. When credentials are missing the whole
   suite **skips** with a clear message instead of failing.

## Running

Run from the **repo root** (recommended — picks up `playwright.config.ts`):

```bash
bun run test:e2e          # all specs (browser visible locally)
bun run test:e2e:headed   # explicit headed run
bun run test:e2e:ui       # Playwright UI mode (debug/inspect, time-travel)
bun run test:e2e tests/specs/product-lifecycle.spec.ts   # one workflow
```

Run from inside `tests/` — you must point at the root config, otherwise
Playwright finds no config and skips the login setup:

```bash
cd tests
bun run --cwd .. test:e2e          # easiest
bunx playwright test -c ../playwright.config.ts
bunx playwright test -c ../playwright.config.ts --headed
bunx playwright show-report ../playwright-report
```

> ⚠️ Don't run a bare `bunx playwright test` from `tests/` — it runs without the
> config (no auth setup, no `baseURL`). Always pass `-c ../playwright.config.ts`.

The browser is **visible by default** locally (headed). It only runs headless in
CI, or when you opt in explicitly:

```bash
HEADED=0 bun run test:e2e   # force headless locally
HEADED=1 bun run test:e2e   # force headed
bunx playwright test -c ../playwright.config.ts --headed --slow-mo=500   # watch slowly
```

Point the tests at a different UI URL (e.g. a hosted environment):

```bash
TEST_BASE_URL=https://admin.example.com bun run test:e2e
```

## How it works

- `auth.setup.ts` logs in once (`data-testid` login fields) and saves the
  session to `tests/.auth/staff.json`. The `chromium` project reuses that
  `storageState`, so specs start already authenticated.
- `tests/helpers/admin-app.ts` is a small page object with the reusable
  actions (add/update product, create slot, suspend SKU, dialog handling).
- Specs live in `tests/specs/`. `product-lifecycle.spec.ts` is the long
  single-instance workflow: **create product → update it → create a slot for it
  → suspend it**, plus a persistence re-check.

## ⚠️ Warning

These tests **create real catalog records** (products, slots) on whatever
backend the running admin-web instance points at. Use a non-production backend
when running them.

## Adding more workflows

Add a sibling spec under `tests/specs/` (matching `*.spec.ts`) and reuse the
helpers in `tests/helpers/admin-app.ts`. Prefer `data-testid` selectors for new
UI; the admin-web components expose test ids where placeholder/role locators
would be brittle.