# playwright-praman

> Agent-First SAP UI5 Test Automation Plugin for Playwright. Typed UI5 control proxies,
> AI-powered test generation, 14 Playwright fixtures, 179 capabilities across 14 categories.
> Supports SAP S/4HANA, BTP, Fiori Elements. Cross-platform: Windows, macOS, Linux.
> npm: `npm install playwright-praman` | Import: `import { test, expect } from 'playwright-praman'`

## Docs

- [Getting Started](https://praman.dev/docs/guides/getting-started): Installation, project setup, first test in under 5 minutes
- [Configuration Reference](https://praman.dev/docs/guides/configuration): Zod-validated config schema with defaults — empty `{}` is valid
- [Fixture Reference](https://praman.dev/docs/guides/fixtures): 14 fixtures — ui5, sapAuth, ui5Navigation, fe, pramanAI, intent, and more
- [Selector Reference](https://praman.dev/docs/guides/selectors): UI5Selector fields — controlType, id, properties, bindingPath, ancestor, descendant
- [Control Interactions](https://praman.dev/docs/guides/control-interactions): click, fill, press, select, check, clear, getText, getProperty, enterText
- [Custom Matchers](https://praman.dev/docs/guides/custom-matchers): 10 UI5-specific expect matchers — toHaveUI5Text, toBeUI5Visible, toBeUI5Enabled
- [Authentication Guide](https://praman.dev/docs/guides/authentication): 6 auth strategies — on-prem, BTP SAML, Office 365, API, certificate, multi-tenant
- [Navigation](https://praman.dev/docs/guides/navigation): 9 FLP navigation methods plus BTP WorkZone dual-frame support
- [Error Reference](https://praman.dev/docs/guides/errors): 14 error classes, 58 error codes with retryable flags and suggestions[]
- [OData Operations](https://praman.dev/docs/guides/odata-operations): Model operations (browser-side) and HTTP CRUD (node-side)
- [Fiori Elements Testing](https://praman.dev/docs/guides/fiori-elements): List Report, Object Page, FE Table, FE List helpers
- [SAP Control Cookbook](https://praman.dev/docs/guides/sap-control-cookbook): Recipes for common SAP UI5 controls in Praman tests
- [AI Integration](https://praman.dev/docs/guides/ai-integration): LLM service, page discovery, agentic handler, capability registry

## Interaction Decision Flowchart

When clicking / pressing a control, choose the right method:

```
Is the element a UI5 control? (check: sap.ui.getCore().byId(id) !== undefined)
│
├─ YES → Use Praman fixture
│  │
│  ├─ Standard sap.m.* / sap.ui.comp.* / sap.uxap.*
│  │  └─ await ui5.click({ id }) or await ui5.press({ id })
│  │     Default strategy (ui5-native) fires: firePress → fireSelect → fireTap → DOM click
│  │
│  ├─ sap.m.IconTabFilter (FLP space/section tabs)
│  │  └─ ⚠ firePress() is a NO-OP on this control
│  │     Use: await page.getByText('Tab Label', { exact: true }).click()
│  │     Or switch to: PRAMAN_INTERACTION_STRATEGY=dom-first
│  │
│  ├─ Custom composite controls (missing firePress)
│  │  └─ Try ui5.click() first — ui5-native falls back to DOM click
│  │     If that fails → switch to PRAMAN_INTERACTION_STRATEGY=dom-first
│  │
│  └─ UI5 Web Components (Shadow DOM: ui5-button, ui5-input)
│     └─ Use page.getByRole() / page.getByText() + .click()
│        Or switch to: PRAMAN_INTERACTION_STRATEGY=dom-first
│
└─ NO → Not a UI5 control (plain HTML, login pages, iframes)
   └─ Use Playwright native: page.getByRole() / page.locator() + .click()
      Praman fixtures do NOT apply here
```

Strategy summary (set via `PRAMAN_INTERACTION_STRATEGY` env var or config):

| Strategy     | Fallback chain                                            | Best for                        |
|------------- |---------------------------------------------------------- |-------------------------------- |
| `ui5-native` | firePress → fireSelect → fireTap → DOM click (default)   | Standard Fiori apps             |
| `dom-first`  | DOM click → firePress → fireSelect → fireTap             | Web Components, IconTabFilter   |
| `opa5`       | RecordReplay.interactWithControl → firePress/fireSelect   | SAP compliance, UI5 >= 1.94     |

Key rules:
- `ui5.click()` and `ui5.press()` are **identical** (press delegates to click)
- NEVER use `page.click('#__xmlview0--myBtn')` — raw UI5 IDs are banned (compliance check fails)
- Auth/login pages are NOT UI5 — always use Playwright native there
- For inputs: `setValue()` + `fireChange()` + `waitForUI5()` — never just `page.fill()`

## Examples

- [Basic Test](https://praman.dev/docs/examples/basic-test): Control discovery by type and property, verification, press
- [Auth Setup](https://praman.dev/docs/examples/auth-setup): OnPrem, BTP Cloud SAML, and Office 365 authentication examples
- [Dialog Handling](https://praman.dev/docs/examples/dialog-handling): Open, interact with, and close SAP UI5 dialogs
- [Table Operations](https://praman.dev/docs/examples/table-operations): SmartTable discovery, row reading, OData binding data
- [Gold Standard BOM](https://praman.dev/docs/examples/gold-standard-bom): Complete BOM maintenance E2E test — the Praman gold standard
- [Hybrid Login](https://praman.dev/docs/examples/hybrid-login): Playwright native for login + Praman for UI5 — auto-fallback pattern

## API

- [Full API Reference](https://praman.dev/docs/api/): TypeDoc-generated API documentation for all 6 sub-path exports
- [llms-full.txt](https://praman.dev/llms-full.txt): Complete documentation with inline API signatures

## Optional

- [Architecture Overview](https://praman.dev/docs/guides/architecture-overview): 5-layer architecture — Core, Bridge, Proxy, Fixtures, AI
- [Bridge Internals](https://praman.dev/docs/guides/bridge-internals): UI5 bridge injection and browser-side script details
- [Control Proxy](https://praman.dev/docs/guides/control-proxy): JavaScript Proxy pattern for UI5 control method forwarding
- [Interaction Strategies](https://praman.dev/docs/guides/interaction-strategies): ui5-native, dom-first, opa5 — swappable strategies
- [Intent API](https://praman.dev/docs/guides/intent-api): Business-oriented test operations for SAP S/4HANA modules
- [Vocabulary System](https://praman.dev/docs/guides/vocabulary-system): SAP business term resolution with fuzzy matching
- [Capabilities & Recipes](https://praman.dev/docs/guides/capabilities-recipes): 179 capabilities registry for AI agent introspection
- [Reporters](https://praman.dev/docs/guides/reporters): ComplianceReporter and ODataTraceReporter
- [Docker & CI/CD](https://praman.dev/docs/guides/docker-cicd): Container setup, 3-OS CI matrix, quality gates
- [Migration from wdi5](https://praman.dev/docs/guides/migration-from-wdi5): wdi5 to Praman API mapping and migration checklist
- [Migration from Playwright](https://praman.dev/docs/guides/migration-from-playwright): Layer Praman on top of existing Playwright tests
- [Migration from Tosca](https://praman.dev/docs/guides/migration-from-tosca): Tosca to Praman migration guide
