feat(queries): add "When I find headings by text" and "When I find heading by text"

cypress/e2e/example/example.feature

@@ -4,6 +4,14 @@ Feature: Example
     Then I see document title "Example Domain"
       And I see document title contains "Example"
 
+  Scenario: See heading
+    Given I visit "http://example.com/"
+    Then I see heading "Example Domain"
+    When I find headings by text "Example Domain"
+    Then I count 1 element
+    When I find heading by text "Example Domain"
+    Then I count 1 element
+
   Scenario: See and not see text
     Given I visit "http://example.com/"
     Then I see text "Example Domain"

src/assertions/button.ts

@@ -1,5 +1,8 @@
 import { Then } from '@badeball/cypress-cucumber-preprocessor';
 
+import { When_I_find_button_by_text } from '../queries';
+import { getCypressElement } from '../utils';
+
 /**
  * Then I see button:
  *
@@ -22,7 +25,8 @@ import { Then } from '@badeball/cypress-cucumber-preprocessor';
  * - {@link Then_I_see_text | Then I see text}
  */
 export function Then_I_see_button(text: string) {
-  cy.contains('button:visible', text).should('exist');
+  When_I_find_button_by_text(text);
+  getCypressElement().should('exist');
 }
 
 Then('I see button {string}', Then_I_see_button);

src/assertions/heading.ts

@@ -1,5 +1,8 @@
 import { Then } from '@badeball/cypress-cucumber-preprocessor';
 
+import { When_I_find_heading_by_text } from '../queries';
+import { getCypressElement } from '../utils';
+
 /**
  * Then I see heading:
  *
@@ -22,10 +25,8 @@ import { Then } from '@badeball/cypress-cucumber-preprocessor';
  * - {@link Then_I_see_text | Then I see text}
  */
 export function Then_I_see_heading(text: string) {
-  const selector = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
-    .map((tag) => `${tag}:contains('${text}'):visible`)
-    .join(',');
-  cy.get(selector).should('exist');
+  When_I_find_heading_by_text(text);
+  getCypressElement().should('exist');
 }
 
 Then('I see heading {string}', Then_I_see_heading);

src/queries/heading.ts

@@ -0,0 +1,74 @@
+import { When } from '@badeball/cypress-cucumber-preprocessor';
+
+import { getCypressElement, setCypressElement } from '../utils';
+
+/**
+ * When I find headings by text:
+ *
+ * ```gherkin
+ * When I find headings by text {string}
+ * ```
+ *
+ * @example
+ *
+ * ```gherkin
+ * When I find headings by text "Heading"
+ * ```
+ *
+ * @remarks
+ *
+ * This precedes steps like {@link When_I_click | "When I click"}. For example:
+ *
+ * ```gherkin
+ * When I find headings by text "Heading"
+ *   And I get 1st element
+ *   And I click
+ * ```
+ *
+ * @see
+ *
+ * - {@link When_I_find_heading_by_text | When I find heading by text}
+ */
+export function When_I_find_headings_by_text(text: string) {
+  const selector = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
+    .map((tag) => `${tag}:contains('${text}'):visible`)
+    .join(',');
+  setCypressElement(cy.get(selector));
+}
+
+When('I find headings by text {string}', When_I_find_headings_by_text);
+
+/**
+ * When I find heading by text:
+ *
+ * ```gherkin
+ * When I find heading by text {string}
+ * ```
+ *
+ * Finds first heading element that matches text.
+ *
+ * @example
+ *
+ * ```gherkin
+ * When I find heading by text "Heading"
+ * ```
+ *
+ * @remarks
+ *
+ * This precedes steps like {@link When_I_click | "When I click"}. For example:
+ *
+ * ```gherkin
+ * When I find heading by text "heading"
+ *   And I click
+ * ```
+ *
+ * @see
+ *
+ * - {@link When_I_find_headings_by_text | When I find headings by text}
+ */
+export function When_I_find_heading_by_text(text: string) {
+  When_I_find_headings_by_text(text);
+  setCypressElement(getCypressElement().first());
+}
+
+When('I find heading by text {string}', When_I_find_heading_by_text);

src/queries/index.ts

@@ -7,6 +7,7 @@ export * from './find';
 export * from './focused';
 export * from './form';
 export * from './get';
+export * from './heading';
 export * from './input';
 export * from './label';
 export * from './link';