# Project plan — playwright_tests

Evidence date: 2026-10-06.

Source repository: `git@bitbucket.org:overdrive/playwright_tests.git`.

Inspected revision: `main` at `41f992c` (2025-11-24, joshgatdew, "Fixup login tests"). The scan-host path `~/projects/sonar_scan/repos/playwright_tests` was not on this machine. The tree below was read from that git revision. Secret values (passwords, tokens, SMTP credentials) are omitted. File paths that contain them are named so they can be rotated.

This plan describes what the repository contains. It does not decide what the suites should become.

There was no `silicon_ark/playwright_tests/` directory before this set.

## Product

`playwright_tests` is not an application. It is a collection of independent Playwright suites, one directory per site hostname. There is no root `package.json`, no shared runner, and no application server in this repository.

| Directory | What is in git at `41f992c` | Target named in config or docs |
|---|---|---|
| `bi.sawisonline.co.za/` | Playwright project, 6 spec files, runner, docs, and a large committed HTML report plus test-result media | `https://bi.sawisonline.co.za` |
| `staging.ipw.co.za/` | Playwright project, 9 spec files, report scripts, MySQL helpers, docs | `http://staging.ipw.co.za` |
| `qa.shopflow.io.dedi1534.jnb2.host-h.net/` | Playwright project, 31 spec files, fixtures, helpers, test data | Default `https://shopflow.php8` via `SHOPFLOW_URL` |
| `label.sawis.co.za/` | `TEST_SPECIFICATION_TEMPLATE.md` only | The prompt inside the template asks for tests of `http://staging.ipw.co.za/`, not this hostname |
| `qa.d3t8evj08x1w1g.amplifyapp.com/` | `TEST_SPECIFICATION_TEMPLATE.md` only | Prompt names `https://qa.d3t8evj08x1w1g.amplifyapp.com/` |
| `sawisonline.co.za/` | `TEST_SPECIFICATION_TEMPLATE.md` and a tracked `.env` | `.env` `BASE_URL` is `https://bi.sawisonline.co.za` |

**Documented** names:

- `bi.sawisonline.co.za/package.json` name `sawis-playwright-tests`, description "UI test cases for SAWIS Business Intelligence Dashboard".
- `bi.sawisonline.co.za/README.md` expands SAWIS as "South African Wine Industry Information & Systems".
- `staging.ipw.co.za/package.json` name `staging-ipw-playwright-tests`.
- ShopFlow README title "ShopFlow Playwright Test Suite". `package.json` name is the generic `playwright`.

**Unknown / Requires Confirmation:** what IPW stands for, what product the Amplify hostname serves, and whether `label.sawis.co.za` and `sawisonline.co.za` were meant to become suites.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `main` (default; `origin/HEAD`) | `41f992c` | 2025-11-24 | Only branch. 4 commits |

Authors: Jaco Brits (2), joshgatdew (2).

| Commit | Date | Author | What landed |
|---|---|---|---|
| `bcee2c5` | 2025-08-19 | Jaco Brits | `.gitignore` only |
| `1973de1` | 2025-11-18 | Jaco Brits | SAWIS BI suite (including committed `playwright-report/` and `test-results/`), IPW staging suite, and the three template directories |
| `15537a0` | 2025-11-19 | joshgatdew | ShopFlow suite |
| `41f992c` | 2025-11-24 | joshgatdew | ShopFlow login/logout and `authentication.ts` fixup; small README, `package.json`, and config edits |

No other local or remote branches were present at inspection.

**Discrepancy:** the task-creation scan listed `sonar-project.properties` and `sonarqube_scan.bat` at the repository root. Neither file is in any commit. No `bitbucket-pipelines.yml` is in the tree. Whether those scan files existed only as untracked files on the scan host is **Unknown**.

## Objectives (inferred from the suites and their READMEs, not from a written plan)

- Exercise the SAWIS BI dashboard in a browser: homepage, login modal, filters, tabs, charts, and page-load timing.
- Exercise ShopFlow as a signed-in user across authentication, commerce, users, partners, pricing, and a seller portal, including optional Gmail IMAP retrieval of a 2FA code.
- Exercise `staging.ipw.co.za` for login, navigation, accessibility, security probes, performance, and post-login pages, and optionally store results in MySQL and email an HTML/PDF report.
- Hold a copied Playwright specification template under hostnames that do not yet have specs.

## Scope

### In scope of `main`

1. Three installable Playwright projects, each with its own `package.json` and config.
2. Specs counted at `41f992c`: 86 `test()` calls under SAWIS BI, 278 under ShopFlow, 68 under IPW staging.
3. ShopFlow support code: `utils/authentication.ts`, `utils/email-2fa-fetcher.ts`, `utils/test-config.ts`, `helpers/`, `fixtures/`, `test-data/`.
4. IPW support code: `scripts/` (DB check, schema check, result save, HTML report, PDF report, email, comprehensive runner, global setup/teardown) and `tests/utils/selectors.ts`.
5. Docs already in the source tree: READMEs, changelogs, `NewKnowledgeBase.md` (BI and IPW), `SETUP_GUIDE.md` (BI), `PROJECT_PATTERNS_AND_RULES.md` and `DATATABLE_NAVIGATION_FIX.md` (ShopFlow), `COMPREHENSIVE_TEST_REPORT.md` and `test-summary.json` (IPW).
6. A root `.gitignore` aimed at Playwright artefacts, `node_modules`, `.env`, and `auth.json`.

### Out of scope / not established

- The applications under test. This repository does not contain SAWIS, ShopFlow, or IPW source.
- A passing CI job. No pipeline file is committed. Changelogs describe the suites as CI-ready. That is documentation, not a pipeline.
- SonarQube. Named by the onboarding scan, absent from git.
- A scheduler, queue, or background worker.
- Suites for `label.sawis.co.za`, the Amplify hostname, and `sawisonline.co.za` beyond a template (and, for `sawisonline.co.za`, a tracked `.env`).

