@hmcts/media-viewer 4.2.26-nodejs-healthcheck-update → 4.2.26

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:
 
 ```
@@ -122,7 +131,13 @@ Current Playwright lanes:
 
 | Lane | Config/project | Command | Scope |
 | --- | --- | --- | --- |
-| Standalone smoke | `playwright.config.ts`, project `smoke` | `yarn test:playwright:smoke` or `yarn test:smoke` | Opens the standalone Media Viewer demo, loads `assets/example.pdf`, and verifies the PDF viewer, page-number control and first rendered page. |
+| 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:
 
@@ -148,27 +163,41 @@ Override the smoke document and case id with `MV_SMOKE_PDF_DOCUMENT_URL` and
 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.
 
-Default Playwright evidence is written under `functional-output/tests`:
+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` |
 
-| Lane | Odhín | HTML | JUnit | Trace, screenshot and video output |
-| --- | --- | --- | --- | --- |
-| Smoke | `functional-output/tests/playwright-smoke/odhin-report/xui-playwright-smoke.html` | `functional-output/tests/playwright-smoke/html-report/index.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`.
 
-Those are the default local and nightly paths. CNP keeps preview and AAT
-evidence separate under `functional-output/tests/playwright-smoke/preview` and
-`functional-output/tests/playwright-smoke/aat` so results cannot be reused
-across environments.
+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.
-- HTML, JUnit and Odhín reporters can run together.
-- Traces, screenshots and videos are kept on failure for diagnostics.
+- 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
@@ -177,14 +206,19 @@ tests and Chromium into the workspace-local `PLAYWRIGHT_BROWSERS_PATH`, and sets
 
 Useful overrides:
 - `PLAYWRIGHT_BASE_URL` or `TEST_URL`: target application URL, default `http://localhost:3000/`
-- `PLAYWRIGHT_REPORTERS`: comma-separated reporter list, for example `list,html,junit,odhin`
+- `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_HTML_REPORT`: HTML report folder
 - `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
@@ -194,6 +228,7 @@ 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:
@@ -216,13 +251,14 @@ Migration boundaries:
 - 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, HTML and JUnit without bespoke stage logic.
+  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 workers.
+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: