@hmcts/media-viewer 4.2.23 → 4.2.25-tar-upgrade

package/README.md

@@ -81,6 +81,15 @@ This command:
 - starts the local API on `PORT` or `1337`
 - starts Angular with `proxy.config.js`
 
+When Angular is already running and only the local API needs restarting, use:
+
+```
+yarn start:api:aat
+```
+
+Do not use `yarn start:api` directly for an AAT-backed run. It deliberately has no
+environment bootstrap and will otherwise target the non-AAT local proxy defaults.
+
 Open:
 
 ```
@@ -112,8 +121,144 @@ This opens `http://localhost:3000/#/media-viewer`, loads
 and first page. If `MV_SMOKE_PDF_DOCUMENT_ID` is blank, the smoke uses the demo app's
 default AAT PDF document id.
 
-### 5. Create isolated AAT test documents
-For mutation-heavy functional tests, do not share one document across parallel workers.
+### 5. Run Playwright tests
+Media Viewer is starting its Playwright migration with the same runner and
+reporting shape used in MC and MO, scaled to the current smoke coverage. The
+legacy Protractor and CodeceptJS functional packs still exist; new browser
+coverage should be added under `playwright_tests/`.
+
+Current Playwright lanes:
+
+| Lane | Config/project | Command | Scope |
+| --- | --- | --- | --- |
+| Standalone smoke | `playwright.config.ts`, project `smoke` | `yarn test:playwright:smoke` or `yarn test:smoke` | Loads standalone PDF and image fixtures and verifies rendered-document readiness, PDF zoom and navigation, image rotation and deterministic PDF search. |
+| Viewer support | `playwright.config.ts`, project `support` | `yarn test:playwright:support` | Proves the reusable PDF, image and unsupported-media fixtures, component objects and response diagnostics. |
+
+The Playwright config runs tests fully in parallel with seven workers. Each test
+gets its own browser context and page-scoped route mocks. Tests must not depend
+on execution order or share mutable documents; mutation-heavy AAT journeys must
+provision a document per test or reset it before reuse.
+
+Install Chromium once before local runs when the browser cache is empty:
+
+```
+yarn test:setup:playwright-install-chromium
+```
+
+Run the smoke project against a running standalone demo app. Start the app in
+one terminal:
+
+```
+yarn start
+```
+
+Then run the smoke in another terminal:
+
+```
+yarn test:playwright:smoke
+```
+
+Override the smoke document and case id with `MV_SMOKE_PDF_DOCUMENT_URL` and
+`MV_SMOKE_CASE_ID`. `yarn test:smoke` now runs the Playwright smoke so Jenkins
+CNP uses the same smoke entrypoint style as MC/MO. The previous CodeceptJS smoke
+remains available as `yarn test:smoke:legacy` while migration work continues.
+
+The lane wrapper commands write Playwright evidence under `functional-output/tests`:
+
+| Lane | Odhín | JUnit | Trace, screenshot and video output |
+| --- | --- | --- | --- |
+| Viewer support | `functional-output/tests/playwright-support/odhin-report/xui-playwright-support.html` | `functional-output/tests/playwright-support/playwright-support-junit.xml` | `functional-output/tests/playwright-support/test-results` |
+| Smoke | `functional-output/tests/playwright-smoke/odhin-report/xui-playwright-smoke.html` | `functional-output/tests/playwright-smoke/playwright-smoke-junit.xml` | `functional-output/tests/playwright-smoke/test-results` |
+
+Those are the default lane-specific paths. CNP keeps preview and AAT viewer
+support evidence separate under `functional-output/tests/playwright-support/preview`
+and `functional-output/tests/playwright-support/aat`. Smoke evidence remains under
+`functional-output/tests/playwright-smoke/preview` and
+`functional-output/tests/playwright-smoke/aat`.
+
+The raw aggregate `npx playwright test --config=playwright.config.ts` command
+uses `functional-output/tests/playwright` unless the report paths are overridden.
+
+Reporting behavior follows the MC/MO pattern:
+
+- Odhín is produced through the patched `odhin-reports-playwright` reporter.
+- Each successfully generated Odhín report uses a stable suite title and includes the application
+  version, branch, target environment, CI or local context, worker count, CPU
+  count and total RAM in its run information.
+- CI logs Odhín finalisation progress using the same progress reporter as MC/MO.
+- Odhín is the only standard human-readable report. JUnit is retained for
+  Jenkins ingestion. Screenshots and videos are kept on failure; traces are
+  captured on the first retry.
+  The standard Playwright HTML reporter is not supported.
+- `PLAYWRIGHT_SKIP_INSTALL=true` skips browser installation when Jenkins or a
+  local setup step has already installed Chromium.
+- Jenkins CNP and nightly pipelines publish the Odhín HTML reports, publish
+  JUnit XML, and archive the full Playwright output folders.
+- The classic Jenkins build page exposes viewer-support reports as `PREVIEW
+  Playwright Viewer Support Test`, `AAT Playwright Viewer Support Test`, or
+  `Nightly Playwright Viewer Support Test`. Blue Ocean does not reliably show
+  HTML Publisher links.
+
+The Jenkins `YarnBuilder` performs its immutable dependency install before the
+first setup task. The pipeline then installs Puppeteer Chrome once for legacy
+tests and Chromium into the workspace-local `PLAYWRIGHT_BROWSERS_PATH`, and sets
+`PLAYWRIGHT_SKIP_INSTALL=true` so Playwright lanes do not reinstall it.
+
+Useful overrides:
+- `PLAYWRIGHT_BASE_URL` or `TEST_URL`: target application URL, default `http://localhost:3000/`
+- `PLAYWRIGHT_REPORTERS`: comma-separated reporter list, for example `list,junit,odhin`
+- `PLAYWRIGHT_DEFAULT_REPORTER`: terminal reporter when `PLAYWRIGHT_REPORTERS` is not set, default `list` locally and `dot` in CI
+- `PLAYWRIGHT_JUNIT_OUTPUT`: JUnit XML path
+- `PLAYWRIGHT_REPORT_FOLDER`: Odhín report folder
+- `PLAYWRIGHT_REPORT_INDEX_FILENAME`: Odhín report file name
+- `PLAYWRIGHT_REPORT_TITLE`: Odhín report title
+- `PLAYWRIGHT_REPORT_PROJECT`: Odhín project label
+- `PLAYWRIGHT_REPORT_RELEASE`: Odhín release label, default `<version> | branch=<branch>`
+- `PLAYWRIGHT_REPORT_BRANCH`: branch override used by the default release label
+- `PLAYWRIGHT_REPORT_TEST_ENVIRONMENT` or `PW_ODHIN_ENV`: complete Odhín test-environment label override
+- `TEST_TYPE`: target-environment label, otherwise inferred from the test URL
+- `PLAYWRIGHT_TEST_OUTPUT_DIR`: traces, screenshots and videos folder
+- `FUNCTIONAL_TESTS_WORKERS`: worker-count override from `1` to `64`, default `7`
+- `PLAYWRIGHT_SKIP_INSTALL=true`: skip the automatic Chromium install in Playwright scripts
+
+Use this local proof set before pushing Playwright documentation or pipeline
+changes:
+
+```
+yarn install --immutable
+yarn test:setup:playwright-install-chromium
+PLAYWRIGHT_SKIP_INSTALL=true yarn test:playwright:smoke:list
+PLAYWRIGHT_SKIP_INSTALL=true npx playwright test --config=playwright.config.ts
+```
+
+For a smoke behavior proof, start the app in one terminal:
+
+```
+yarn start
+```
+
+Then run the Playwright smoke in another terminal:
+
+```
+PLAYWRIGHT_SKIP_INSTALL=true yarn test:smoke
+```
+
+Migration boundaries:
+
+- Put new native Playwright specs under `playwright_tests/`.
+- Keep screen interactions and reusable locators in page objects under
+  `playwright_tests/pages/`; keep assertions visible in specs.
+- Keep legacy Protractor and CodeceptJS coverage until replacement coverage and
+  Jenkins evidence are agreed.
+- Add stable report output paths for every new Playwright lane so Jenkins can
+  publish Odhín and JUnit and archive failure diagnostics without bespoke stage
+  logic.
+- Prefer Playwright browser-level assertions for viewer readiness; do not treat
+  an error page, blank page, wrong route or service-down page as a valid ready
+  signal.
+
+### 6. Create isolated AAT test documents
+For mutation-heavy functional tests, do not share one document across parallel tests.
 Create fresh AAT DM Store documents through the local API proxy while `yarn start:aat`
 is running:
 
@@ -130,7 +275,7 @@ This writes:
 The upload path mirrors em-showcase: multipart `files`, `classification=PUBLIC`,
 and civil/probate metadata are posted to `/documents`.
 
-### 6. Run isolated local functional tests
+### 7. Run isolated local functional tests
 With `yarn start:aat` still running, execute the functional groups with separate
 documents and separate reports: