feat(cypress-commands): add findToolbarButtonByText query

packages/cypress-commands/src/queries.ts

@@ -1,3 +1,7 @@
+interface FindToolbarButtonByTextOptions {
+  queryShadowButton?: boolean;
+}
+
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace Cypress {
@@ -23,7 +27,24 @@ declare global {
        * @example cy.get('[ui5-tab-container]').findUi5TabOpenPopoverButtonByText('Tab 1.1');
        * @param {string} text The text of the sub-tab that should be queried.
        */
-      findUi5TabOpenPopoverButtonByText(text: string, options?: Partial<ClickOptions>): Chainable<Element>;
+      findUi5TabOpenPopoverButtonByText(text: string): Chainable<Element>;
+
+      /**
+       * Returns the element that represents the `ui5-toolbar-button`.
+       * When `options.queryShadowButton` is `true`, the internal `button` element is returned, otherwise the `ui5-button` element.
+       *
+       * __Note:__ This query can either be chained to a `ui5-toolbar` or not be chained at all.
+       *
+       * __Note:__ The `text` next needs to be unique in the respective scope.
+       *
+       * @example cy.findToolbarButtonByText("Button Text")
+       * @example cy.get('[ui5-toolbar]').findToolbarButtonByText("Button Text")
+       *
+       * @param {string} text - The text of the button to search for. This text should be unique within the toolbar to ensure a single button is returned.
+       * @param {FindToolbarButtonByTextOptions} [options] - An optional object containing configuration options for the query.
+       * @param {boolean} [options.queryShadowButton=false] - If set to `true`, the internal `button` element will be returned instead of the `ui5-button` element.
+       */
+      findToolbarButtonByText(text: string, options?: FindToolbarButtonByTextOptions): Chainable<Element>;
       // private
       /**
        * Returns the internal input element inside the shadow-root.
@@ -36,6 +57,41 @@ declare global {
   }
 }
 
+Cypress.Commands.addQuery('findToolbarButtonByText', function (text, options) {
+  return (subject) => {
+    if (subject !== undefined && !subject?.[0]?.hasAttribute('ui5-toolbar')) {
+      const err = `findToolbarButtonByText() needs to be chained to a \`ui5-toolbar\`, or not be chained at all.`;
+      throw new TypeError(err);
+    }
+    const container = subject ? [subject[0]] : document.querySelectorAll('[ui5-toolbar]');
+
+    const toolbarBtns: HTMLElement[] = [];
+    container.forEach((el) => {
+      if (el) {
+        const toolbarDom = el.getDomRef();
+        const buttons = Cypress.$(toolbarDom).find('[ui5-button]');
+        const matchingButtons = buttons.filter(function () {
+          return Cypress.$(this).text() === text;
+        });
+
+        toolbarBtns.push(...matchingButtons);
+      }
+    });
+
+    if (toolbarBtns.length > 1) {
+      const err = `Multiple ui5-toolbar-button elements with the same text ("${text}") were found.`;
+      throw new TypeError(err);
+    }
+
+    let toolbarBtn = toolbarBtns[0];
+    if (options?.queryShadowButton) {
+      toolbarBtn = toolbarBtn.shadowRoot!.querySelector('button')!;
+    }
+
+    return Cypress.$(toolbarBtn);
+  };
+});
+
 Cypress.Commands.addQuery('findShadowInput', function () {
   const getShadow = cy.now('shadow');
   const getInput = cy.now('find', 'input');

packages/cypress-commands/test/UI5WebComponentsChild.cy.tsx

@@ -16,7 +16,9 @@ import {
   Switch,
   Tab,
   TabContainer,
-  TextArea
+  TextArea,
+  Toolbar,
+  ToolbarButton
 } from '@ui5/webcomponents-react';
 
 describe('UI5 Web Components - Child Commands', () => {
@@ -260,4 +262,26 @@ describe('UI5 Web Components - Child Commands', () => {
       cy.wait(200);
     });
   });
+
+  it('findToolbarButtonByText', () => {
+    cy.mount(
+      <>
+        <Toolbar>
+          <ToolbarButton text="TBB1" />
+          <ToolbarButton text="TBB2" />
+        </Toolbar>
+        <Toolbar>
+          <ToolbarButton text="TBB3" />
+        </Toolbar>
+        <Toolbar>
+          <ToolbarButton text="TBB4" style={{ display: 'none' }} />
+        </Toolbar>
+      </>
+    );
+
+    cy.findToolbarButtonByText('TBB1').should('be.visible');
+    cy.findToolbarButtonByText('TBB2').should('be.visible');
+    cy.findToolbarButtonByText('TBB3').should('be.visible');
+    cy.findToolbarButtonByText('TBB3').should('exist').not('be.visible');
+  });
 });