From 74c24bdd94950329c32eff95679474b6a071d81b Mon Sep 17 00:00:00 2001
From: Mark <mark@remarkablemark.org>
Date: Sat, 30 Nov 2024 13:14:43 -0500
Subject: [PATCH] feat(queries): add "When I find elements by title"

---
 src/queries/title.ts | 88 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 79 insertions(+), 9 deletions(-)

diff --git a/src/queries/title.ts b/src/queries/title.ts
index 77d87476d..60a61e10a 100644
--- a/src/queries/title.ts
+++ b/src/queries/title.ts
@@ -1,6 +1,61 @@
-import { When } from '@badeball/cypress-cucumber-preprocessor';
+import { DataTable, When } from '@badeball/cypress-cucumber-preprocessor';
 
-import { setCypressElement } from '../utils';
+import { getCypressElement, getOptions, setCypressElement } from '../utils';
+
+/**
+ * When I find elements by title:
+ *
+ * ```gherkin
+ * When I find elements by title {string}
+ * ```
+ *
+ * Finds elements with a matching `title` attribute. This will also find `title` elements within SVGs.
+ *
+ * @example
+ *
+ * ```gherkin
+ * When I find elements by title "Title"
+ * ```
+ *
+ * With [options](https://docs.cypress.io/api/commands/get#Arguments):
+ *
+ * ```gherkin
+ * When I find elements by title "Title"
+ *   | log | true |
+ *   | timeout | 4000 |
+ *   | withinSubject | null |
+ *   | includeShadowDom | false |
+ *   | pseudoSelector | visible |
+ * ```
+ *
+ * @remarks
+ *
+ * This precedes steps like {@link When_I_click | "When I click"}. For example:
+ *
+ * ```gherkin
+ * When I find elements by title "Close"
+ *   And I get 1st element
+ *   And I click
+ * ```
+ *
+ * Inspired by Testing Library's [ByTitle](https://testing-library.com/docs/queries/bytitle).
+ *
+ * @see
+ *
+ * - {@link When_I_find_element_by_title | When I find element by title}
+ */
+export function When_I_find_elements_by_title(
+  title: string,
+  options?: DataTable,
+) {
+  const selectors = [
+    `[title=${JSON.stringify(title)}]`,
+    `svg title:contains(${JSON.stringify(title)})`,
+  ];
+  setCypressElement(cy.get(selectors.join(','), getOptions(options)));
+}
+
+When('I find elements by title {string}', When_I_find_elements_by_title);
 
 /**
  * When I find element by title:
@@ -14,7 +69,18 @@ import { setCypressElement } from '../utils';
  * @example
  *
  * ```gherkin
- * When I find element by title "Close"
+ * When I find element by title "Title"
+ * ```
+ *
+ * With [options](https://docs.cypress.io/api/commands/get#Arguments):
+ *
+ * ```gherkin
+ * When I find element by title "Title"
+ *   | log | true |
+ *   | timeout | 4000 |
+ *   | withinSubject | null |
+ *   | includeShadowDom | false |
+ *   | pseudoSelector | visible |
  * ```
  *
  * @remarks
@@ -27,13 +93,17 @@ import { setCypressElement } from '../utils';
  * ```
  *
  * Inspired by Testing Library's [ByTitle](https://testing-library.com/docs/queries/bytitle).
+ *
+ * @see
+ *
+ * - {@link When_I_find_elements_by_title | When I find elements by title}
  */
-export function When_I_find_element_by_title(title: string) {
-  const selector = [
-    `svg title:contains(${JSON.stringify(title)})`,
-    `[title=${JSON.stringify(title)}]`,
-  ].join(',');
-  setCypressElement(cy.get(selector).first());
+export function When_I_find_element_by_title(
+  title: string,
+  options?: DataTable,
+) {
+  When_I_find_elements_by_title(title, options);
+  setCypressElement(getCypressElement().first());
 }
 
 When('I find element by title {string}', When_I_find_element_by_title);