feat(e2e): refactor tests to use semantic selectors and remove flaky anti-patterns

[gustavolira]

Description

Refactored Playwright E2E tests to follow best practices using semantic locators and removed common anti-patterns that cause test flakiness.

Which issue(s) does this PR fix

• Fixes https://issues.redhat.com/browse/RHIDP-11136

PR acceptance criteria

Please make sure that the following steps are complete:

• GitHub Actions are completed and successful
• Unit Tests are updated and passing
• E2E Tests are updated and passing
• Documentation is updated if necessary (requirement for new features)
• Add a screenshot if the change is UX/UI related

How to test changes / Special notes to the reviewer

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign gustavolira for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• e2e-tests/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[rhdh-qodo-merge]

PR Reviewer Guide 🔍

(Review updated until commit ce0cf78)

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🔒 No security concerns identified

⚡ Recommended focus areas for review Locator Robustness New chained .or() locators combine different strategies; if both branches match multiple elements, interactions may become ambiguous or flaky. Validate that these locators resolve to a single, actionable element in all target UIs/environments. // Wait for permissions step to be ready await expect(page.getByRole("heading", { name: /Configure permission/i }).or(page.getByTestId("nextButton-2"))).toBeVisible(); await uiHelper.clickButton("Next"); // Wait for review step to be ready await expect(page.getByRole("heading", { name: /Review/i }).or(page.getByRole("button", { name: "Save" }))).toBeVisible(); await uiHelper.clickButton("Save"); API Surface Stability Large addition of new semantic helper methods alongside deprecated legacy selectors introduces dual paths. Ensure callers migrate consistently and that tree-shaking/build size and naming remain stable to avoid accidental cross-usage. * New code should use SemanticSelectors class or the get*() methods below. */ export const UI_HELPER_ELEMENTS = { // ======================================== // LEGACY SELECTORS - Maintained for backward compatibility // These will be removed in a future phase after all tests are migrated // ======================================== /** @deprecated Use SemanticSelectors.button(page, name) or getButton() */ MuiButtonLabel: 'span[class^="MuiButton-label"],button[class*="MuiButton-root"]', /** @deprecated Use SemanticSelectors.button(page, name) with filter */ MuiToggleButtonLabel: 'span[class^="MuiToggleButton-label"]', /** @deprecated Use SemanticSelectors.inputByLabel(page, label) */ MuiBoxLabel: 'div[class*="MuiBox-root"] label', /** @deprecated Use SemanticSelectors.tableHeader(page, name) or getTableHeader() */ MuiTableHead: 'th[class*="MuiTableCell-root"]', /** @deprecated Use SemanticSelectors.tableCell(page, text) or getTableCell() */ MuiTableCell: 'td[class*="MuiTableCell-root"]', /** @deprecated Use SemanticSelectors.tableRow(page, text) or getTableRow() */ MuiTableRow: 'tr[class*="MuiTableRow-root"]', /** @deprecated Use semantic selectors with appropriate styling checks */ MuiTypographyColorPrimary: ".MuiTypography-colorPrimary", /** @deprecated Use SemanticSelectors.checkbox() with appropriate checks */ MuiSwitchColorPrimary: ".MuiSwitch-colorPrimary", /** @deprecated Use SemanticSelectors.button(page, name) */ MuiButtonTextPrimary: ".MuiButton-textPrimary", /** @deprecated Use getCardByHeading() method or SemanticSelectors.region().filter() */ MuiCard: (cardHeading: string) => `//div[contains(@class,'MuiCardHeader-root') and descendant::*[text()='${cardHeading}']]/..`, /** @deprecated Use getCardByText() method or SemanticSelectors.region().filter() */ MuiCardRoot: (cardText: string) => `//div[contains(@class,'MuiCard-root')][descendant::text()[contains(., '${cardText}')]]`, /** @deprecated Use SemanticSelectors.table(page) or getTable() */ MuiTable: "table.MuiTable-root", /** @deprecated Use SemanticSelectors.region().filter() for card headers */ MuiCardHeader: 'div[class*="MuiCardHeader-root"]', /** @deprecated Use SemanticSelectors.inputByPlaceholder() or inputByLabel() */ MuiInputBase: 'div[class*="MuiInputBase-root"]', /** @deprecated Use appropriate semantic selector based on element role */ MuiTypography: 'span[class*="MuiTypography-root"]', /** @deprecated Use SemanticSelectors.alert(page, name) */ MuiAlert: 'div[class*="MuiAlert-message"]', /** ✅ This is already semantic, but prefer SemanticSelectors.tab(page, name) */ tabs: '[role="tab"]', /** @deprecated Use SemanticSelectors.tableRow(page, text) */ rowByText: (text: string) => `tr:has(:text-is("${text}"))`, // ======================================== // NEW SEMANTIC METHODS - Preferred approach // Use these for new code and when refactoring // ======================================== /** * Get a button by its accessible name * ✅ Preferred over MuiButtonLabel * @example UI_HELPER_ELEMENTS.getButton(page, 'Submit').click() */ getButton: (page: Page, name: string | RegExp): Locator => SemanticSelectors.button(page, name), /** * Get a link by its accessible name * ✅ Preferred for navigation elements * @example UI_HELPER_ELEMENTS.getLink(page, 'View Details').click() */ getLink: (page: Page, name: string | RegExp): Locator => SemanticSelectors.link(page, name), /** * Get a table element * ✅ Preferred over MuiTable * @example const table = UI_HELPER_ELEMENTS.getTable(page) */ getTable: (page: Page): Locator => SemanticSelectors.table(page), /** * Get a table cell by content * ✅ Preferred over MuiTableCell * @example UI_HELPER_ELEMENTS.getTableCell(page, 'Active') */ getTableCell: (page: Page, text?: string | RegExp): Locator => SemanticSelectors.tableCell(page, text), /** * Get a table header (column header) * ✅ Preferred over MuiTableHead * @example UI_HELPER_ELEMENTS.getTableHeader(page, 'Created At').click() */ getTableHeader: (page: Page, name: string | RegExp): Locator => SemanticSelectors.tableHeader(page, name), /** * Get a table row by content * ✅ Preferred over MuiTableRow and rowByText * @example const row = UI_HELPER_ELEMENTS.getTableRow(page, 'Guest User') */ getTableRow: (page: Page, text?: string | RegExp): Locator => SemanticSelectors.tableRow(page, text), /** * Get a heading by text and optional level * @example UI_HELPER_ELEMENTS.getHeading(page, 'RBAC', 1) */ getHeading: (page: Page, name: string | RegExp, level?: 1 | 2 | 3 | 4 | 5 | 6): Locator => SemanticSelectors.heading(page, name, level), /** * Get a tab by name * ✅ Preferred over tabs selector * @example UI_HELPER_ELEMENTS.getTab(page, 'Settings').click() */ getTab: (page: Page, name: string | RegExp): Locator => SemanticSelectors.tab(page, name), /** * Get a dialog/modal * @example const dialog = UI_HELPER_ELEMENTS.getDialog(page, 'Confirm Delete') */ getDialog: (page: Page, name?: string | RegExp): Locator => SemanticSelectors.dialog(page, name), /** * Get a card by heading text (semantic alternative to MuiCard) * ✅ Preferred over MuiCard XPath selector * @example const card = UI_HELPER_ELEMENTS.getCardByHeading(page, 'RHDH Build info') */ getCardByHeading: (page: Page, heading: string | RegExp): Locator => { // Find region or article containing the heading return page.locator('[role="region"], article, section').filter({ has: page.getByRole('heading', { name: heading }) }).first(); }, /** * Get a card by text content (semantic alternative to MuiCardRoot) * ✅ Preferred over MuiCardRoot XPath selector * @example const card = UI_HELPER_ELEMENTS.getCardByText(page, 'Context one') */ getCardByText: (page: Page, text: string | RegExp): Locator => { return page.locator('[role="region"], article, section').filter({ hasText: text }).first(); }, /** * Get an input by label * ✅ Preferred over MuiInputBase * @example UI_HELPER_ELEMENTS.getInputByLabel(page, 'Email').fill('[email protected]') */ getInputByLabel: (page: Page, label: string | RegExp): Locator => SemanticSelectors.inputByLabel(page, label), /** * Get an input by placeholder * ✅ Preferred over MuiInputBase * @example UI_HELPER_ELEMENTS.getInputByPlaceholder(page, 'Search...').fill('test') */ getInputByPlaceholder: (page: Page, placeholder: string | RegExp): Locator => SemanticSelectors.inputByPlaceholder(page, placeholder), /** * Get an alert element * ✅ Preferred over MuiAlert * @example await expect(UI_HELPER_ELEMENTS.getAlert(page, 'Error')).toBeVisible() */ getAlert: (page: Page, name?: string | RegExp): Locator => SemanticSelectors.alert(page, name), /** * Get navigation element * @example const nav = UI_HELPER_ELEMENTS.getNavigation(page) */ getNavigation: (page: Page, name?: string | RegExp): Locator => SemanticSelectors.navigation(page, name), /** * Get menu item * @example UI_HELPER_ELEMENTS.getMenuItem(page, 'Delete').click() */ getMenuItem: (page: Page, name: string | RegExp): Locator => SemanticSelectors.menuItem(page, name), }; Assertion Semantics Replaced waitForSelector/timeout with visibility assertions like expect(page.getByText("Error")).toBeHidden(); verify "Error" text is uniquely scoped to the creation flow to avoid false negatives if unrelated error banners exist. await expect(page.getByText("second")).toBeVisible(); // Verify no error occurred during creation await expect(page.getByText("Error")).toBeHidden();

