@tstdl/base 0.87.2 → 0.87.3

package/browser/document-controller.d.ts

@@ -1,9 +1,9 @@
 import type { ElementHandle, Frame, FrameLocator, Page } from 'playwright';
 import type { BrowserContextController } from './browser-context-controller.js';
-import type { Delay } from './element-controller.js';
 import { ElementController } from './element-controller.js';
 import type { FrameController, FrameControllerOptions } from './frame-controller.js';
 import { LocatorController } from './locator-controller.js';
+import type { Delay } from './types.js';
 export type DocumentControllerOptions = {
     defaultActionDelay?: Delay;
     defaultTypeDelay?: Delay;

package/browser/element-controller.d.ts

@@ -1,10 +1,6 @@
 import type { ElementHandle, Locator } from 'playwright';
 import type { Merge, NonUndefinable, TypedOmit } from '../types.js';
-import type { ValueOrProvider } from '../utils/value-or-provider.js';
-export type Delay = ValueOrProvider<number>;
-export type ActionDelayOptions = {
-    actionDelay?: Delay;
-};
+import type { ActionDelayOptions, Delay, TimeoutOptions } from './types.js';
 export type TypeDelayOptions = {
     typeDelay?: Delay;
 };
@@ -23,6 +19,12 @@ export type Filter = {
     hasText?: string | RegExp;
     hasNotText?: string | RegExp;
 };
+export type BoundingBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 export declare class ElementController<T extends Locator | ElementHandle = Locator | ElementHandle> implements Pick<Locator, Methods> {
     readonly locatorOrHandle: T;
     readonly options: ElementControllerOptions;
@@ -35,6 +37,12 @@ export declare class ElementController<T extends Locator | ElementHandle = Locat
      * @param elementController
      */
     and(elementController: ElementController): ElementController<Locator>;
+    /**
+     * Get an controller with elements contained in this and the provided controller.
+     * Requires locator based controller
+     * @param elementController
+     */
+    or(elementController: ElementController): ElementController<Locator>;
     /**
      * Filter out elements with by provided filter.
      * Requires locator based controller.
@@ -45,12 +53,23 @@ export declare class ElementController<T extends Locator | ElementHandle = Locat
      * Requires locator based controller.
      */
     locate(selectorOrController: string | ElementController, filter?: Filter): ElementController<Locator>;
+    first(): ElementController<Locator>;
+    last(): ElementController<Locator>;
+    nth(index: number): ElementController<Locator>;
+    evaluate<R, A>(fn: string | ((element: SVGElement | HTMLElement, argument: A) => R | Promise<R>), argument: A): Promise<R>;
+    evaluate<R, A>(fn: string | ((element: SVGElement | HTMLElement, argument?: A) => R | Promise<R>), argument?: A): Promise<R>;
     /**
      * Wait for element state
      * @param state some states may only be usable for either locator or handle
      * @param options options
      */
     waitFor(state?: Parameters<ElementHandle['waitForElementState']>[0] | NonNullable<LocatorOptions<'waitFor', '0'>['state']>, options?: Parameters<ElementHandle['waitForElementState']>[1]): Promise<void>;
+    boundingBox(options?: TimeoutOptions): Promise<BoundingBox | null>;
+    scrollIntoViewIfNeeded(options?: TimeoutOptions): Promise<void>;
+    /**
+     * Counts matching elements for locator based or returns 1 for handle based.
+     */
+    count(): Promise<number>;
     /**
      * Check if element exists
      * @param options.state which state is required in order to be deemed existing
@@ -58,14 +77,14 @@ export declare class ElementController<T extends Locator | ElementHandle = Locat
      */
     exists(options?: {
         state?: 'visible' | 'attached';
-        timeout?: number;
-    }): Promise<boolean>;
+    } & TimeoutOptions): Promise<boolean>;
     isVisible(): Promise<boolean>;
     isHidden(): Promise<boolean>;
     isEnabled(): Promise<boolean>;
     isDisabled(): Promise<boolean>;
     isChecked(): Promise<boolean>;
     isEditable(): Promise<boolean>;
