Playwright CLI for SAP Testing

The Playwright CLI (@playwright/cli) is a terminal-based interface for controlling browsers, designed for AI agent workflows. Praman extends it with SAP UI5-specific capabilities — bridge injection, control discovery, structured snapshots, and screencast — to create a token-efficient alternative to the MCP-based agent workflow.

Both MCP and CLI are first-class, coexisting options. They produce identical gold-standard .spec.ts files using Praman fixtures.

Why Playwright CLI?

Benefit	Details
30–50% fewer tokens	CLI commands are compact strings vs structured JSON-RPC tool calls
Named persistent sessions	-s=sap keeps browser state across commands — no MCP server lifecycle
Same output quality	Identical .spec.ts files with import { test } from 'playwright-praman'
Works everywhere	Any AI agent with shell access (Bash tool) can use CLI commands
Coexists with MCP	Use both in the same project — shared auth state, shared config

How It Works

┌───────────────────────────────────────────────────────────────┐
│                     AI Agent (Claude, Copilot, Cursor)         │
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────┐  │
│  │ Plan        │ →  │ Generate     │ →  │ Heal            │  │
│  │ CLI session │    │ Validate     │    │ --debug=cli     │  │
│  │ + discovery │    │ live browser │    │ fix selectors   │  │
│  └─────────────┘    └──────────────┘    └─────────────────┘  │
│         │                  │                    │              │
│         ▼                  ▼                    ▼              │
│  test-plan.md       app.spec.ts        app.spec.ts (fixed)   │
└───────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│  Playwright CLI  +  Praman Bridge       │
│  ─────────────────────────────────────  │
│  open / snapshot / run-code / fill /    │
│  click / state-save / state-load        │
│  + sap.ui.core.ElementRegistry          │
│  + window.__praman_bridge               │
└─────────────────────────────────────────┘

1. Agent opens a CLI session with the Praman bridge injected via initScript
2. Bridge exposes UI5 controls — run-code calls sap.ui.core.ElementRegistry for discovery
3. Agent generates tests using Praman fixtures exclusively (ui5.control(), ui5.click())
4. Tests are healed by attaching to --debug=cli sessions and inspecting live page state

Quick Start

# 1. Install (CLI agents are included by default)
npm install --save-dev playwright-praman
npx playwright-praman init

# 2. Export the bridge init script
npx playwright-praman bridge-script --output .playwright/praman-bridge.js

# 3. Verify your setup
npx playwright-praman doctor

# 4. Run an agent (Claude Code example)
# /praman-cli-plan
# "Explore the Manage Purchase Orders app and create a test plan"

Guides

Read the guides in this order for a structured learning path, or jump to any topic directly.

Setup and Configuration

Guide	What You Will Learn
Playwright CLI Setup	Install @playwright/cli, configure bridge injection, verify with Quick Test
MCP vs CLI	Side-by-side comparison — when to use MCP, CLI, or both

Discovery and Interaction

Guide	What You Will Learn
CLI Control Discovery	run-code patterns for finding controls by ID, type, property; dialog discovery; V2 vs V4 differences
CLI Iframe Handling	Bridge auto-injection into SAP iframes, #sap-ui-static scanning, cross-origin limitations

AI Agents

Guide	What You Will Learn
CLI Agents	Three-agent pipeline (Plan, Generate, Heal), slash commands, skill files, IDE setup
Browser Bind & Screencast	PRAMAN_BIND=1 to expose test browser to agents, screencast chapters, frame streaming

Reference

Guide	What You Will Learn
CLI Quick Reference	Complete command table, run-code patterns, session management, auth workflow cheat sheet

Key Concepts

Bridge Injection

The Praman bridge (window.__praman_bridge) is a JavaScript module injected into every page via Playwright's initScript mechanism. It provides access to the UI5 runtime — control registry, property getters, OData model inspection — through a stable API that agents consume via run-code.

# Generate the bridge script
npx playwright-praman bridge-script --output .playwright/praman-bridge.js

See CLI Setup for full configuration.

Pre-Built Discovery Scripts

Praman ships 4 parameter-free run-code scripts in dist/scripts/ for common discovery operations:

# Discover all controls with types, properties, methods (max 100)
playwright-cli -s=sap run-code "$(cat node_modules/playwright-praman/dist/scripts/discover-all.js)"

# Wait for UI5 stability
playwright-cli -s=sap run-code "$(cat node_modules/playwright-praman/dist/scripts/wait-for-ui5.js)"

See CLI Quick Reference for the full scripts table.

Skill Files

Praman installs skill files to per-IDE locations so agents auto-discover SAP testing capabilities:

IDE	Skill Location
Claude Code	.claude/skills/praman-sap-cli/SKILL.md
GitHub Copilot	.github/skills/praman-sap-cli/SKILL.md
Project root	skills/praman-sap-cli/SKILL.md

When an agent receives "Use playwright skills to test SAP app", it finds the skill file, reads the command reference and discovery patterns, and generates Praman-compliant tests.

See CLI Agents for skill file details.

Praman CLI Commands

In addition to standard Playwright CLI commands, Praman provides:

Command	Purpose
npx playwright-praman bridge-script	Export bridge init script for CLI config
npx playwright-praman snapshot	Capture structured SAP UI5 control tree snapshot
npx playwright-praman doctor	Validate complete setup (12 checks)
npx playwright-praman capabilities	Show capability manifest for agent preflight
npx playwright-praman verify-spec <file>	Validate generated .spec.ts against gold-standard rules

See CLI Quick Reference for full option tables.

Browser Bind (Playwright 1.59+)

Enable PRAMAN_BIND=1 to let CLI agents connect to a running test browser:

PRAMAN_BIND=1 npx playwright test tests/e2e/my-sap-test.spec.ts

The test fixture calls browser.bind('praman-agent') and logs the endpoint URL. A CLI agent can then attach to inspect live UI state mid-test.

See Browser Bind & Screencast for details.

Supported IDEs

CLI agents are installed for all detected IDEs during npx playwright-praman init:

IDE	Agent Format	Invocation
Claude Code	.claude/agents/praman-sap-*-cli.md	/praman-cli-plan
GitHub Copilot	.github/agents/praman-sap-*-cli.agent.md	@praman-sap-planner-cli
Cursor	.cursor/rules/praman-cli.mdc	Auto-activates on .spec.ts files
Jules	.jules/praman-setup.md	References CLI commands

Pass --no-cli to init or init-agents to skip CLI agent installation.

Next Steps

• New to Praman? Start with Getting Started and Agent & IDE Setup
• Ready to install? Go to Playwright CLI Setup
• Choosing between MCP and CLI? Read MCP vs CLI
• Already set up? Jump to CLI Agents to run your first agent