/sap-webgui

name: sap-webgui
description: Authoritative SAP WebGUI behavior and locator guidance for live exploration and Playwright script generation. Covers iframes, accessible names, generated IDs, selection screens, dialogs, ALV grids, toolbars, uploads, themes, and known SapSession helper limitations. Load before explore-ui live exploration and before build-scripts translation.

SAP WebGUI — UI Mechanics and Locator Rules

For bounded, self-contained support work, use `sap-task-helper` with explicit inputs, allowed writes, and an output contract.

Non-negotiable execution gate

The `abapfs_run_playwright_tests` tool verifies the workflow artifacts produced from WebGUI exploration and **will reject affected cases** when required screen mappings or script checks are missing. Do not guess locators or skip live verification.

Related workflows

Apply the guidance below for **WebGUI mechanics and pitfalls**. When the task also requires another workflow:

• follow `analyze-and-plan` for code coverage, `explore-ui` for `_screens.md`, and `design-cases` for test cases;
• follow `sap-webgui-recording` to decide when and how to obtain a focused user recording;
• follow `build-scripts` to translate a case into code;
• follow `helpers-reference` for exact `SapSession`/`SapArtifacts` methods and signatures.

Labels versus IDs

SAP WebGUI DOM IDs, generated reference numbers, row indexes, and CSS class suffixes can change across sessions, themes, support-package levels, and screen rerenders. Do not use them as test contracts.

Prefer, in order:

1. semantic role + exact accessible name; 2. role/name scoped to a verified dialog or group; 3. stable `title` or `aria-label` for toolbar controls; 4. visible cell text for grids; 5. `sap.setGridCell(columnTitle, rowIndex, value)` for editable ALV cells whose inputs have no accessible name (see “Editable ALV grid cells” below); 6. `{ technicalName: "<ABAP_FIELD>" }` on `sap.setField(...)` when two visible fields share the same label — last-resort disambiguator via the SAP data-dictionary name inside `lsdata` (see “The `lsdata` attribute” below); 7. a narrowly-contained `sap.raw()` locator using role/name when no helper fits.

The on-screen label and DOM accessible name are often—but not always—the same. Exploration must record both when they differ. English UI language is required because labels are part of the locator contract.

Interpreting Playwright recordings

Recordings are interaction evidence, not production specs. Classify generated code before using it:

**Preferred evidence**

• `getByRole(..., { name: "..." })` when the role and exact accessible name match the observed control;
• `getByTitle("...")` or a verified `aria-label` for toolbar actions;
• exact visible text scoped to a verified dialog, region, row, or tab strip.

**Conditionally usable evidence**

• `.first()` or `.nth()` only for a duplicate set whose order and meaning were explicitly verified and recorded in `_screens.md`;
• grid row text only when the row has stable business text and the intended column/action is unambiguous;
• Enter or other key presses as evidence of a required server roundtrip, translated through `SapSession`.

**Unsafe recording output**

• iframe names containing session timestamps, such as `itsframe1_202607...`;
• dynpro/control IDs such as `M0:46:...`;
• generated table IDs such as `tbl81` or `tbl166`;
• table-cell coordinates such as `[1,5]`, row numbers, or visual column indexes;
• CSS classes, generated suffixes, and unverified positional selectors;
• broad text filters such as `locator("div").filter({ hasText: /^Hold$/ })` when duplicates exist.

Complex dynpro and ME21N patterns

• ITS iframe names are session-scoped. Let `SapSession` select the frame; raw code must not preserve a recorded iframe name.
• PBO/server processing can replace a table within one flow. A recording changing from `tbl81[...]` to `tbl166[...]` after Enter proves that table identity is not a contract.
• Cell coordinates encode the current layout. Personalization, hidden columns, variants, horizontal scrolling, and support-package changes can move the same business field.
• Tab labels may exist several times in visible and hidden DOM sections. Recorded `.first()`/`.nth()` is not proof of the intended tab.
• A click immediately before `fill()` is usually recorder noise; preserve it only when clicking changes mode or activates a cell editor.
• Codegen records actions, not business assertions. Expected messages, persisted state, and visible results still come from the approved TC.
• Typed materials, vendors, plants, organizations, and document numbers are examples. Build scripts must resolve them through `.data.md`, not copy them as constants.

Stable replacement decision

For every required recorded interaction:

1. Use the matching `SapSession` helper with labels and scopes verified in `_screens.md`. 2. If no helper fits, use one narrow `sap.raw()` role/name, title, aria-label, or stable visible-text locator confirmed by live evidence. 3. If the recording exposes only an unsafe ID or coordinate, stop. Obtain focused exploration evidence or report a runtime/control-accessibility gap.

Never “improve” an unsafe ID by shortening it, regex-matching part of it, or replacing it with an unverified position.

WebGUI structure and common traps

• The ITS application normally renders inside an iframe. Page-level locators can miss every SAP control.
• **Every server round-trip invalidates every accessibility-tree `ref` on the page.** Clicking a radio, tab, toolbar button, Execute, Enter/OK, any F-key, or any grid-cell dropdown all trigger PBO and re-render the ITS DOM. Any `ref` captured from a previous `read_page` snapshot is stale after that action — including on plain selection screens, SM30/SE16-family screens, ALV outputs, dialogs, and F4 popups. This is not SE16N-specific; it happens on every SAP screen. Re-`read_page` before the next `click_element`/`type_in_page`