+    clear(options?: Merge<LocatorOptions<'clear', 1>, ActionDelayOptions>): Promise<void>;
     fill(text: string, options?: Merge<LocatorOptions<'fill', 1>, ActionDelayOptions>): Promise<void>;
     type(text: string, options?: Merge<TypedOmit<LocatorOptions<'type', 1>, 'delay'>, ActionDelayOptions & TypeDelayOptions>): Promise<void>;
     press(key: string, options?: Merge<LocatorOptions<'press', 1>, ActionDelayOptions>): Promise<void>;
@@ -81,6 +100,5 @@ export declare class ElementController<T extends Locator | ElementHandle = Locat
     tap(options?: Merge<LocatorOptions<'tap', 1>, ActionDelayOptions>): Promise<void>;
     selectText(options?: Merge<LocatorOptions<'selectText', 1>, ActionDelayOptions>): Promise<void>;
     inputValue(options?: LocatorOptions<'inputValue', 0>): Promise<string>;
-    private prepareAction;
 }
 export {};

package/browser/element-controller.js

@@ -21,11 +21,10 @@ __export(element_controller_exports, {
   ElementController: () => ElementController
 });
 module.exports = __toCommonJS(element_controller_exports);
-var import_timing = require("../utils/timing.js");
 var import_type_guards = require("../utils/type-guards.js");
 var import_value_or_provider = require("../utils/value-or-provider.js");
 var import_utils = require("./utils.js");
