Skip to main content

Praman 1.2: Playwright 1.57+, TypeScript 6 & 5, CLI Agents, MCP Agents, Unified ui5= Selector Engine, and Interactive Inspector

· 10 min read
Maheshwar Kanitkar
Maheshwar Kanitkar
Creator of Praman

We are releasing Praman 1.2.0 to the latest tag on npm today. This is the largest functional update since the v1.0 launch, bringing first-class support for Playwright 1.57+, TypeScript 6.x & 5.x, Praman CLI Agents, Praman MCP Agents, a completely rewritten ui5= selector engine, a live interactive inspector, OpenTelemetry tracing & metrics, and a battery of quality-of-life improvements for teams building SAP UI5 test automation at scale.

What changed since v1.1.2​

Sixty-six commits landed between v1.1.2 and v1.2.0, touching the selector engine, CLI tooling, configuration system, error messages, CI pipeline, and documentation. Here is everything that matters.

🎭 Playwright 1.57+ — Tested, Validated, Flagged​

Praman now tracks Playwright 1.57+ as its peer baseline, and the CI matrix now runs both @playwright/test@stable and @playwright/test@next (canary) on every push. This means Praman validates against upcoming Playwright changes before they ship, giving teams early warning of regressions.

Playwright introduced several powerful new APIs. Praman exposes all of them behind opt-in feature flags so your existing tests are unaffected:

FlagAPIWhat it does
playwrightFeatures.screencastpage.screencastProgrammatic video — start/stop recording, overlays, real-time frames
playwrightFeatures.ariaSnapshotDepthlocator.ariaSnapshot({ depth })Scoped accessibility tree snapshots — ideal for deep SAP component hierarchies
playwrightFeatures.setStorageStatebrowserContext.setStorageState()Replace auth state in-place without spawning a new context
playwrightFeatures.locatorNormalizelocator.normalize()Auto-convert ad-hoc selectors to aria-role / test-id best practices
playwrightFeatures.urlPatternMatcherURL Pattern API in toHaveURLModern URL Pattern matching instead of RegExp

Enable any flag in playwright.config.ts:

import { defineConfig } from 'playwright-praman';

export default defineConfig({
  use: {
    pramanConfig: {
      playwrightFeatures: { screencast: true },
    },
  },
});

🔷 TypeScript 6.x & 5.x — Future-Proof Support​

Praman is now compiled and shipped with TypeScript 6.0.2, with full backward compatibility for TypeScript 5.x. Every exported type, generic, and conditional type has been audited against TS 6 semantics. The CI matrix runs a TS compatibility job that builds the package against both TS 5.9 and TS 6.0.

If you are still on TypeScript 5.x, nothing changes. If you have migrated to TS 6.0, all Praman APIs now give you accurate inference, narrowing, and editor completions under the stricter TS 6 rules.

🔍 A New ui5= Selector Engine​

The most architecturally significant change in v1.2 is the complete rewrite of the UI5 selector engine.

The old approach: three separate parsers​

v1.1 shipped three distinct engines — a CSS engine, an XPath engine, and a legacy ui5-selector-engine. They had overlapping responsibilities, inconsistent error messages, and subtle differences in how they handled array properties or negative positions.

The new approach: one engine, two syntaxes​

v1.2 ships a unified engine powered by fontoxpath (fully conformant XPath 3.1) and css-selector-parser. The CSS-style selectors you already write (sap.m.Button[text=Save]) are parsed to an AST, converted to XPath 3.1, and evaluated against an in-memory XML DOM that mirrors the live UI5 control tree of the page.

This is the same approach used by playwright-ui5 — proven in production SAP environments.

New selectors you can use today​

// :labeled() — find a control by the sap.m.Label that points to it
page.locator("ui5=sap.m.Input:labeled('Vendor Number')");

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

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

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

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

// Positional
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​

If your tests use the enableXpathEngine config option, remove it. The unified engine handles both CSS-style and XPath selectors — no per-engine configuration is needed. All other selectors continue to work unchanged.

🔬 npx praman inspect — Find Controls Without Guessing​

The most-requested developer experience improvement: a live interactive inspector that lets you click any element in a running SAP app and instantly see the UI5 control metadata and copy-paste-ready selectors.

# Point it at your SAP Fiori Launchpad
npx praman inspect https://my-sap.example.com/sap/bc/ui5_ui5/...

# Pass a Playwright storageState file to authenticate
npx praman inspect https://my-sap.example.com --auth .auth/user.json

Click any element in the headed browser and the terminal prints:

━━━ 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: semantic property matches first, IDs second, composite selectors last. The browser highlights the selected control with a blue overlay so you can confirm you clicked the right element.

This makes writing your first test against an unfamiliar SAP app dramatically faster. Instead of opening DevTools, digging through the DOM, and guessing control types, you click and copy.

⚙️ Two New CLI Commands​

npx praman config​

Prints the fully resolved PramanConfig — every value, including those injected by environment variables — so you can quickly debug why a CI run is using different auth credentials than your local machine.