## System architecture

```text
Tester workstation (Node.js, Playwright browsers)
   |
   |-- bi.sawisonline.co.za/          Playwright -> https://bi.sawisonline.co.za
   |-- staging.ipw.co.za/             Playwright -> http://staging.ipw.co.za
   |       optional: MySQL (mysql2), SMTP email (nodemailer), Puppeteer PDF
   |-- qa.shopflow.../                Playwright -> SHOPFLOW_URL or https://shopflow.php8
   |       optional: Gmail IMAP for a 2FA code (imap)
   |
   '-- three hostname folders with a template and no specs
```

Each suite is invoked with `npm test` from its own directory. Nothing at the repository root starts them.

## Major components

| Component | Role |
|---|---|
| SAWIS BI specs | UI checks against the public BI dashboard. Login tests stop at the modal (reCAPTCHA, links, focus). They do not automate a successful login. |
| ShopFlow phase projects | `playwright.config.ts` defines projects `01-authentication` through `06-seller-portal`, each depending on the previous. `workers: 1` and `fullyParallel: false`. |
| ShopFlow authenticator | Fills email/password, treats `/2fa-validation` as the second step, and can read a Gmail message whose subject is `2FA Validation`. |
| `auth.json` | Playwright `storageState` required by ShopFlow phases 2–6. Gitignored. Not in the tree. Produced when authentication helpers save session state. |
| IPW dual config | `playwright.config.ts` and `playwright.config.js` both exist. Playwright's default lookup uses the `.ts` file first. `package.json` scripts do not pass `--config`. |
| IPW reporters | HTML/JSON/JUnit from Playwright, plus `scripts/generate-html-report.js`, `generate-pdf-report.js` (Puppeteer), and `send-email-report.js`. |
| Committed BI artefacts | `bi.sawisonline.co.za/playwright-report/` (501 files) and `test-results/` (1060 files), mostly `.webm` and `.png`. |

## Milestones (from git, not from a plan)

1. 2025-08-19 — repository created with `.gitignore`.
2. 2025-11-18 — SAWIS BI and IPW staging suites and three template folders committed together. BI HTML report and failure media were included.
3. 2025-11-19 — ShopFlow suite added (six phases, 2FA helper, patterns doc).
4. 2025-11-24 — ShopFlow login and logout specs and `authentication.ts` adjusted. No commits after this date as of inspection.

Changelog dates inside the suites (`2024-07-24` for BI, `2024-12-19` for IPW) are earlier than these git dates. Treat the changelog dates as document text, not as the git history.

## Implementation plan

There is no written roadmap in the repository. The only forward-looking text is `staging.ipw.co.za/CHANGELOG.md` under `[Unreleased]`, which lists page-specific tests, performance testing, accessibility automation, API tests, database tests, and monitoring integration as planned. Several of those areas already have spec files in the same directory (performance, accessibility, security, database scripts). The changelog and the tree disagree. See the PRD.

## Known dependencies

| Suite | Runtime libraries (from `package.json`) |
|---|---|
| SAWIS BI | `@playwright/test` ^1.40.0, `@types/node` ^20, `dotenv` ^16.3.0. Docs ask for Node.js 16 or higher. No `engines` field. |
| ShopFlow | `@playwright/test` ^1.56.0, `@types/node` ^24.7.0, `dotenv` ^17.2.3, `imap` ^0.8.17 |
| IPW staging | `@playwright/test` ^1.40.0, `dotenv` ^16.3.1, `mysql2` ^3.6.5, `nodemailer` ^7.0.6, `puppeteer` ^24.19.0 |

External systems the suites call:

- The three websites above.
- Gmail IMAP (`imap.gmail.com:993`) when `GMAIL_APP_PASSWORD` is set (ShopFlow).
- MySQL when IPW DB scripts are run. `playwright.config.js` defaults the database name to `playwright_tests`. The tracked `sawisonline.co.za/.env` names a different database (`timsheets2`) and is not wired to a `package.json`.
- SMTP host `mail.appnotify.co.za` port 587, mailbox `noreply@appnotify.co.za`, recipient `jaco@overdrive.co.za`, from `scripts/send-email-report.js`. The password is in that file and is omitted here.

Browsers are installed separately (`npm run install:browsers` or `npx playwright install`). They are not in git.

## Current project status

Active development is not visible after 2025-11-24. `main` is the only branch.

| Suite | Status at `41f992c` |
|---|---|
| SAWIS BI | Specs and a historical HTML report are committed. Whether that report's run passed was not re-executed for this document. |
| ShopFlow | Largest suite. Last change is the login fixup. Phases 2–6 declare `storageState: 'auth.json'`, which is not in git, so a clean checkout cannot start those projects until a session file exists. |
| IPW staging | README and `test-summary.json` (timestamp `2024-12-04`) say site-accessibility passed and authentication failed, and that other suites were blocked. That summary counts 93 tests. The current specs contain 68 `test()` calls. The summary does not match the current tree. |
| Template folders | No specs. |

## Human confirmation

- Whether `sonar-project.properties` and `sonarqube_scan.bat` should exist.
- Which ShopFlow host is canonical: directory name `qa.shopflow.io.dedi1534.jnb2.host-h.net` or default URL `https://shopflow.php8`.
- Which IPW login identity is the approved test account. Two different identities are hardcoded. Passwords are omitted here.
- Whether committed BI videos and screenshots should stay in git.
- Whether credentials committed in source should be rotated and removed from history. Locations are listed in `technical-documentation.md`.
- What the Amplify app, `label.sawis.co.za`, and `sawisonline.co.za` folders are for.