Skip to main content
Version: 1.x

Release Notes

Version 1.3.6​

Released: October 2026 · npm · GitHub

🎭 Playwright 1.62 + 1.63 Support — 14 New Feature Flags​

Praman now detects and gates Playwright 1.62 and 1.63 APIs via 14 new feature flags, auto-detected at runtime:

Playwright 1.62 — 6 flags:

Feature flagAPI gatedWhat it enables
hasLocatorWaitForFunctionlocator.waitFor(predicate)Per-control wait predicates beyond global waitForUI5Stable
hasWebPScreenshotsWebP screenshot formatSmaller screenshot files with lossy compression
hasRetryStrategyIsolatedretries: { mode: 'isolated' }Isolated retry execution in clean browser contexts
hasAbortSignalAbortSignal on API methodsCancellable Playwright operations with abort controller
hasApiResponseTimingResource Timing on API responsesNative timing replaces Date.now() deltas in OData tracing
hasScrollOptionlocator.click({ scroll: 'none' })Opt out of auto-scroll before click actions

Playwright 1.63 — 8 flags:

Feature flagAPI gatedWhat it enables
hasTestLockstest({ lock: 'name' })Named test locks for parallel isolation of shared SAP state
hasSubtreeFrameLocatorlocator.frameLocator()Scoped frame locators for nested iframe content
hasVisibleLocatorlocator.visible()Boolean visibility check without assertion
hasStepParamstest.step(title, fn, { params })Structured parameters on test steps for reporting
hasAriaSnapshotJSONariaSnapshot() JSON outputMachine-readable accessibility snapshots for AI grounding
hasDialogClosedEventpage.on('dialogclosed')Detect-only observation of native browser dialogs
hasOpfsStorageStatestorageState({ opfs: true })Origin-private filesystem storage state persistence
hasHttpCredentialsArrayhttpCredentials array formMultiple HTTP credential sets per browser context

All flags return false on older Playwright versions — zero behavior change for existing users.

Ceiling drift detector: CI now fails when an uncatalogued Playwright release is detected, ensuring new APIs are flagged before they ship uncovered.

Peer dependency unchanged: "@playwright/test": ">=1.57.0 <2.0.0" — Playwright 1.62 and 1.63 already fall within range.

🗨️ New: Browser Dialog Fixture​

Native alert/confirm/prompt/beforeunload dialogs were invisible to Praman — these are the browser's own dialogs, not sap.m.Dialog. SAP's "unsaved changes" warning on navigation is a native beforeunload dialog that Playwright auto-dismissed silently.

Two methods with different risk profiles:

MethodEventRiskGate
observe()dialogclosedNone — purely observationalPlaywright 1.63+, degrades to silence
register()dialogChanges behavior by existingAll Playwright versions
import { test, expect } from 'playwright-praman';

test('detect unsaved changes dialog', async ({ ui5Navigation, nativeDialogs }) => {
  // Detect-only — observe without answering (1.63+)
  nativeDialogs.observe();

  // Navigate away from a dirty form
  await ui5Navigation.navigateToHash('Shell-home');

  // Assert the beforeunload dialog was observed
  expect(nativeDialogs.records).toContainEqual(expect.objectContaining({ type: 'beforeunload' }));
});

🛡️ New: SAP Overlay Handler​

SAP applications show overlays — BusyIndicator, MessageToast, confirmation dialogs — that interrupt test actions. The new overlays fixture detects and handles these automatically using Playwright's addLocatorHandler (available since Playwright 1.42, below the 1.57 floor — no version gate needed).

Detect, don't dismiss: Handlers report overlays by default. Dismissal is opt-in per rule and logged at warn, because silently answering a dialog turns a real failure into a passing test. BusyIndicator defers to waitForUI5Stable rather than racing it.

🔍 New: UI5 Diagnostics on Failure​

Failing tests now automatically capture and attach:

  • Console output — browser console messages at the time of failure
  • Page errors — unhandled JavaScript exceptions
  • Network requests — failed or pending network calls

All three are argument-free and safe across Playwright versions. The hasConsoleMessageFilter flag (1.59+) ensures the filter option isn't passed to older runtimes where it would silently return everything.

Opt-in clock fixture: A fake clock is available but never auto-installed, because SAP session and token validity are time-sensitive. Controlling time before install throws rather than silently doing nothing.

🤖 AI Generator Integrity​

Two-phase overhaul of the AI test generator to ensure deterministic, auditable output:

