Skip to main content
Version: 1.1.4

getByRoleUI5

getByRoleUI5 finds UI5 controls by control type (role) plus optional control property filters. It talks to the UI5 runtime (not raw DOM) making it far more stable than default playwright locators.

Signature​

page.getByRoleUI5(
  role: string, // UI5 control type (e.g., 'Button', 'Table')
  properties?: Record<string, string>,  // Control properties to match (e.g., { text: 'Save' })
  options?: { exact?: boolean }
): Locator

Parameters​

ParameterTypeRequiredDescription
rolestring✅The UI5 control type as exposed by the framework (case-insensitive)
Examples: Button, Input, Table, Dialog, IconTabFilter
propertiesobject❌A map of control properties to match
Example: { text: 'Save' }, { icon: 'sap-icon://search' }
options.exactboolean❌When true, property matching is case-sensitive and requires exact matches
When false (default), matching is case-insensitive and allows partial matches

Quick Examples​

// Click a button by its text
await page.getByRoleUI5('Button', { text: 'Save' }).click();

// Fill an input by its label property
await page.getByRoleUI5('Input', { label: 'First Name' }).fill('John');

// Select a list item inside a ComboBox popup
await page.getByRoleUI5('ComboBox', { name: 'Country' }).click();
await page.getByRoleUI5('Item', { text: 'Germany' }).click();

How It Works​

getByRoleUI5 works by injecting JavaScript into the page that communicates directly with the UI5 framework. Instead of relying on the DOM structure, it uses UI5's own APIs to find controls based on their type and properties.

Using UI5 Inspector

To identify the correct control types and properties, install the UI5 Inspector browser extension:

UI5 Inspector for Chrome

This tool shows you the UI5 control hierarchy and all available properties for each control.

Example with UI5 Inspector​

Example getByRoleUI5

In this example from ui5.sap.com, we want to click on the "Documentation" tab (highlighted in blue). Using UI5 Inspector, we can see it's an IconTabFilter control with various properties.

Any of these locators will work:

// Find by icon property
await page.getByRoleUI5('IconTabFilter', { icon: 'sap-icon://learning-assistant' }).click();

// Find by text property
await page.getByRoleUI5('IconTabFilter', { text: 'Documentation' }).click();

// Find by key property
await page.getByRoleUI5('IconTabFilter', { key: 'topic' }).click();

// Find by index (if it's the second IconTabFilter)
await page.getByRoleUI5('IconTabFilter').nth(1).click();

Why Use getByRoleUI5?​

  • Stable: Ignores volatile generated DOM IDs
  • Readable: Intent expressed via control type & business-facing properties
  • Precise: Filters on multiple properties
  • Composable: Chain with Playwright (.nth(), .first(), assertions, etc.)

Comparison with Standard Playwright​

Standard Playwright (Brittle)​

// Using standard Playwright locators - likely to break when UI changes
await page.locator('.sapMITBContent > .sapMITBTab:nth-child(2)').click();
// or
await page.locator('[id$="-documentationTab"]').click();

Playwright-SAP (Robust)​

// Using getByRoleUI5 - stable across UI changes
await page.getByRoleUI5('IconTabFilter', { text: 'Documentation' }).click();

Best Practices​

  • Prefer semantic properties (text, label, title, icon, name) over index-based .nth().
  • Add one property at a time while debugging; over‑constraining can yield zero results.
  • Use exact: true only when partial matches cause ambiguity.
  • Inspect with the UI5 Inspector extension to discover real property names.

See Also​