📄 References No matching references available

[rhdh-qodo-merge]

PR Type

Enhancement

---

Description

• Introduce SemanticSelectors class with 30+ role-based locator methods following Playwright best practices

• Add semantic getter methods to page object files (global-obj, page-obj) as preferred alternatives to legacy MUI class selectors

• Mark legacy CSS class selectors as deprecated with migration guidance to semantic selectors

• Include WaitStrategies helper class for preferred wait patterns over waitForTimeout

---

File Walkthrough

Relevant files

Enhancement

semantic-selectors.ts New semantic selectors class with role-based locators        e2e-tests/playwright/support/selectors/semantic-selectors.ts Create new SemanticSelectors class with 30+ static methods for role-based element selection (button, link, table, heading, input, checkbox, dialog, etc.) Implement helper functions findTableCell() and findTableCellByColumn() for table navigation Add WaitStrategies class with methods for visibility, network idle, and API response waiting Include comprehensive JSDoc documentation with examples for each selector method +475/-0  global-obj.ts Add semantic getter methods to global page objects              e2e-tests/playwright/support/page-objects/global-obj.ts Add imports for Page, Locator, and SemanticSelectors Mark all legacy MUI class selectors (WAIT_OBJECTS, UI_HELPER_ELEMENTS) as @deprecated with migration guidance Add 15+ new semantic getter methods (getButton, getLink, getTable, getTableCell, getTableHeader, getTableRow, getHeading, getTab, getDialog, getCardByHeading, getCardByText, getInputByLabel, getInputByPlaceholder, getAlert, getNavigation, getMenuItem) Each new method wraps SemanticSelectors or implements semantic filtering with JSDoc examples +180/-1  page-obj.ts Add semantic methods to all page component objects              e2e-tests/playwright/support/page-objects/page-obj.ts Add imports for Page, Locator, and SemanticSelectors Mark legacy MUI class selectors as @deprecated across all component objects (HOME_PAGE_COMPONENTS, SEARCH_OBJECTS_COMPONENTS, CATALOG_IMPORT_COMPONENTS, KUBERNETES_COMPONENTS, BACKSTAGE_SHOWCASE_COMPONENTS, SETTINGS_PAGE_COMPONENTS, ROLES_PAGE_COMPONENTS, DELETE_ROLE_COMPONENTS, ROLE_OVERVIEW_COMPONENTS_TEST_ID) Add 25+ new semantic getter methods with JSDoc documentation and usage examples Include migration guidance comments for each deprecated selector Preserve existing data-testid and aria-label selectors marked as already semantic +220/-0

