browsertime 26.3.1 → 27.0.0

package/lib/core/engine/command/select.js

@@ -1,4 +1,7 @@
+import webdriver from 'selenium-webdriver';
 import { getLogger } from '@sitespeed.io/log';
+import { executeCommand } from './commandHelper.js';
+import { parseSelector } from './selectorParser.js';
 const log = getLogger('browsertime.command.select');
 
 /**
@@ -8,17 +11,100 @@ const log = getLogger('browsertime.command.select');
  * @hideconstructor
  */
 export class Select {
-  constructor(browser) {
+  constructor(browser, options) {
     /**
      * @private
      */
     this.browser = browser;
+    /**
+     * @private
+     */
+    this.options = options;
+  }
+
+  /**
+   * @private
+   */
+  async _waitForElement(driver, locator) {
+    const timeout = this.options?.timeouts?.elementWait ?? 0;
+    if (timeout > 0) {
+      await driver.wait(webdriver.until.elementLocated(locator), timeout);
+    }
+  }
+
+  /**
+   * Selects an option in a select element using a unified selector string and a value.
+   * Supports CSS selectors (default), and prefix-based strategies:
+   * 'id:mySelect', 'name:country', 'class:dropdown'.
+   *
+   * @async
+   * @param {string} selector - The selector string for the select element.
+   * @param {string} value - The value of the option to select.
+   * @returns {Promise<void>} A promise that resolves when the option is selected.
+   * @throws {Error} Throws an error if the select element is not found.
+   */
+  async run(selector, value) {
+    const { locator, description } = parseSelector(selector);
+    return executeCommand(
+      log,
+      'Could not select value for %s',
+      description,
+      async () => {
+        const driver = this.browser.getDriver();
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        await driver.executeScript(
+          `arguments[0].value = '${value}'; arguments[0].dispatchEvent(new Event('change'));`,
+          element
+        );
+      },
+      this.browser
+    );
+  }
+
+  /**
+   * Selects an option in a select element by its visible text using a unified selector string.
+   *
+   * @async
+   * @param {string} selector - The selector string for the select element.
+   * @param {string} text - The visible text of the option to select.
+   * @returns {Promise<void>} A promise that resolves when the option is selected.
+   * @throws {Error} Throws an error if the select element or option is not found.
+   */
+  async runByText(selector, text) {
+    const { locator, description } = parseSelector(selector);
+    return executeCommand(
+      log,
+      'Could not select option by text for %s',
+      description,
+      async () => {
+        const driver = this.browser.getDriver();
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        await driver.executeScript(
+          `const select = arguments[0];
+           const text = arguments[1];
+           for (const option of select.options) {
+             if (option.text === text || option.textContent.trim() === text) {
+               select.value = option.value;
+               select.dispatchEvent(new Event('change'));
+               return;
+             }
+           }
+           throw new Error('Option with text "' + text + '" not found');`,
+          element,
+          text
+        );
+      },
+      this.browser
+    );
   }
 
   /**
    * Selects an option in a `<select>` element by its ID and the value of the option.
    *
    * @async
+   * @private
    * @param {string} selectId - The ID of the `<select>` element.
    * @param {string} value - The value of the option to select.
    * @returns {Promise<void>} A promise that resolves when the option is selected.
@@ -39,6 +125,7 @@ export class Select {
    * Selects an option in a `<select>` element by its name and the value of the option.
    *
    * @async
+   * @private
    * @param {string} selectName - The name of the `<select>` element.
    * @param {string} value - The value of the option to select.
    * @returns {Promise<void>} A promise that resolves when the option is selected.
@@ -61,6 +148,7 @@ export class Select {
    * Selects an option in a `<select>` element by its ID and the index of the option.
    *
    * @async
+   * @private
    * @param {string} selectId - The ID of the `<select>` element.
    * @param {number} index - The index of the option to select.
    * @returns {Promise<void>} A promise that resolves when the option is selected.
@@ -85,6 +173,7 @@ export class Select {
    * Selects an option in a `<select>` element by its name and the index of the option.
    *
    * @async
+   * @private
    * @param {string} selectName - The name of the `<select>` element.
    * @param {number} index - The index of the option to select.
    * @returns {Promise<void>} A promise that resolves when the option is selected.
@@ -109,6 +198,7 @@ export class Select {
    * Deselects all options in a `<select>` element by its ID.
    *
    * @async
+   * @private
    * @param {string} selectId - The ID of the `<select>` element.
    * @returns {Promise<void>} A promise that resolves when all options are deselected.
    * @throws {Error} Throws an error if the `<select>` element is not found.
@@ -119,9 +209,9 @@ export class Select {
       const value = await this.browser.runScript(script, 'CUSTOM');
       return value;
     } catch (error) {
-      log.error('Could not deleselect by select id %s', selectId);
+      log.error('Could not deselect by select id %s', selectId);
       log.verbose(error);
-      throw new Error(`Could not deleselect by select id  ${selectId}`);
+      throw new Error(`Could not deselect by select id ${selectId}`);
     }
   }
 
@@ -129,6 +219,7 @@ export class Select {
    * Retrieves all option values in a `<select>` element by its ID.
    *
    * @async
+   * @private
    * @param {string} selectId - The ID of the `<select>` element.
    * @returns {Promise<string[]>} A promise that resolves with an array of the values of the options.
    * @throws {Error} Throws an error if the `<select>` element is not found.
@@ -156,6 +247,7 @@ export class Select {
    * Retrieves the value of the selected option in a `<select>` element by its ID.
    *
    * @async
+   * @private
    * @param {string} selectId - The ID of the `<select>` element.
    * @returns {Promise<string>} A promise that resolves with the value of the selected option.
    * @throws {Error} Throws an error if the `<select>` element is not found.

package/lib/core/engine/command/selectorParser.js

@@ -0,0 +1,58 @@
+import { By } from 'selenium-webdriver';
+
+/**
+ * Parses a selector string into a Selenium By locator.
+ * Supports prefix-based strategies:
+ * - 'id:value' -> By.id('value')
+ * - 'xpath:expression' -> By.xpath('expression')
+ * - 'name:value' -> By.name('value')
+ * - 'text:value' -> By.xpath('//*[normalize-space(text())="value"]')
+ * - 'link:value' -> By.xpath('//a[text()="value"]')
+ * - 'class:value' -> By.className('value')
+ * - No prefix -> By.css(selector) (CSS selector is the default)
+ *
+ * @param {string} selector - The selector string to parse.
+ * @returns {{ locator: By, description: string }} The parsed locator and a human-readable description.
+ */
+export function parseSelector(selector) {
+  const colonIndex = selector.indexOf(':');
+  if (colonIndex > 0) {
+    const prefix = selector.slice(0, colonIndex).toLowerCase();
+    const value = selector.slice(colonIndex + 1);
+    switch (prefix) {
+      case 'id': {
+        return { locator: By.id(value), description: `id ${value}` };
+      }
+      case 'xpath': {
+        return { locator: By.xpath(value), description: `xpath ${value}` };
+      }
+      case 'name': {
+        return { locator: By.name(value), description: `name ${value}` };
+      }
+      case 'text': {
+        return {
+          locator: By.xpath(`//*[normalize-space(text())='${value}']`),
+          description: `text ${value}`
+        };
+      }
+      case 'link': {
+        return {
+          locator: By.xpath(`//a[text()='${value}']`),
+          description: `link text ${value}`
+        };
+      }
+      case 'class': {
+        return {
+          locator: By.className(value),
+          description: `class ${value}`
+        };
+      }
+      default: {
+        // Unknown prefix — treat entire string as CSS selector
+        return { locator: By.css(selector), description: `css ${selector}` };
+      }
+    }
+  }
+  // No prefix — CSS selector
+  return { locator: By.css(selector), description: `css ${selector}` };
+}

package/lib/core/engine/command/set.js

@@ -1,4 +1,7 @@
+import webdriver from 'selenium-webdriver';
 import { getLogger } from '@sitespeed.io/log';
+import { executeCommand } from './commandHelper.js';
+import { parseSelector } from './selectorParser.js';
 const log = getLogger('browsertime.command.set');
 
 /**
@@ -8,17 +11,63 @@ const log = getLogger('browsertime.command.set');
  * @hideconstructor
  */
 export class Set {
-  constructor(browser) {
+  constructor(browser, options) {
     /**
      * @private
      */
     this.browser = browser;
+    /**
+     * @private
+     */
+    this.options = options;
+  }
+
+  /**
+   * @private
+   */
+  async _waitForElement(driver, locator) {
+    const timeout = this.options?.timeouts?.elementWait ?? 0;
+    if (timeout > 0) {
+      await driver.wait(webdriver.until.elementLocated(locator), timeout);
+    }
+  }
+
+  /**
+   * Sets a property on an element using a unified selector string.
+   * Supports CSS selectors (default), and prefix-based strategies:
+   * 'id:myId', 'xpath://input', 'name:field', 'class:input-field'.
+   *
+   * @async
+   * @param {string} selector - The selector string for the element.
+   * @param {string} value - The value to set.
+   * @param {string} [property='value'] - The property to set: 'value', 'innerText', or 'innerHTML'.
+   * @returns {Promise<void>} A promise that resolves when the property is set.
+   * @throws {Error} Throws an error if the element is not found.
+   */
+  async run(selector, value, property = 'value') {
+    const { locator, description } = parseSelector(selector);
+    return executeCommand(
+      log,
+      `Could not set ${property} on %s`,
+      description,
+      async () => {
+        const driver = this.browser.getDriver();
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        await driver.executeScript(
+          `arguments[0].${property} = '${value}';`,
+          element
+        );
+      },
+      this.browser
+    );
   }
 
   /**
    * Sets the innerHTML of an element using a CSS selector.
    *
    * @async
+   * @private
    * @param {string} html - The HTML string to set as innerHTML.
    * @param {string} selector - The CSS selector of the element.
    * @returns {Promise<void>} A promise that resolves when the innerHTML is set.
@@ -41,6 +90,7 @@ export class Set {
    * Sets the innerHTML of an element using its ID.
    *
    * @async
+   * @private
    * @param {string} html - The HTML string to set as innerHTML.
    * @param {string} id - The ID of the element.
    * @returns {Promise<void>} A promise that resolves when the innerHTML is set.
@@ -61,6 +111,7 @@ export class Set {
    * Sets the innerText of an element using a CSS selector.
    *
    * @async
+   * @private
    * @param {string} text - The text to set as innerText.
    * @param {string} selector - The CSS selector of the element.
    * @returns {Promise<void>} A promise that resolves when the innerText is set.
@@ -83,6 +134,7 @@ export class Set {
    * Sets the innerText of an element using its ID.
    *
    * @async
+   * @private
    * @param {string} text - The text to set as innerText.
    * @param {string} id - The ID of the element.
    * @returns {Promise<void>} A promise that resolves when the innerText is set.
@@ -103,6 +155,7 @@ export class Set {
    * Sets the value of an element using a CSS selector.
    *
    * @async
+   * @private
    * @param {string} value - The value to set on the element.
    * @param {string} selector - The CSS selector of the element.
    * @returns {Promise<void>} A promise that resolves when the value is set.
@@ -123,6 +176,7 @@ export class Set {
    * Sets the value of an element using its ID.
    *
    * @async
+   * @private
    * @param {string} value - The value to set on the element.
    * @param {string} id - The ID of the element.
    * @returns {Promise<void>} A promise that resolves when the value is set.

package/lib/core/engine/command/wait.js

@@ -1,5 +1,7 @@
 import webdriver from 'selenium-webdriver';
 import { getLogger } from '@sitespeed.io/log';
+import { executeCommand } from './commandHelper.js';
+import { parseSelector } from './selectorParser.js';
 const log = getLogger('browsertime.command.wait');
 const delay = ms => new Promise(res => setTimeout(res, ms));
 
@@ -25,6 +27,7 @@ export class Wait {
    * Waits for an element with a specific ID to be located within a maximum time.
    *
    * @async
+   * @private
    * @param {string} id - The ID of the element to wait for.
    * @param {number} maxTime - Maximum time to wait in milliseconds.
    * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
@@ -50,6 +53,7 @@ export class Wait {
    * Waits for an element with a specific ID to be located and visible within a maximum time.
    *
    * @async
+   * @private
    * @param {string} id - The ID of the element to wait for.
    * @param {number} maxTime - Maximum time to wait in milliseconds.
    * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
@@ -59,7 +63,6 @@ export class Wait {
     const driver = this.browser.getDriver();
     await this.byId(id, maxTime);
     try {
-      driver.findElement;
       await driver.wait(
         webdriver.until.elementIsVisible(
           driver.findElement(webdriver.By.id(id))
@@ -77,6 +80,7 @@ export class Wait {
    * Waits for an element located by XPath to appear within a maximum time.
    *
    * @async
+   * @private
    * @param {string} xpath - The XPath of the element to wait for.
    * @param {number} maxTime - Maximum time to wait in milliseconds.
    * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
@@ -104,6 +108,7 @@ export class Wait {
    * Waits for an element located by XPath to appear and visible within a maximum time.
    *
    * @async
+   * @private
    * @param {string} xpath - The XPath of the element to wait for.
    * @param {number} maxTime - Maximum time to wait in milliseconds.
    * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
@@ -113,7 +118,6 @@ export class Wait {
     const driver = this.browser.getDriver();
     await this.byXpath(xpath, maxTime);
     try {
-      driver.findElement;
       await driver.wait(
         webdriver.until.elementIsVisible(
           driver.findElement(webdriver.By.xpath(xpath))
@@ -133,6 +137,7 @@ export class Wait {
    * Waits for an element located by a CSS selector to appear within a maximum time.
    *
    * @async
+   * @private
    * @param {string} selector - The CSS selector of the element to wait for.
    * @param {number} maxTime - Maximum time to wait in milliseconds.
    * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
@@ -164,6 +169,7 @@ export class Wait {
    * Waits for an element located by a CSS selector to be visible within a maximum time.
    *
    * @async
+   * @private
    * @param {string} selector - The CSS selector of the element to wait for.
    * @param {number} maxTime - Maximum time to wait in milliseconds.
    * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
@@ -214,6 +220,39 @@ export class Wait {
     return this.browser.extraWait(this.pageCompleteCheck);
   }
 
+  /**
+   * Waits for an element using a unified selector string to appear within a maximum time.
+   * Supports CSS selectors (default), and prefix-based strategies:
+   * 'id:myId', 'xpath://div', 'name:field', 'class:loaded'.
+   *
+   * @async
+   * @param {string} selector - The selector string. CSS by default, or use a prefix.
+   * @param {Object} [options] - Options for waiting.
+   * @param {number} [options.timeout=6000] - Maximum time to wait in milliseconds.
+   * @param {boolean} [options.visible=false] - If true, waits for the element to be visible, not just present.
+   * @returns {Promise<void>} A promise that resolves when the element is found.
+   * @throws {Error} Throws an error if the element is not found within the timeout.
+   */
+  async run(selector, options = {}) {
+    const timeout = options.timeout ?? 6000;
+    const visible = options.visible ?? false;
+    const { locator, description } = parseSelector(selector);
+    return executeCommand(
+      log,
+      'Element %s was not located in ' + timeout + ' ms',
+      description,
+      async () => {
+        const driver = this.browser.getDriver();
+        await driver.wait(webdriver.until.elementLocated(locator), timeout);
+        if (visible) {
+          const element = await driver.findElement(locator);
+          await driver.wait(webdriver.until.elementIsVisible(element), timeout);
+        }
+      },
+      this.browser
+    );
+  }
+
   /**
    * Waits for a JavaScript condition to return a truthy value within a maximum time.
    *