Playwright Compatibility
Praman declares @playwright/test as a peer dependency with the range >=1.57.0 <2.0.0.
This page documents which versions are actively tested and recommended.
Playwright Version Matrix
| Playwright Version | Status | CI-Tested | Notes |
|---|---|---|---|
| 1.57.x | Supported | Yes | Minimum supported version |
| 1.58.x | Supported | No | Compatible, between the tested floor and top |
| 1.59.x | Supported | No | Screencast, CLI agents, ariaSnapshotDepth |
| 1.60.x | Supported | No | ARIA snapshots, highlight styles, test.abort |
| 1.61.x | Supported | No | Web Storage API, soft poll, video retain modes |
| 1.62.x | Supported | No | locator.waitForFunction, WebP, AbortSignal |
| 1.63.x | Recommended | Yes | Test locks, subtree frameLocator, step params |
| 2.x | Not supported | No | Breaking API changes expected |
Three jobs bound this range on every CI run:
| Job | What it pins | What it proves |
|---|---|---|
Playwright Floor (1.57.0) | the declared minimum | the unit suite passes at the floor |
Playwright Ceiling (latest) | @playwright/test@latest | the newest catalogued flags are active, and that Playwright has not published a minor Praman hasn't catalogued |
UI5 Bridge Smoke (PW 1.57.0 / 1.63.0) | both ends of the range | a real Chromium drives the UI5 bridge against live UI5 1.146.0 apps |
The ceiling job fails on an uncatalogued Playwright minor, so the feature table below cannot quietly fall behind the code.
The bridge smoke job is the only CI job that launches a browser. It targets public UI5 demo apps on the SAP CDN, which bundle their own mock OData server, so it needs no SAP system and no secrets — and each matrix leg downloads the Chromium revision its own Playwright version pins, so the bridge is exercised against the browser each supported version actually ships with.
Versions between the floor and the ceiling are supported via feature detection
but are not individually exercised. The SAP-system integration matrices in
canary.yml and release.yml list more versions, but they are gated on a
SAP_CLOUD_BASE_URL secret and skip when it is absent — treat them as
opt-in coverage for a configured fork, not as a guarantee this project makes.
TypeScript Version Matrix
| TypeScript Version | Status | CI-Tested | Notes |
|---|---|---|---|
| 5.5 – 5.9 | Supported | No | Compatible, not actively tested |
| 6.x | Supported | Yes | Published types compiled with TS 6.0.3 |
| 7.x | Recommended | Yes | Full inference, strict mode validated |
Tech Stack
| Component | Version |
|---|---|
| Playwright | 1.63.0 (peer: >=1.57.0) |
| TypeScript | 6.0.3 (supports 7.x) |
| Node.js | >=22 |
| ESLint | 10.12.0 (11 plugins) |
| Zod | 4.6.5 |
| Pino | 10.4.0 |
| Build | tsup 8.5.1 (ESM + CJS) |
| Test Runner | Vitest 5.0.3 |
| AI SDKs | Anthropic >=0.78, OpenAI >=6.22 |
| OpenTelemetry | SDK >=0.212 (optional) |
Minimum Version Enforcement
At startup, Praman calls assertMinVersion('1.57.0') from the internal
compatibility layer. If an older version is detected, a clear error is thrown
before any tests execute.
Feature Detection
Praman uses runtime feature detection (not version checks) to enable capabilities introduced in newer Playwright releases:
| Feature | Required Version | Detection Key |
|---|---|---|
| Clock API | 1.45+ | hasClockAPI |
| ARIA snapshots | 1.49+ | hasAriaSnapshot |
| Screencast API | 1.59+ | hasScreencastAPI |
| ARIA snapshot depth | 1.59+ | hasAriaSnapshotDepth |
| Set storage state | 1.59+ | hasSetStorageState |
| Locator normalize | 1.59+ | hasLocatorNormalize |
| URL pattern matcher | 1.59+ | hasURLPatternMatcher |
| Test abort | 1.60+ | hasTestAbort |
getByRole({ description }) | 1.60+ | hasGetByRoleDescription |
| Page ARIA snapshot | 1.60+ | hasPageAriaSnapshot |
| ARIA snapshot boxes | 1.60+ | hasAriaSnapshotBoxes |
| Tracing HAR | 1.60+ | hasTracingHAR |
| Locator drop | 1.60+ | hasLocatorDrop |
| Locator highlight style | 1.60+ | hasLocatorHighlightStyle |
| Browser context event | 1.60+ | hasBrowserContextEvent |
| WebAuthn credentials | 1.61+ | hasWebAuthnCredentials |
| Web Storage API | 1.61+ | hasWebStorageAPI |
| Soft poll | 1.61+ | hasSoftPoll |
| Screencast timestamp | 1.61+ | hasScreencastTimestamp |
| Video retain modes | 1.61+ | hasVideoRetainModes |
locator.waitForFunction() | 1.62+ | hasLocatorWaitForFunction |
| WebP screenshots | 1.62+ | hasWebPScreenshots |
retryStrategy: 'isolated' | 1.62+ | hasRetryStrategyIsolated |
AbortSignal support | 1.62+ | hasAbortSignal |
apiResponse.timing() | 1.62+ | hasApiResponseTiming |
scroll: 'none' on actions | 1.62+ | hasScrollOption |
| Test locks | 1.63+ | hasTestLocks |
Subtree frameLocator() | 1.63+ | hasSubtreeFrameLocator |
locator.visible() | 1.63+ | hasVisibleLocator |
Step params / subtitle | 1.63+ | hasStepParams |
ariaSnapshotJSON() | 1.63+ | hasAriaSnapshotJSON |
dialogclosed event | 1.63+ | hasDialogClosedEvent |
| OPFS in storage state | 1.63+ | hasOpfsStorageState |
httpCredentials array | 1.63+ | hasHttpCredentialsArray |
Test locks are the one flag with a user-facing guard: requireTestLocks()
throws below 1.63 rather than letting a silently-ignored lock run your tests
in parallel. See Parallel Execution.
Praman's behaviour when a feature is unavailable depends on whether the floor
has an equivalent — the policy is stated once in
src/core/compat/playwright-compat.ts and applies to every flag above:
- An equivalent exists → degrade transparently and log at
debugwhich path was taken.locator.waitForFunctionis the reference case: a page-scopedpage.waitForFunctionexpresses the same predicate. - No equivalent on the floor → throw
ERR_COMPAT_FEATURE_UNAVAILABLE, naming the required version. The Web Storage API is the reference case: there is no olderpage.localStorage, so degrading would silently give wrong results instead of an actionable error.
A special case worth knowing: hasConsoleMessageFilter guards an option,
not a method. page.consoleMessages() exists at the 1.57 floor but takes no
arguments, and JavaScript ignores surplus arguments — so passing { filter }
on an older runtime returns every message while the caller believes it was
filtered. Always guard the option, not the call.
How to Upgrade Playwright
npm install --save-dev @playwright/test@latest
npx playwright install
After upgrading, run your test suite to verify compatibility:
npx playwright test --reporter=list
Reporting Issues
If you encounter a compatibility issue with a specific Playwright version, please open a GitHub issue with:
- The exact Playwright version (
npx playwright --version) - The Praman version (
npm ls playwright-praman) - The error message or unexpected behavior