-const filterNonLocatorErrorMessage = "Requires a locator basesd controller";
+const requiresLocatorBasedController = "Requires a locator based controller";
 class ElementController {
   locatorOrHandle;
   options;
@@ -53,17 +52,28 @@ class ElementController {
    * @param elementController
    */
   and(elementController) {
-    (0, import_utils.assertLocator)(this.locatorOrHandle, filterNonLocatorErrorMessage);
-    (0, import_utils.assertLocator)(elementController.locatorOrHandle, filterNonLocatorErrorMessage);
+    (0, import_utils.assertLocator)(this.locatorOrHandle, requiresLocatorBasedController);
+    (0, import_utils.assertLocator)(elementController.locatorOrHandle, requiresLocatorBasedController);
     const locator = this.locatorOrHandle.and(elementController.locatorOrHandle);
     return new ElementController(locator, this.options);
   }
+  /**
+   * Get an controller with elements contained in this and the provided controller.
+   * Requires locator based controller
+   * @param elementController
+   */
+  or(elementController) {
+    (0, import_utils.assertLocator)(this.locatorOrHandle, requiresLocatorBasedController);
+    (0, import_utils.assertLocator)(elementController.locatorOrHandle, requiresLocatorBasedController);
+    const locator = this.locatorOrHandle.or(elementController.locatorOrHandle);
+    return new ElementController(locator, this.options);
+  }
   /**
    * Filter out elements with by provided filter.
    * Requires locator based controller.
    */
   filter(filter) {
-    (0, import_utils.assertLocator)(this.locatorOrHandle, filterNonLocatorErrorMessage);
+    (0, import_utils.assertLocator)(this.locatorOrHandle, requiresLocatorBasedController);
     const locator = this.locatorOrHandle.filter(convertFilter(filter));
     return new ElementController(locator, this.options);
   }
@@ -72,12 +82,33 @@ class ElementController {
    * Requires locator based controller.
    */
   locate(selectorOrController, filter) {
-    (0, import_utils.assertLocator)(this.locatorOrHandle, filterNonLocatorErrorMessage);
-    const selector = (0, import_type_guards.isString)(selectorOrController) ? selectorOrController : (0, import_utils.assertLocatorPass)(selectorOrController.locatorOrHandle, filterNonLocatorErrorMessage);
+    (0, import_utils.assertLocator)(this.locatorOrHandle, requiresLocatorBasedController);
+    const selector = (0, import_type_guards.isString)(selectorOrController) ? selectorOrController : (0, import_utils.assertLocatorPass)(selectorOrController.locatorOrHandle, requiresLocatorBasedController);
     const convertedFilter = (0, import_type_guards.isDefined)(filter) ? convertFilter(filter) : void 0;
     const locator = this.locatorOrHandle.locator(selector, convertedFilter);
     return new ElementController(locator, this.options);
   }
+  first() {
+    (0, import_utils.assertLocator)(this.locatorOrHandle, requiresLocatorBasedController);
+    const locator = this.locatorOrHandle.first();
+    return new ElementController(locator, this.options);
+  }
+  last() {
+    (0, import_utils.assertLocator)(this.locatorOrHandle, requiresLocatorBasedController);
+    const locator = this.locatorOrHandle.last();
+    return new ElementController(locator, this.options);
+  }
+  nth(index) {
+    (0, import_utils.assertLocator)(this.locatorOrHandle, requiresLocatorBasedController);
+    const locator = this.locatorOrHandle.nth(index);
+    return new ElementController(locator, this.options);
+  }
+  async evaluate(fn, argument) {
+    if ((0, import_utils.isLocator)(this.locatorOrHandle)) {
+      return this.locatorOrHandle.evaluate(fn, argument);
+    }
+    return this.locatorOrHandle.evaluate(fn, argument);
+  }
   /**
    * Wait for element state
    * @param state some states may only be usable for either locator or handle
@@ -89,6 +120,18 @@ class ElementController {
     }
     return this.locatorOrHandle.waitForElementState(state, options);
   }
+  async boundingBox(options) {
+    return this.locatorOrHandle.boundingBox({ timeout: options?.timeout ?? 1e3 });
+  }
+  async scrollIntoViewIfNeeded(options) {
+    await this.locatorOrHandle.scrollIntoViewIfNeeded({ timeout: options?.timeout ?? 1e3 });
+  }
+  /**
+   * Counts matching elements for locator based or returns 1 for handle based.
+   */
+  async count() {
+    return (0, import_utils.isLocator)(this.locatorOrHandle) ? this.locatorOrHandle.count() : 1;
+  }
   /**
    * Check if element exists
    * @param options.state which state is required in order to be deemed existing
@@ -96,7 +139,7 @@ class ElementController {
    */
   async exists(options) {
     try {
-      await this.waitFor(options?.state ?? "visible", { timeout: options?.timeout ?? 250 });
+      await this.waitFor(options?.state ?? "visible", { timeout: options?.timeout ?? 1e3 });
       return true;
     } catch (error) {
       if (error instanceof Error && error.message.includes("violation")) {
@@ -123,97 +166,89 @@ class ElementController {
   async isEditable() {
     return this.locatorOrHandle.isEditable();
   }
+  async clear(options) {
+    (0, import_utils.assertLocator)(this.locatorOrHandle, requiresLocatorBasedController);
+    await (0, import_utils.prepareAction)(options);
+    await this.locatorOrHandle.clear(options);
+  }
   async fill(text, options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.fill(text, options);
   }
   async type(text, options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     if ((0, import_type_guards.isUndefined)(this.options.typeDelay)) {
       await this.locatorOrHandle.type(text, options);
     } else {
       for (const char of text) {
         await this.locatorOrHandle.type(char, options);
-        await delay(options?.typeDelay ?? this.options.typeDelay);
+        await (0, import_utils.delay)(options?.typeDelay ?? this.options.typeDelay);
       }
     }
   }
   async press(key, options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.press(key, options);
   }
   async check(options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.check(options);
   }
   async uncheck(options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.uncheck(options);
   }
   async setChecked(checked, options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.setChecked(checked, options);
   }
   async selectOption(option, options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     const selectedOptions = await this.locatorOrHandle.selectOption(option, options);
     return selectedOptions;
   }
   async setInputFiles(files, options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.setInputFiles(files, options);
   }
   async click(options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.click({
       ...options,
       delay: (0, import_value_or_provider.resolveValueOrProvider)(options?.clickDelay)
     });
   }
   async dblclick(options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.dblclick({
       ...options,
       delay: (0, import_value_or_provider.resolveValueOrProvider)(options?.clickDelay)
     });
   }
   async hover(options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.hover(options);
   }
   async focus(options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.focus(options);
   }
   async tap(options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.tap(options);
   }
   async selectText(options) {
-    await this.prepareAction(options);
+    await (0, import_utils.prepareAction)(options);
     await this.locatorOrHandle.selectText(options);
   }
   async inputValue(options) {
     return this.locatorOrHandle.inputValue(options);
   }
-  async prepareAction(options) {
-    const actionDelay = options?.actionDelay ?? this.options.actionDelay;
-    if ((0, import_type_guards.isDefined)(actionDelay)) {
-      await this.waitFor("visible", { timeout: (0, import_value_or_provider.resolveValueOrProvider)(options?.timeout) });
-      await delay(actionDelay);
-    }
-  }
-}
-async function delay(milliseconds) {
-  if ((0, import_type_guards.isUndefined)(milliseconds)) {
-    return;
-  }
-  await (0, import_timing.timeout)((0, import_value_or_provider.resolveValueOrProvider)(milliseconds));
 }
 function convertFilter(filter) {
   return {
-    has: (0, import_type_guards.isDefined)(filter.has) ? (0, import_utils.assertLocatorPass)(filter.has.locatorOrHandle, filterNonLocatorErrorMessage) : void 0,
-    hasNot: (0, import_type_guards.isDefined)(filter.hasNot) ? (0, import_utils.assertLocatorPass)(filter.hasNot.locatorOrHandle, filterNonLocatorErrorMessage) : void 0,
+    has: (0, import_type_guards.isDefined)(filter.has) ? (0, import_utils.assertLocatorPass)(filter.has.locatorOrHandle, requiresLocatorBasedController) : void 0,
+    hasNot: (0, import_type_guards.isDefined)(filter.hasNot) ? (0, import_utils.assertLocatorPass)(filter.hasNot.locatorOrHandle, requiresLocatorBasedController) : void 0,
     hasText: filter.hasText,
     hasNotText: filter.hasNotText
   };

package/browser/page-controller.d.ts

@@ -5,10 +5,15 @@ import type { Logger } from '../logger/logger.js';
 import type { BrowserContextController } from './browser-context-controller.js';
 import type { DocumentControllerOptions } from './document-controller.js';
 import { DocumentController } from './document-controller.js';
+import { ElementController } from './element-controller.js';
 import type { FrameController, FrameControllerOptions } from './frame-controller.js';
 import type { PdfRenderOptions } from './pdf-options.js';
 import type { Abortable } from './types.js';
 export type PageControllerOptions = DocumentControllerOptions;
+export type ScrollToCoordinates = {
+    x?: number;
+    y?: number;
+};
 export declare class PageController extends DocumentController<Page> implements AsyncDisposable {
     /** @deprecated should be avoided */
     readonly page: Page;
@@ -28,6 +33,8 @@ export declare class PageController extends DocumentController<Page> implements
      */
     frame(frameSelector: Parameters<Page['frame']>[0], options?: FrameControllerOptions): FrameController;
     renderPdf(options?: PdfRenderOptions & Abortable): Promise<Uint8Array>;
+    scroll(deltaX: number, deltaY: number): Promise<void>;
+    scrollTo(coordinatesOrController: ScrollToCoordinates | ElementController): Promise<void>;
     renderPdfStream(options?: PdfRenderOptions & Abortable): ReadableStream<Uint8Array>;
     attachLogger(logger: Logger): void;
 }

package/browser/page-controller.js

@@ -28,6 +28,7 @@ var import_timing = require("../utils/timing.js");
 var import_type_guards = require("../utils/type-guards.js");
 var import_units = require("../utils/units.js");
 var import_document_controller = require("./document-controller.js");
+var import_element_controller = require("./element-controller.js");
 var import_utils = require("./utils.js");
 class PageController extends import_document_controller.DocumentController {
   /** @deprecated should be avoided */
@@ -92,6 +93,52 @@ class PageController extends import_document_controller.DocumentController {
     const createPdfOptions = convertPdfOptions(options);
     return (0, import_timing.withTimeout)(options.timeout ?? 30 * import_units.millisecondsPerSecond, this.page.pdf(createPdfOptions), { errorMessage: "Rendering pdf timed out." });
   }
+  async scroll(deltaX, deltaY) {
+    await this.page.mouse.wheel(deltaX, deltaY);
+  }
+  async scrollTo(coordinatesOrController) {
+    const viewportSize = this.page.viewportSize();
+    if ((0, import_type_guards.isNull)(viewportSize)) {
+      throw new Error("Could not get page viewport size.");
+    }
+    const targetLeft = viewportSize.width / 3;
+    const targetRight = viewportSize.width / 3 * 2;
+    const targetTop = viewportSize.height / 3;
+    const targetBottom = viewportSize.height / 3 * 2;
+    const offsetX = viewportSize.width / 10;
+    const offsetY = viewportSize.height / 10;
+    const isElement = coordinatesOrController instanceof import_element_controller.ElementController;
+    while (true) {
+      const { scrollWidth, scrollHeight, scrollLeft, scrollTop, clientWidth, clientHeight } = await this.page.evaluate(async () => {
+        const { scrollWidth: scrollWidth2, scrollHeight: scrollHeight2, scrollLeft: scrollLeft2, scrollTop: scrollTop2, clientWidth: clientWidth2, clientHeight: clientHeight2 } = document.documentElement;
+        return { scrollWidth: scrollWidth2, scrollHeight: scrollHeight2, scrollLeft: scrollLeft2, scrollTop: scrollTop2, clientWidth: clientWidth2, clientHeight: clientHeight2 };
+      });
+      let targetX;
+      let targetY;
+      if (isElement) {
+        const boundingBox = await coordinatesOrController.boundingBox();
+        if ((0, import_type_guards.isNull)(boundingBox)) {
+          throw new Error("Could not get element bounding box.");
+        }
+        targetX = boundingBox.x + boundingBox.width / 2;
+        targetY = boundingBox.y + boundingBox.height / 2;
+      } else {
+        targetX = (0, import_type_guards.isDefined)(coordinatesOrController.x) ? coordinatesOrController.x - scrollLeft : void 0;
+        targetY = (0, import_type_guards.isDefined)(coordinatesOrController.y) ? coordinatesOrController.y - scrollTop : void 0;
+      }
+      const deltaX = (0, import_type_guards.isUndefined)(targetX) ? void 0 : targetX < targetLeft && scrollLeft > 0 ? -offsetX : targetX > targetRight && scrollLeft + clientWidth < scrollWidth ? offsetX : void 0;
+      const deltaY = (0, import_type_guards.isUndefined)(targetY) ? void 0 : targetY < targetTop && scrollTop > 0 ? -offsetY : targetY > targetBottom && scrollTop + clientHeight < scrollHeight ? offsetY : void 0;
+      if ((0, import_type_guards.isDefined)(deltaY)) {
+        await this.page.mouse.wheel(0, deltaY);
+        await (0, import_utils.delay)(Math.max(10, 150 - Math.abs(targetY - targetTop) / 10));
+      } else if ((0, import_type_guards.isDefined)(deltaX)) {
+        await this.page.mouse.wheel(deltaX, 0);
+        await (0, import_utils.delay)(Math.max(10, 150 - Math.abs(targetX - targetLeft) / 10));
+      } else {
+        break;
+      }
+    }
+  }
   renderPdfStream(options = {}) {
     return (0, import_readable_stream_from_promise.readableStreamFromPromise)(async () => {
       const buffer = await this.renderPdf(options);

package/browser/types.d.ts

@@ -1,3 +1,4 @@
+import type { ValueOrProvider } from '../utils/value-or-provider.js';
 export type TimeoutOptions = {
     timeout?: number;
 };
@@ -8,3 +9,7 @@ export type WaitForStateOptions = {
 export type Abortable = {
     abort?: AbortSignal;
 };
+export type Delay = ValueOrProvider<number>;
+export type ActionDelayOptions = {
+    actionDelay?: Delay;
+};

package/browser/utils.d.ts

@@ -2,6 +2,7 @@ import type { Logger } from '../logger/logger.js';
 import type { BrowserContext, ElementHandle, Frame, LaunchOptions, Locator, Page } from 'playwright';
 import type { NewBrowserContextOptions } from './browser-controller.js';
 import type { NewBrowserOptions } from './browser.service.js';
+import type { ActionDelayOptions, Delay, TimeoutOptions } from './types.js';
 export declare function getLaunchOptions(options: NewBrowserOptions): LaunchOptions;
 export declare function mergeNewBrowserContextOptions(a: NewBrowserContextOptions | undefined, b?: NewBrowserContextOptions, c?: NewBrowserContextOptions): NewBrowserContextOptions;
 export declare function attachLogger(loggable: Page | BrowserContext, logger: Logger): void;
@@ -12,3 +13,5 @@ export declare function isElementHandle(locatorOrHandle: Locator | ElementHandle
 export declare function isPage(pageOrFrameOrContext: Page | Frame | BrowserContext): pageOrFrameOrContext is Page;
 export declare function isFrame(pageOrFrameOrContext: Page | Frame | BrowserContext): pageOrFrameOrContext is Frame;
 export declare function isBrowserContext(pageOrFrameOrContext: Page | Frame | BrowserContext): pageOrFrameOrContext is BrowserContext;
+export declare function prepareAction(options?: ActionDelayOptions & TimeoutOptions): Promise<void>;
+export declare function delay(milliseconds: Delay | undefined): Promise<void>;

package/browser/utils.js

@@ -21,17 +21,21 @@ __export(utils_exports, {
   assertLocator: () => assertLocator,
   assertLocatorPass: () => assertLocatorPass,
   attachLogger: () => attachLogger,
+  delay: () => delay,
   getLaunchOptions: () => getLaunchOptions,
   isBrowserContext: () => isBrowserContext,
   isElementHandle: () => isElementHandle,
   isFrame: () => isFrame,
   isLocator: () => isLocator,
   isPage: () => isPage,
-  mergeNewBrowserContextOptions: () => mergeNewBrowserContextOptions
+  mergeNewBrowserContextOptions: () => mergeNewBrowserContextOptions,
+  prepareAction: () => prepareAction
 });
 module.exports = __toCommonJS(utils_exports);
 var import_object = require("../utils/object/object.js");
+var import_timing = require("../utils/timing.js");
 var import_type_guards = require("../utils/type-guards.js");
+var import_value_or_provider = require("../utils/value-or-provider.js");
 const pageLoggerMap = /* @__PURE__ */ new WeakMap();
 function getLaunchOptions(options) {
   const { windowSize, browserArguments, headless } = options;
@@ -125,3 +129,15 @@ function isFrame(pageOrFrameOrContext) {
 function isBrowserContext(pageOrFrameOrContext) {
   return pageOrFrameOrContext.constructor.name == "BrowserContext";
 }
+async function prepareAction(options) {
+  const actionDelay = options?.actionDelay;
+  if ((0, import_type_guards.isDefined)(actionDelay)) {
+    await (0, import_timing.timeout)((0, import_value_or_provider.resolveValueOrProvider)(actionDelay));
+  }
+}
+async function delay(milliseconds) {
+  if ((0, import_type_guards.isUndefined)(milliseconds)) {
+    return;
+  }
+  await (0, import_timing.timeout)((0, import_value_or_provider.resolveValueOrProvider)(milliseconds));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.87.2",
+  "version": "0.87.3",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"