@checksum-ai/runtime 1.1.26 → 1.1.27

package/README.md

@@ -2,7 +2,7 @@
 
 ### Quick Start
 
-1. Install the package using `npm install -D @checksum-ai/runtime` or `yarn add @checksum-ai/runtime -D`.
+1. Install the package using `npm install -D checksumai` or `yarn add checksumai -D`.
 2. Navigate to the directory where you want to initialize the Checksum tests folder and run `npx checksumai init`.
 3. In the newly created "checksum" folder
    1. Edit `checksum.config.ts` and add the necessary configurations, including your apiKey, application baseURL, environment info, etc.
@@ -222,6 +222,20 @@ interface ChecksumPage extends Page {
    * When required to login mid-test, use reauthenticate with the user's role. Note: It is not possible to change environments during a single test run.
    */
   reauthenticate: (role: string) => Promise<void>;
+
+   /**
+   * When required to handle actions that involve browser Native Dialogs that are part of the WebAPI,
+   * use waitForDialog to listen for any dialog events, and handle them accordingly inside the handler.
+   * Note: waitForDialog can only work within a checksumAI.withDialog call which initiates the dialog listener. 
+   * 
+   * await checksumAI.withDialog("delete item and confirm", () => {
+   *  await page.locator('.delete').click();
+   *  await page.waitForDialog().then((confirm) => {
+   *      confirm.accept();
+   *  });
+   * });
+   */
+  waitForDialog: (timeout?: number) => Promise<Dialog>;
 }
 
 ```
@@ -229,6 +243,8 @@ interface ChecksumPage extends Page {
 ## ChecksumLocator API
 
 ChecksumLocator extends the existing Playwright Locator, adding the following functionality:
+* canvasClick
+* compoundSelection
 
 ```js
 interface ChecksumLocator extends Locator {
@@ -240,6 +256,68 @@ interface ChecksumLocator extends Locator {
    * await page.locator('canvas').canvasClick('graph-point-1', 1); // clicking on the 2nd largest
    */
   canvasClick: (canvasText: string, rectSizeIndex?: number) => Promise<void>;
+
+  /**
+   * Will create a compound selection that selects elements by grouping multiple locators as anchors
+   * and finding the target elements, if specified, from their common root parent.
+   * If no target is provided, the compound selection will return a locator to the common parents that were calculated from the anchors.
+   *
+   * **Usage example**
+   *
+   * ```js
+   * await page.compoundSelection(
+   *  (base) => [base.getByText("<selector to first anchor>""), page.locator("selector to second anchor"), "<text content of third anchor>"],
+   *  (base) => base.locator("<relative selector to target element>")
+   * ]).first().click();
+   * ```
+   *
+   * @param anchors Method that returns array of locators and/or text context, to group and calculate the common parent from.
+   *                The method receives the base locator as an argument, which is the relative locator or page that the compound selection is called on.
+   *                The method should return an array of locators or strings that point at the anchor elements.
+   * @param target [optional] Method that returns the relative locator or string content that will point at the target element from the common parent
+   *               that was calculated from the anchors.
+   *               If no target is provided, the compound selection will return a locator pointing at the common parents.
+   * @returns Locator to the common parent(s) or the target element(s) if specified.
+   */
+  compoundSelection(
+    anchors: (base: Locator) => Array<Locator | string>,
+    target?: (base: Locator) => Locator | string
+  ): ChecksumLocator;
+
+  /**
+   * Will create a compound selection that selects elements by grouping multiple locators as anchors
+   * and finding the target elements, if specified, from their common root parent.
+   * If no target is provided, the compound selection will return a locator to the common parents that were calculated from the anchors.
+   *
+   * **Usage example**
+   *
+   * ```js
+   * await page.compoundSelection({
+   *    anchors: (base) => [base.getByText("<selector to first anchor>""), page.locator("selector to second anchor"), "<text content of third anchor>"],
+   *    target?: (base) => base.locator("<relative selector to target element>")
+   * }).first().click();
+   * ```
+   * @param selection
+   * @returns Locator to the common parent(s) or the target element(s) if specified.
+   */
+  compoundSelection(selection: {
+    /**
+     * Method that returns array of locators and/or text context, to group and calculate the common parent from.
+     * The method receives the base locator as an argument, which is the relative locator or page that the compound selection is called on.
+     * The method should return an array of locators or strings that point at the anchor elements.
+     *
+     * @param base Base locator that the compound selection is called on.
+     */
+    anchors: (base: Locator) => Array<Locator | string>;
+    /**
+     * Method that returns the relative locator or string content that will point at the target element from the common parent
+     * that was calculated from the anchors.
+     * If the target is null, the compound selection will return a locator pointing at the common parents.
+     *
+     * @param base Base locator that the compound selection is called on.
+     */
+    target?: (base: Locator) => Locator | string;
+  }): ChecksumLocator;
 }
 ```