npx praman config

Nested Environment Variables​

Configuration now supports deep injection via environment variables. No more editing playwright.config.ts per CI environment:

# Set AI provider in CI
PRAMAN_AI_PROVIDER=azure-openai
PRAMAN_AI_API_KEY=${{ secrets.AZURE_OPENAI_KEY }}

# Set telemetry in CI
PRAMAN_TELEMETRY_ENABLED=true
PRAMAN_TELEMETRY_ENDPOINT=https://otel-collector:4318

🔌 Extension System​

Praman now ships a plugin API that lets shared testing libraries ship custom matchers and fixture extensions:

import { defineExtension } from 'playwright-praman';

export const approvalExtension = defineExtension({
  name: 'approval-workflow',
  matchers: {
    toHaveApprovalStatus: async (proxy, expected) => {
      const status = await proxy.getProperty('approvalStatus');
      return {
        pass: status === expected,
        message: () => `Expected ${expected}, got ${status}`,
      };
    },
  },
});

Register extensions in defineConfig:

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

🤖 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. Token-efficient browser automation via stdin/stdout, optimized for Claude Code, GitHub Copilot, and Cursor. No MCP server required.

Three agents ship out of the box:

  • Planner — explores a live SAP app and produces a structured test plan
  • Generator — generates compliant Playwright tests from the plan
  • Healer — debugs and fixes failing tests with SAP domain knowledge

Learn more: CLI Agents Guide · Running Your Agent

🔌 Praman MCP Agents​

For richer inline feedback and IDE integrations, Praman also supports MCP (Model Context Protocol) agents — a JSON-RPC server that provides structured accessibility snapshots, live control discovery, and step-level feedback to AI agents running inside VS Code Copilot, Cursor, and JetBrains AI.

Both CLI and MCP agents are installed by default with npx playwright-praman init. See MCP vs CLI for a comparison of when to use each approach.

🤖 Playwright CLI Agents — Now the Default​

This is a quality-of-life change with a big practical impact for teams getting started.

Previously, Playwright CLI–based agents (the token-efficient alternative to MCP) required an explicit --cli opt-in flag. Starting with this release, CLI agents are installed by default alongside MCP agents whenever you run init or init-agents. If you only want MCP agents, pass --no-cli.

Auto-install of peer dependencies​

init now checks for — and installs — four packages in a single npm install call if any are missing:

PackageRole
@playwright/testPlaywright test runner
@playwright/cliPlaywright CLI for agent browser control
playwright-pramanThe plugin itself
dotenvEnvironment variable loading

This means npm install playwright-praman && npx playwright-praman init is the complete setup sequence — no separate npm install @playwright/test @playwright/cli step required.

Flag change​

BeforeAfter
--cli (opt-in, default off)--no-cli (opt-out, default on)
# Install everything including CLI agents (new default)
npx playwright-praman init

# MCP agents only
npx playwright-praman init --no-cli

# init-agents — same default
npx playwright-praman init-agents --loop=claude
npx playwright-praman init-agents --loop=copilot --no-cli

A warning is printed when @playwright/cli is absent from node_modules but CLI agents are being scaffolded, so you know exactly what to run if you skipped auto-install.

📋 Errors Now Link to Docs​

Every PramanError now carries a docsUrl pointing directly to the relevant documentation anchor. The URL appears in the terminal, in serialized JSON for reporting, and in the AI-envelope when 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 in the UI5 view
    - Try: npx praman inspect <url>

⬆️ Node.js 22 Minimum​

Node.js 20 reached End-of-Life in April 2026. Praman v1.2 requires Node.js 22 or later.

Update your CI workflow:

- uses: actions/setup-node@v4
  with:
    node-version: '22'

🔒 Zero Vulnerabilities​

All npm audit findings — in both the main package and the docs/ workspace — are resolved to zero. Every security bump has been validated for compatibility with Praman's zero-tolerance CI gates.

📡 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 are supported: OTLP (Jaeger, Grafana Tempo, any OTLP collector), Jaeger (native OTLP), and Azure Monitor (via Application Insights connection string).

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. See the Telemetry Setup Guide for detailed configuration.

📚 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

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.
  • 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.

Upgrading from v1.1​

npm install playwright-praman@latest

Breaking changes in v1.2: One — the enableXpathEngine configuration field has been removed. Simply delete it from your PramanConfig; the unified selector engine replaces its functionality automatically.

All fixtures, matchers, proxies, and authentication strategies remain source-compatible. No test code changes are required.

What's next​

The roadmap for v1.3 focuses on:

  • OPA5 migration agent (ADR-030): An automated agent that reads existing OPA5 test files and generates equivalent Praman tests, including control mapping and assertion translation.
  • BTP Work Zone multi-tenant improvements to the btpWorkZone fixture.
  • Playwright MCP integration: First-class support for @playwright/mcp session hand-off to Praman's AI agents.

Follow the project on GitHub or subscribe to the npm package for release notifications.

Praman is open-source under the Apache-2.0 license. Docs · npm · GitHub · Discord