---

[rhdh-qodo-merge]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Enforce adoption of new selectors To ensure consistent adoption of the new semantic selectors, this suggestion proposes creating a custom ESLint rule. This rule would flag and prevent the use of the old, deprecated selectors, enforcing the migration and improving long-term code maintenance. Examples: e2e-tests/playwright/support/page-objects/global-obj.ts [26-207] export const UI_HELPER_ELEMENTS = { // ======================================== // LEGACY SELECTORS - Maintained for backward compatibility // These will be removed in a future phase after all tests are migrated // ======================================== /** @deprecated Use SemanticSelectors.button(page, name) or getButton() */ MuiButtonLabel: 'span[class^="MuiButton-label"],button[class*="MuiButton-root"]', /** @deprecated Use SemanticSelectors.button(page, name) with filter */ ... (clipped 172 lines) e2e-tests/playwright/support/page-objects/page-obj.ts [14-276] export const HOME_PAGE_COMPONENTS = { // Legacy selectors - maintained for backward compatibility /** @deprecated Use SemanticSelectors.region() with appropriate filter */ MuiAccordion: 'div[class*="MuiAccordion-root-"]', /** @deprecated Use SemanticSelectors.region() or article with appropriate filter */ MuiCard: 'div[class*="MuiCard-root-"]', // Semantic methods - preferred /** * Get accordion/expandable section by heading text ... (clipped 253 lines) Solution Walkthrough: Before: // e2e-tests/playwright/support/page-objects/global-obj.ts export const UI_HELPER_ELEMENTS = { // LEGACY SELECTORS /** @deprecated Use SemanticSelectors.button(page, name) or getButton() */ MuiButtonLabel: 'span[class^="MuiButton-label"],button[class*="MuiButton-root"]', // ... other deprecated selectors // NEW SEMANTIC METHODS getButton: (page: Page, name: string | RegExp): Locator => SemanticSelectors.button(page, name), // ... other new methods }; After: // .eslintrc.js (conceptual) module.exports = { // ... rules: { 'no-restricted-syntax': [ 'error', { selector: 'MemberExpression[object.name="UI_HELPER_ELEMENTS"][property.name="MuiButtonLabel"]', message: 'UI_HELPER_ELEMENTS.MuiButtonLabel is deprecated. Use the new getButton() method instead.', }, // ... other rules for all deprecated selectors ], }, }; // In a test file, this would now raise a linting error: // ERROR: UI_HELPER_ELEMENTS.MuiButtonLabel is deprecated. page.locator(UI_HELPER_ELEMENTS.MuiButtonLabel); Suggestion importance[1-10]: 8 __ Why: This is a high-impact strategic suggestion that addresses the long-term maintainability and success of the PR's refactoring by proposing a concrete enforcement mechanism (ESLint rule) to ensure adoption of the new pattern.	Medium
Possible issue	Fix incorrect accordion locator logic Fix the getClusterAccordion selector by first locating the accordion element and then finding the button within it, as the original filter logic is incorrect. e2e-tests/playwright/support/page-objects/page-obj.ts [100-105] getClusterAccordion: (page: Page, clusterName?: string | RegExp): Locator => { if (clusterName) { return page.getByRole('button', { name: clusterName }); } - return page.getByRole('button').filter({ has: page.locator('[class*="MuiAccordion"]') }).first(); + // Find the first accordion element, then get the button inside it. + return page.locator('[class*="MuiAccordion-root"]').first().getByRole('button'); }, Apply / Chat Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a logical flaw in the Playwright selector for accordions, where the filter logic was inverted, and provides a working alternative that prevents the selector from failing.	Medium
General	Remove redundant explicit wait helpers Remove the redundant forVisible and forHidden explicit wait helpers and instead use Playwright's built-in auto-waiting assertions like expect(locator).toBeVisible(). e2e-tests/playwright/support/selectors/semantic-selectors.ts [429-443] export class WaitStrategies { /** - * Wait for element to be visible (auto-waiting assertion) - * Preferred over waitForTimeout + * Wait for network to be idle + * @deprecated Prefer web-first assertions like `expect(locator).toBeVisible()` over explicit waits. + * This class may be removed in a future update. */ - static async forVisible(locator: Locator, timeout?: number): Promise<void> { - await locator.waitFor({ state: 'visible', timeout }); - } - - /** - * Wait for element to be hidden - */ - static async forHidden(locator: Locator, timeout?: number): Promise<void> { - await locator.waitFor({ state: 'hidden', timeout }); + static async forNetworkIdle(page: Page): Promise<void> { + await page.waitForLoadState('networkidle'); } ... [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out that the explicit wait helpers are redundant with Playwright's preferred expect assertions, and removing them aligns with best practices and simplifies the codebase.	Low
Update

[gustavolira]

/review

[rhdh-qodo-merge]

Persistent review updated to latest commit 0ddad92

[github-actions]

The image is available at:

• quay.io/rhdh-community/rhdh:pr-3837
• quay.io/rhdh-community/rhdh:pr-3837-0ddad92d

[gustavolira]

/review

[rhdh-qodo-merge]

Persistent review updated to latest commit ce0cf78

[github-actions]

The image is available at:

• quay.io/rhdh-community/rhdh:pr-3837
• quay.io/rhdh-community/rhdh:pr-3837-18df22d7

[github-actions]

The image is available at:

• quay.io/rhdh-community/rhdh:pr-3837
• quay.io/rhdh-community/rhdh:pr-3837-eeadff4a

/test e2e-ocp-helm

[github-actions]

🚫 Image Push Skipped.

The container image push was skipped because the build was skipped (either due to [skip-build] tag or no relevant changes with existing image)

/test e2e-ocp-helm

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

The image is available at:

• quay.io/rhdh-community/rhdh:pr-3837
• quay.io/rhdh-community/rhdh:pr-3837-9f2827d1

/test e2e-ocp-helm