Phase A (#261) — Single ownership and integrity primitives:

  • Each generated artifact now has exactly one owner script — no more "last writer wins" races between generate:skill-md and generate:capabilities
  • Content-neutral: no generated artifact changes in this PR

Phase B (#264) — Deterministic generation and drift gate:

  • Removed new Date() stamps that made every regeneration produce a diff
  • Output is now a pure function of its input — regenerating twice produces identical bytes
  • CI drift gate: npm run validate:generated fails if any generated artifact is stale

🔒 Test Locks for Shared SAP State​

Playwright 1.63 adds lock to the test options: tests holding the same lock name never run concurrently. Praman adds a runtime guard and conventional lock names for SAP-specific shared state (e.g., a single Sales Order being edited by parallel tests).

The guard is fail-closed: on Playwright < 1.63, attempting to use lock throws a PramanError with upgrade guidance rather than silently ignoring the option.

⏱️ Per-Control Waits​

New waitForControlState() method for per-control predicates — additive to waitForUI5Stable(), which is global. Useful when a specific control's state matters independently of the UI5 framework's busy state.

The compatibility policy is documented: throw when the Playwright floor has no equivalent, degrade when it does.

🏭 S/4HANA Gap Analysis — 4 New Intent Domains​

Based on real-world usage analysis of SAP S/4HANA test suites, Praman adds four new intent domains:

DomainSAP ModuleFunctionsNamespace
Quality ManagementQMcreateInspectionLot, recordResults, createQualityNotificationintent.quality
Warehouse ManagementWMcreateGoodsMovement, createTransferOrderintent.warehouse
Asset ManagementAMacquireAsset, retireAsset, transferAssetintent.assetManagement
Human ResourcesHRcreateEmployee, recordTime, requestAbsenceintent.hr

All follow the existing intent pattern: vocabulary-driven field resolution, IntentResult envelope, IntentOptions with skip-navigation and timeout.

import { quality, warehouse, assetManagement, hr } from 'playwright-praman/intents';

await quality.createInspectionLot(ui5, ui5Nav, vocab, {
  material: 'RAW-0001',
  plant: '1000',
});

await hr.requestAbsence(ui5, ui5Nav, vocab, {
  absenceType: 'Vacation',
  startDate: '2026-11-01',
  endDate: '2026-11-05',
});

🔧 Intent Configurability — IntentOverrides​

All 9 intent domains now accept overrides in IntentOptions for environment-specific customization:

await procurement.createPurchaseOrder(ui5, ui5Nav, vocab, poData, {
  overrides: {
    appId: 'ZMM_PO-create', // Custom FLP hash
    saveButtonText: 'Sichern', // Localized button label
    fields: { Vendor: 'Lieferant' }, // Localized field labels
  },
});

This eliminates hardcoded FLP semantic objects, button labels, and field names — making tests portable across SAP system landscapes with different configurations or languages.

📊 Reporter Enhancements​

Compliance reporter annotations: The compliance reporter now reads Playwright test annotations for SAP-specific metadata:

test(
  'create purchase order',
  {
    annotation: [
      { type: 'process', description: 'Procure-to-Pay' },
      { type: 'tcode', description: 'ME21N' },
      { type: 'criticality', description: 'high' },
    ],
  },
  async ({ ui5 }) => {
    /* ... */
  },
);

The ANNOTATION_TYPES constant is exported from playwright-praman/reporters.

Allure SAP categories: Pre-defined failure categories for Allure reporting — ALLURE_SAP_CATEGORIES maps Praman error codes to Allure-compatible category objects for UI5 control errors, navigation errors, OData errors, auth errors, and test data failures.

📸 New: Visual Regression Fixture​

Screenshot comparison with automatic FLP chrome masking:

test('purchase order form', async ({ visualRegression }) => {
  await visualRegression.compareScreenshot('po-form', {
    mask: visualRegression.maskFLPChrome(),
  });
});

The maskFLPChrome() method returns locators for #shell-header, .sapUshellShellHead, and #meAreaHeaderButton — the SAP FLP elements that change between sessions and break pixel comparisons.

Available as standalone visualRegressionTest or merged into the default test object.

🗄️ New: Standalone OData Fixture​

odata is now available as a top-level fixture (alongside the existing ui5.odata sub-namespace):

test('verify entity count', async ({ odata }) => {
  const count = await odata.getEntityCount('/sap/opu/odata/sap/ZMM_PO_SRV/PurchaseOrders');
  expect(count).toBeGreaterThan(0);
});

Available as standalone odataTest or merged into the default test object.

📅 Date Template Placeholders​

The testData fixture now supports date placeholders in templates:

PlaceholderResolves to
{{today}}Current date (YYYY-MM-DD)
{{tomorrow}}Tomorrow's date
{{yesterday}}Yesterday's date
{{date+N}}N days from now
{{date-N}}N days ago
test('create PO with dynamic dates', async ({ testData }) => {
  const data = await testData.load('po-template', {
    deliveryDate: '{{date+14}}', // 2 weeks from now
    documentDate: '{{today}}',
  });
});

🌍 Multi-Environment defineConfig​

defineConfig() now accepts an optional second parameter for environment-specific overrides:

import { defineConfig } from 'playwright-praman';

export default defineConfig(
  { baseURL: 'https://dev.example.com', auth: { strategy: 'form' } },
  {
    ci: { baseURL: 'https://ci.example.com', headless: true },
    staging: { baseURL: 'https://staging.example.com' },
  },
);

Set PRAMAN_ENV or NODE_ENV to select the environment. PRAMAN_ENV takes precedence.

⚡ fill() Now Calls waitForUI5​

fill() now automatically calls waitForUI5() after setValue + fireChange, matching the documented behavior. This eliminates the need for manual waitForUI5() calls after fill operations.

Opt out via config for performance-sensitive scenarios:

defineConfig({ skipPostFillWait: true });

🧩 Scaffolder Templates​

npx praman init now generates additional project files:

  • global.teardown.ts — shared test teardown
  • tests/helpers/master-data.ts — reusable master data helpers
  • .github/workflows/playwright.yml — CI workflow template
  • Subdirectories: tests/helpers/, tests/otc/, tests/ptp/, tests/rtr/

🐛 Bug Fixes​

  • #246 (#256): agents/ (20 files) and seeds/ were not shipped in the npm package. Fixed with a files[] guard that fails the build if a declared entry matches nothing.
  • #296: Reporter step classification changed from title-prefix matching to structural classification — 80% misclassification rate (12/15 steps) reduced to 0%.
  • #300: Malformed OData response bodies no longer crash the trace reporter. Calls are now timed by the Resource Timing API instead of Date.now() deltas.
  • #226: npx praman init now actually scaffolds a project — the command was broken since the tsup chunk-splitting change.
  • #228: Agent-asset validation now runs in CI; Prettier no longer corrupts the asset manifest.
  • #268: Stale npm override ranges refreshed to match current security advisories.

⚡ CI & Testing Improvements​

  • First browser-launching CI job (#266): CI now runs a real Chromium instance, catching wiring bugs that mocked tests pass through.
  • TypeScript type verification (#223): Shipped .d.ts files verified against TypeScript 5.9, 6.0, and 7.0 on every push.
  • Vitest 4 → 5 (#292): Major test framework upgrade with per-file coverage enforcement restored.
  • CI action bumps (#291): codeql-action v4.38.2, deploy-pages v5.0.1.

📦 Dependency Updates​

CategoryChange
Playwright@playwright/test 1.61.1 → 1.63.0
Testingvitest + @vitest/coverage-v8 4.x → 5.x
Lintingeslint → 10.12.0, eslint-plugin-n → 18.4.1
DocsDocusaurus suite consolidated to latest, docusaurus-plugin-llms 0.6.1
Securityhttp-proxy-middleware override 2.0.10, stale advisory overrides refreshed
CI Actionscodeql-action v4.37.8 → v4.38.2, actions/checkout 7.0.0 → 7.0.1

14 dependency-related commits in total (13 upgrades + 1 security override refresh).

Upgrade: npm install [email protected] — no config changes needed.

Version 1.3.5​

Released: July 2026 · npm · GitHub

🔧 CI Fixes​

  • Aligned CodeQL action SHAs to resolve version mismatch (#191)
  • Resolved CI failures and removed stale release-as pin (#189)

No user-facing changes. Upgrade: npm install [email protected]

Version 1.3.4​

Released: July 2026 · npm · GitHub

🎭 Playwright 1.61 Support — 5 New Feature Flags​

Praman now detects and gates Playwright 1.61 APIs via 5 new feature flags, auto-detected at runtime:

Feature flagAPI gatedWhat it enables
hasWebAuthnCredentialsbrowserContext.credentialsWebAuthn credential management for passkey testing
hasWebStorageAPIpage.localStorage / sessionStorageTyped access to browser storage without evaluate()
hasSoftPollexpect.soft.poll()Soft assertion polling for non-blocking checks
hasScreencastTimestampNative onFrame timestampsMicrosecond-precise frame timing from the browser
hasVideoRetainModeson-all-retries, retain-on-*Granular video recording retention strategies

All flags return false on Playwright < 1.61 — zero behavior change for existing users.

Peer dependency unchanged: "@playwright/test": ">=1.57.0 <2.0.0" — Playwright 1.61 already falls within range.

💾 New: Web Storage Fixture​

A typed fixture for seeding and inspecting browser storage — no more page.evaluate() for localStorage/sessionStorage operations:

import { test } from 'playwright-praman';

test('seed localStorage before navigation', async ({ webStorage }) => {
  await webStorage.localStorage.seed({ theme: 'dark', lang: 'en' });
  await webStorage.localStorage.setItem('token', 'abc123');

  const all = await webStorage.sessionStorage.items();
  const count = await webStorage.localStorage.size();
  await webStorage.localStorage.clear();
});

API surface: setItem, getItem, removeItem, items, seed, clear, size — available on both webStorage.localStorage and webStorage.sessionStorage.

Feature-gated: Throws ERR_COMPAT_FEATURE_UNAVAILABLE with clear upgrade guidance on Playwright < 1.61. The error includes suggestions for both upgrading and using page.evaluate() as a fallback.

📹 Native Screencast Frame Timestamps​

The screencast fixture now uses native browser-provided frame timestamps (microsecond-aligned) on Playwright 1.61+, instead of synthetic Date.now() timestamps. This improves timing precision for frame-level analysis without any API changes — ScreencastFrame.timestamp remains number (milliseconds since recording start).

Falls back to synthetic timestamps on Playwright < 1.61.

🛡️ Security Fixes​

Resolved 5 vulnerabilities through direct upgrades and npm overrides:

PackageFromToSeverityFix type
vite8.0.68.1.3Highaudit fix
tar7.5.157.5.16Moderateaudit fix
esbuild0.27.70.28.1Highnpm override
undici7.24.77.28.0Highdocs workspace
linkify-it5.0.05.0.2Highdocs workspace

Remaining 8 vulnerabilities are all in @ui5/mcp-server's transitive @sigstore/core chain — no fix available until SAP publishes an update.

🔧 New Error Category: Compat​

Added ERR_COMPAT_FEATURE_UNAVAILABLE error code under a new Compat error category. Used when a fixture requires a Playwright version newer than what's installed. The error includes specific upgrade instructions and fallback suggestions.

Total: 78 error codes across 18 categories (up from 77/17).

⚡ CI Improvements​

  • Playwright ceiling test: new CI job installs @playwright/test@latest and explicitly verifies PW 1.61 feature flags are active
  • actions/checkout upgraded v5 → v7 across all workflows
  • github/codeql-action upgraded to 4.36.2
  • Floor + ceiling validation: CI now validates both minimum (1.57.0) and latest Playwright compatibility on every push

📦 Dependency Updates​

Dev dependencies (35 packages upgraded):

  • @playwright/test 1.60.0 → 1.61.1
  • @anthropic-ai/sdk 0.100.1 → 0.110.0
  • commander 14.0.3 → 15.0.0
  • @commitlint/cli 21.0.2 → 21.2.0
  • vitest + @vitest/coverage-v8 → 4.1.9
  • @opentelemetry/* suite updated
  • @ui5/mcp-server 0.2.12 → 0.2.14

Upgrade: npm install [email protected] — no config changes needed.

Version 1.3.3​

Released: June 2026 · npm · GitHub

🐛 UI5 1.136+ Compatibility Fix​

Praman now works correctly on SAP UI5 1.136+, which removed the global sap.ui.core.ElementRegistry accessor. All internal code paths have been migrated to sap.ui.require('sap/ui/core/ElementRegistry') — the modular API that works across all UI5 versions.

Three files were affected:

FileImpact
src/ai/bulk-discovery.tsAI control discovery failed silently on UI5 1.136+
src/bridge/browser-scripts/find-control-fn.tsControl lookup fallback path used deprecated accessor
tests/seeds/sap-seed.spec.tsSeed control counting fallback broke on 1.136+

Who is affected: Anyone running Praman against an SAP system on UI5 1.136 or later. Older UI5 versions are unaffected.

Upgrade: npm install [email protected] — no config changes needed.

🔒 Zero npm Audit Vulnerabilities​

Updated @ui5/mcp-server 0.2.11 → 0.2.12, resolving all 9 previously reported vulnerabilities (2 high, 7 moderate). npm audit now reports 0 vulnerabilities for the main package.

📹 Docs: Demo Videos​

The documentation site now includes three demo videos showing Praman in action — AI test generation, control discovery, and end-to-end SAP testing workflows.

Version 1.3.0​

Released: May 2026 · npm · GitHub

🎭 Playwright 1.60 Support​

Praman now ships with Playwright 1.60 as its peer dependency (up from 1.59). The compat layer adds 8 new feature flags gated behind version detection so you can adopt 1.60 APIs at your own pace:

Feature flagAPI gatedWhat it enables
hasTestAborttest.abort()Programmatic test abort from within a test body
hasGetByRoleDescriptiongetByRole({ description })Filter ARIA roles by aria-description attribute
hasPageAriaSnapshotpage.ariaSnapshot()Full-page accessibility tree capture for AI grounding
hasAriaSnapshotBoxesariaSnapshot({ boxes })Bounding-box coordinates in accessibility snapshots
hasTracingHARTracing HAR captureHAR network archive alongside trace recordings
hasLocatorDroplocator.drop()Native drag-and-drop target for file upload and DnD scenarios
hasLocatorHighlightStylelocator.highlight({ style })Custom highlight styling for visual debugging
hasBrowserContextEventbrowserContext.on('event')New browser context event subscriptions

All eight flags are auto-detected — no configuration required. Existing tests on Playwright 1.57–1.59 continue to work unchanged.

Browser engine updates: Chromium 136 → 148, Firefox 139 → 150, WebKit 18.4 → 26.4.

Removed APIs (zero impact): Playwright 1.60 removed Locator.ariaRef(), exposeBinding handle option, connect/connectOverCDP logger option, and videosPath/videoSize. None were used by Praman — no breaking changes.

🔷 TypeScript 7.x and 6.x Support​

Praman source and published types are now compiled with TypeScript 6.0.3. The CI matrix validates against both TS 6.x and TS 7.x on every push.

What this means for you:

  • If you compile your tests with TypeScript 7.x, Praman types work out of the box with full inference.
  • If you compile with TypeScript 6.x, nothing changes from v1.2.0 — full support continues.
  • If you compile with TypeScript ≥ 5.5, all Praman APIs remain compatible.
  • The strict: true tsconfig is enforced throughout — all generics, narrowing, and inference behave correctly under TS 7 semantics.

🧠 AI Grounding with ARIA Snapshots​

Praman's AI context builder now captures the full-page ARIA accessibility snapshot and includes it in the PageContext envelope sent to LLM agents. This gives AI test generators a structural map of the page — control roles, names, states, and hierarchy — alongside the existing UI5 control tree.

// Enable in config
export default defineConfig({
  use: {
    pramanConfig: {
      includeAriaSnapshot: true, // opt-in: page.ariaSnapshot() in AI context
    },
  },
});

The PageContext.ariaSnapshot field is populated automatically during bulk discovery when the flag is enabled. Requires Playwright 1.60+ (hasPageAriaSnapshot compat flag).

🔦 Screencast Control Highlighting​

New screencast.highlightControls() fixture that draws a visible overlay on UI5 controls as they are interacted with during screencast recording. Every ui5.press(), ui5.fill(), and proxy method call highlights the target control with a configurable border style.

test('demo with highlights', async ({ screencast, ui5 }) => {
  // Enable highlighting — controls flash on interaction
  screencast.highlightControls(true);

  // Custom highlight style
  screencast.highlightControls(true, {
    border: '3px solid red',
    backgroundColor: 'rgba(255, 0, 0, 0.1)',
  });

  await ui5.press({ id: 'myButton' }); // button highlighted during press
});

The highlight controller is page-keyed — each page in a multi-tab test gets its own highlight state. Highlighting is a no-op on Playwright versions below 1.60.

📊 OData Trace Reporter — onError Hook​

The OData trace reporter now implements the onError(error, workerInfo) Playwright reporter hook, capturing worker-level errors (crashes, timeouts, unhandled exceptions) alongside OData trace data. Previously, worker errors were silently dropped from OData trace reports.

⬆️ ESLint 10 Ecosystem​

The linting toolchain has been upgraded from ESLint 9.x to ESLint 10.x:

PackageFromTo
eslint9.39.210.4.0
@eslint/js9.39.310.0.1
eslint-plugin-n17.24.018.0.1
eslint-plugin-security3.0.14.0.0
eslint-plugin-promise7.2.17.3.0

The @microsoft/eslint-plugin-sdl plugin (peerDep on eslint ^9) works correctly at runtime with ESLint 10 — resolved via npm overrides until Microsoft publishes an update. Zero config changes needed for existing setups.

📦 Dependency Updates​

Runtime:

  • zod 4.3.6 → 4.4.3
  • dotenv 16.x → 17.4.2

LLM SDKs & Telemetry:

  • @anthropic-ai/sdk 0.82.0 → 0.98.0
  • openai SDK updated
  • OpenTelemetry suite updated

CI Actions:

  • actions/github-script 7.0.1 → 9.0.0
  • actions/setup-node 6.3.0 → 6.4.0
  • actions/upload-artifact 4.6.2 → 7.0.1
  • googleapis/release-please-action 4.4.0 → 5.0.0
  • github/codeql-action 4.35.1 → 4.35.3

Dev tooling:

  • ts-morph 24.0.0 → 28.0.0
  • cspell 9.7.0 → 10.0.0
  • commitlint 20 → 21, lint-staged 16 → 17
  • postcss 8.5.8 → 8.5.15, protobufjs 7.5.4 → 7.6.1

📋 Docs Verification Pipeline — 8 Checks​

The documentation accuracy pipeline now runs 8 automated checks on every PR:

  1. TypeScript snippet type-checking
  2. API reference accuracy
  3. Config default validation
  4. Import path verification
  5. AI-assisted review
  6. SAP UI5 API verification
  7. Code example execution
  8. Cross-reference link validation

Other Improvements​

  • Claude Code Plugin docs: New documentation for Claude Code and Cowork plugin integration.
  • Plugin install instructions: Fixed to match official Claude Code documentation format.
  • Capabilities registry: screencast.highlightControls and ARIA grounding capabilities registered in capabilities.yaml.
  • Security: protobufjs, postcss, @xmldom/xmldom bumped to resolve advisories.

Version 1.2.0​

Released: April 2026 · npm · GitHub

🎭 Playwright 1.59 Support​

Praman now ships with Playwright 1.59 as its peer dependency, validated against both the stable channel and the Playwright canary (next) build in CI.

Five new Playwright 1.59 APIs are gated behind feature flags in PramanConfig so you can opt in as soon as your SAP environment is ready:

Feature flagAPI gatedWhat it enables
playwrightFeatures.screencastpage.screencastProgrammatic video recording with start/stop control and action overlays
playwrightFeatures.ariaSnapshotDepthlocator.ariaSnapshot({ depth })Scoped accessibility tree capture for deep UI5 component trees
playwrightFeatures.setStorageStatebrowserContext.setStorageState()Clear and replace storage state in-place without creating a new context
playwrightFeatures.locatorNormalizelocator.normalize()Convert ad-hoc locators to best-practice test-id / aria-role equivalents
playwrightFeatures.urlPatternMatcherexpect(page).toHaveURL(pattern)URL Pattern API matching in URL assertions

All five flags default to false and have zero impact on existing tests.

// playwright.config.ts
import { defineConfig } from 'playwright-praman';

export default defineConfig({
  use: {
    pramanConfig: {
      playwrightFeatures: {
        screencast: true, // opt-in: page.screencast API
        ariaSnapshotDepth: true, // opt-in: depth option on ariaSnapshot
      },
    },
  },
});

CI now runs a three-channel integration matrix: Playwright stable, Playwright next (canary), and the bundled Chromium baseline — so Praman validates against upcoming Playwright changes before they ship.

🤖 Praman CLI Agents for Playwright​

Praman now supports Playwright CLI Agents — plan, generate, and heal SAP UI5 tests directly from the command line using Claude Code's playwright-cli skill. No MCP server required.

🔷 TypeScript 6.x Support​

Praman source and its published types are now compiled with TypeScript 6.0.2. The CI matrix validates against both TS 5.9 and TS 6.0 on every push.

What this means for you:

  • If you compile your test files with TypeScript ≥ 5.5, nothing changes.
  • If you use TypeScript 6.0, you get full type inference on all Praman APIs with no extra configuration.
  • The strict: true tsconfig is enforced throughout — all generics, narrowing, and inference behave correctly under TS 6 semantics.

See the TypeScript 6.0 Compatibility Report in the repository for the detailed analysis.

🔍 Unified ui5= Selector Engine​

The three separate selector parsers (CSS engine, XPath engine, legacy ui5-selector-engine) have been replaced by a single unified engine powered by fontoxpath (XPath 3.1) and css-selector-parser.

CSS-style selectors like sap.m.Button[text=Save] are now parsed to an AST, converted to XPath 3.1, and evaluated against an in-memory XML DOM built from the live UI5 control tree. This is the same proven approach used by playwright-ui5.

New pseudo-classes and combinators:

// :labeled() — find controls by associated sap.m.Label text
page.locator("ui5=sap.m.Input:labeled('Vendor')");

// :not() — exclude specific control types
page.locator('ui5=sap.m.Button:not([type=Back])');

// Descendant combinator (space)
page.locator('ui5=sap.m.Panel sap.m.Button[text=Save]');

// Child combinator (>)
page.locator('ui5=sap.m.Panel > sap.m.Button');

// Adjacent sibling (+)
page.locator('ui5=sap.m.Label + sap.m.Input');

// General sibling (~)
page.locator('ui5=sap.m.Label ~ sap.m.Input');

// Positional selectors
page.locator('ui5=sap.m.ColumnListItem:nth-child(2)');
page.locator('ui5=sap.m.ColumnListItem:first-child');
page.locator('ui5=sap.m.ColumnListItem:last-child');

Migration note: The enableXpathEngine configuration field has been removed. The unified engine handles all selector styles automatically — no config change required for existing tests.

For a full reference of the selector syntax, see the Locator Selector Syntax guide.

🔬 npx praman inspect — Interactive Control Inspector​

New CLI command that opens a live SAP application in a headed Chromium window and captures click events to print UI5 control metadata and ready-to-paste selectors in the terminal.

# Inspect any SAP Fiori Launchpad
npx praman inspect https://my-sap.example.com/sap/bc/ui5_ui5/...

# With stored auth (Playwright storageState JSON)
npx praman inspect https://my-sap.example.com --auth .auth/user.json

Click any element in the browser to see:

━━━ Clicked: sap.m.Button ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ID:      __button0--orderCreateBtn
  Type:    sap.m.Button
  Visible: true  Enabled: true

  Properties:
    text = "Create Order"
    type = "Emphasized"

  Bindings:
    text → {i18n>CREATE_ORDER}

━━━ Selectors (best → worst) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ① ui5=sap.m.Button[text=Create Order]
  ② ui5=sap.m.Button#orderCreateBtn
  ③ ui5=sap.m.Button[text=Create Order][type=Emphasized]

  Fixture:
    await ui5.control({ controlType: 'sap.m.Button', properties: { text: 'Create Order' } });

Selectors are ranked by stability — stable semantic properties before IDs, IDs before composite selectors. The inspector highlights the matched control with a blue border overlay so you can confirm the selection.

Read more in the Interactive Inspector guide.

⚙️ npx praman config — Display Resolved Configuration​

New CLI command that prints the fully resolved PramanConfig to the terminal — including values sourced from environment variables, playwright.config.ts, and defaults. Useful for debugging authentication and AI configuration on CI without adding debug logging to tests.

npx praman config

Output (example):

Praman Resolved Configuration
──────────────────────────────
baseUrl:         https://my-sap.example.com
auth.strategy:   storageState
auth.storageStatePath: .auth/user.json
ai.provider:     openai
ai.model:        gpt-4o
telemetry.openTelemetry: false
odataTracing:    false

🌿 Nested Environment Variable Support​

Configuration can now be injected at any nesting level via environment variables, removing the need to edit playwright.config.ts in CI pipelines:

Env variableConfig path
PRAMAN_AI_PROVIDERai.provider
PRAMAN_AI_MODELai.model
PRAMAN_AI_API_KEYai.apiKey
PRAMAN_TELEMETRY_ENABLEDtelemetry.openTelemetry
PRAMAN_ODATA_TRACING_ENABLEDodataTracing.enabled

See the Configuration guide for the full reference.

🔌 Extension System & Custom Matcher Registry​

Praman now exposes a plugin API for registering custom control matchers and fixture extensions at initialization time. This enables shared testing libraries to ship Praman extensions without modifying the core:

// my-extension.ts
import { defineExtension } from 'playwright-praman';

export const myExtension = defineExtension({
  name: 'my-company-controls',
  matchers: {
    toHaveApprovalStatus: async (controlProxy, expected) => {
      const status = await controlProxy.getProperty('approvalStatus');
      return {
        pass: status === expected,
        message: () => `Expected approval status ${expected}, got ${status}`,
      };
    },
  },
});
// playwright.config.ts
import { defineConfig } from 'playwright-praman';
import { myExtension } from './my-extension';

export default defineConfig({
  use: {
    pramanConfig: {
      extensions: [myExtension],
    },
  },
});

📋 Error Messages Now Include Docs URLs​

All typed PramanError subclasses now include a docsUrl field that links directly to the relevant documentation page. The URL appears in:

  • The terminal error message
  • The serialized JSON (for reporting and AI context)
  • The AI-envelope when Praman errors are surfaced to LLM agents
ControlError: Control not found: sap.m.Button[text=Save]
  code: ERR_CONTROL_NOT_FOUND
  docsUrl: https://praman.dev/docs/guides/errors#err-control-not-found
  suggestions:
    - Verify the control type and property value
    - Check if the page has fully loaded (waitForUI5)
    - Try using the inspect command: npx praman inspect <url>

🤖 Playwright CLI Agents — Now the Default​

Playwright CLI agents are now installed by default by both npx playwright-praman init and npx playwright-praman init-agents. Previously they required an explicit --cli opt-in flag.

What changed:

BeforeAfter
init installs MCP agents onlyinit installs MCP and CLI agents
--cli required to add CLI agents--no-cli to skip CLI agents
@playwright/cli not auto-installed@playwright/cli is an optional peer dependency — install manually if using CLI agents

init now scaffolds both MCP and CLI agent definitions by default:

PackageRoleInstall
@playwright/testPlaywright test runnerRequired — install before init
@playwright/mcpMCP server for MCP agentsInstall if using MCP agents
@playwright/cliPlaywright CLI for CLI agentsInstall if using CLI agents
playwright-pramanThe plugin itselfRequired — install before init

After installing @playwright/test, @playwright/mcp, or @playwright/cli, run npx playwright install chromium to download the bundled browser binary.

Command reference:

# Default — installs MCP + CLI agents, auto-installs all peer deps
npx playwright-praman init

# Opt out of CLI agents
npx playwright-praman init --no-cli

# init-agents also defaults to CLI-on
npx playwright-praman init-agents --loop=claude
npx playwright-praman init-agents --loop=copilot --no-cli

When CLI agents are being installed but @playwright/cli is absent from node_modules, the installer prints a warning with the exact install command.

⬆️ Node.js 22 Minimum​

The minimum supported Node.js version has been raised to 22 (from 20). Node.js 20 reached End-of-Life in April 2026.

If you are running CI on Node.js 20, update your workflow:

# .github/workflows/test.yml
- uses: actions/setup-node@v4
  with:
    node-version: '22'

🔒 Zero npm Vulnerabilities​

All npm audit vulnerabilities — in both the main package and the docs/ workspace — have been resolved to 0 remaining (0 critical, 0 high, 0 moderate). Security dependency bumps included:

  • picomatch 4.0.3 → 4.0.4
  • tar 7.5.10 → 7.5.11
  • path-to-regexp 0.1.12 → 0.1.13 (docs)
  • handlebars 4.7.8 → 4.7.9 (dev)
  • flatted 3.3.3 → 3.4.2 (dev)

📚 100% TSDoc Coverage​

TypeDoc now reports zero warnings across all public exports. Every exported function, class, interface, and type has:

  • @param annotations for all parameters
  • @returns describing the return value
  • @throws listing typed error classes
  • @example with a working code snippet

📡 OpenTelemetry Tracing & Metrics​

Praman now ships with full OpenTelemetry integration for distributed observability. Telemetry is disabled by default with zero overhead — enable it when you need end-to-end visibility into test execution.

FeatureWhat it does
TracingSpans for control discovery, bridge evaluation, test lifecycle
MetricsCounters (pass/fail/skip, discovery, injection) and histograms (duration)
OTel ReporterPlaywright reporter emitting nested spans per test step
Live correlationOTel traceId embedded in Playwright trace titles

Three exporters supported:

  • OTLP (default) — works with Jaeger, Grafana Tempo, any OTLP collector
  • Jaeger — via OTLP protocol (Jaeger accepts OTLP natively)
  • Azure Monitor — via connection string from Application Insights

Quick start:

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
docker compose -f docs/docker-compose.otel.yml up -d
PRAMAN_TELEMETRY_ENABLED=true PRAMAN_TELEMETRY_ENDPOINT=http://localhost:4318 npx playwright test
# Open Jaeger UI at http://localhost:16686

Dependencies are optional peer deps — not installed unless you opt in. When disabled, all telemetry calls are no-ops with negligible overhead. TelemetryError with 5 error codes provides actionable messages when OTel initialization fails (e.g., missing peer dependencies, unreachable endpoints).

See the Telemetry Setup Guide for detailed configuration, Azure Monitor setup, and troubleshooting.

Other Improvements​

  • Playwright Canary CI: Integration tests now run against @playwright/test@next in a separate matrix job, catching regressions before Playwright stable releases.
  • ADR-030 added: Architecture Decision Record for OPA5 migration strategy with code samples for hybrid OPA5 + Praman test suites.
  • 100% documentation accuracy: Eliminated fictional APIs and mismatched examples across 42 documentation files in the accuracy audit.
  • Locator Selector Syntax guide: New comprehensive guide for the ui5= custom engine covering all selector forms, pseudo-classes, and combinators.
  • Docs verification pipeline: 6 automated checks (typecheck snippets, API references, config defaults, import paths, AI review, SAP UI5 API) validate documentation accuracy on every PR.

Version 1.1.2​

Released: March 7, 2026

Bug Fixes​

  • build: disable chunk splitting to resolve Socket.dev obfuscation alert.

Version 1.1.1​

Released: March 7, 2026

Features​

  • docs: simplify onboarding to 2 commands, elevate AI agent pipeline.
  • prompts: add prompt factory with two SAP prompts and disclaimers.

Bug Fixes​

  • ci: add SAP domain words to cspell dictionary.
  • ci: inline upload-pages-artifact for SHA-pinning compliance.

Version 1.1.0​

Released: March 7, 2026

Features​

  • docs: add SEO badges, keywords, FAQ schema, config.

Bug Fixes​

  • docs: resolve Bing SEO scan issues and update footer copyright.

Version 1.0.4​

Released: March 7, 2026

Bug Fixes​

  • ci: ignore auto-generated CHANGELOG.md in markdownlint.
  • security: harden regex anchoring, XSS escaping, and hostname checks.

Version 1.0.0​

Released: February 16, 2026

Initial release of playwright-praman — Agent-First SAP UI5 Test Automation Plugin for Playwright.

Features​

  • 199 typed control proxies for SAP UI5 controls.
  • ui5, ui5Navigation, ui5Footer, fe, intent, pramanAI fixtures.
  • OData V2/V4 interception and mocking.
  • Fiori Elements List Report and Object Page testing.
  • 6 authentication strategies (storageState, basic, SAML, OAuth2, BTP, S/4HANA Cloud).
  • AI test generation, healing, and compliance enforcement agents.
  • Dual ESM + CJS build with validated sub-path exports.
  • 11-plugin ESLint configuration with zero-tolerance quality gates.