tessl/npm-puppeteer

A high-level API to control headless Chrome over the DevTools Protocol

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Locators & Waiting

Name: tessl/npm-puppeteer
Author: tessl

Modern element selection with automatic waiting, retries, and fluent interface for reliable element interactions.

Capabilities

Locator Class

Modern element locator with built-in waiting and retry mechanisms.

/**
 * Modern element locator with automatic waiting and retries
 */
class Locator<T> {
  /** Set timeout for all operations */
  setTimeout(timeout: number): Locator<T>;
  
  /** Set visibility requirement */
  setVisibility(visibility: VisibilityOption): Locator<T>;
  
  /** Set wait for enabled requirement */
  setWaitForEnabled(wait: boolean): Locator<T>;
  
  /** Set viewport requirement */
  setEnsureElementIsInTheViewport(ensure: boolean): Locator<T>;
  
  /** Set stable bounding box requirement */
  setWaitForStableBoundingBox(wait: boolean): Locator<T>;
  
  /** Wait for element handle */
  waitHandle(options?: ActionOptions): Promise<HandleFor<T>>;
  
  /** Wait for element */
  wait(options?: ActionOptions): Promise<T>;
  
  /** Click element with automatic waiting */
  click(options?: LocatorClickOptions): Promise<void>;
  
  /** Fill input field */
  fill(value: string, options?: ActionOptions): Promise<void>;
  
  /** Focus element */
  focus(options?: ActionOptions): Promise<void>;
  
  /** Hover over element */
  hover(options?: ActionOptions): Promise<void>;
  
  /** Scroll element */
  scroll(options?: LocatorScrollOptions): Promise<void>;
  
  /** Filter locator results */
  filter<U extends T>(predicate: Predicate<T, U>): Locator<U>;
  
  /** Map locator results */
  map<To>(mapper: Mapper<T, To>): Locator<To>;
  
  /** Race multiple locators */
  static race<T>(locators: T[]): RaceLocator<AwaitedLocator<T[number]>>;
}

type VisibilityOption = "visible" | "hidden";

interface ActionOptions {
  timeout?: number;
}

interface LocatorClickOptions extends ActionOptions {
  button?: "left" | "right" | "middle";
  clickCount?: number;
  delay?: number;
}

interface LocatorScrollOptions extends ActionOptions {
  behavior?: "auto" | "instant" | "smooth";
  block?: "start" | "center" | "end" | "nearest";
  inline?: "start" | "center" | "end" | "nearest";
}

Usage Examples:

// Create locator
const submitButton = page.locator("#submit-button");

// Configure locator
const stableButton = submitButton
  .setTimeout(10000)
  .setVisibility("visible")
  .setWaitForEnabled(true)
  .setWaitForStableBoundingBox(true);

// Use locator with automatic retries
await stableButton.click();

// Filter and map locators
const visibleLinks = page.locator("a")
  .filter(async (el) => await el.isVisible())
  .map(async (el) => await el.getAttribute("href"));

// Race multiple locators
const firstButton = Locator.race([
  page.locator("#button1"),
  page.locator("#button2"),
  page.locator("#button3")
]);
await firstButton.click();

Page Locator Methods

Create locators from page context.

/**
 * Create locator for selector
 * @param selector - CSS selector
 * @returns Locator instance
 */
locator(selector: string): Locator;

/**
 * Race multiple locators
 * @param locators - Array of locators to race
 * @returns Racing locator
 */
locatorRace(locators: Locator[]): Locator;

Usage Examples:

// Create locators
const searchBox = page.locator("#search");
const results = page.locator(".search-result");

// Race for first available action
const quickAction = page.locatorRace([
  page.locator("#quick-save"),
  page.locator("#quick-cancel"),
  page.locator("#quick-submit")
]);

await quickAction.click();

Waiting Utilities

Traditional waiting methods for various conditions.

/**
 * Wait for selector to appear
 */
waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle>;

/**
 * Wait for function condition
 */
waitForFunction<R>(
  pageFunction: (...args: any[]) => R,
  options?: WaitForFunctionOptions,
  ...args: any[]
): Promise<JSHandle<R>>;

/**
 * Wait for timeout
 */
waitForTimeout(milliseconds: number): Promise<void>;

/**
 * Wait for file chooser dialog
 */
waitForFileChooser(options?: WaitTimeoutOptions): Promise<FileChooser>;

interface WaitForSelectorOptions {
  visible?: boolean;
  hidden?: boolean;
  timeout?: number;
}

interface WaitForFunctionOptions {
  timeout?: number;
  polling?: "raf" | "mutation" | number;
}

Usage Examples:

// Wait for elements
await page.waitForSelector(".loading", { hidden: true });
await page.waitForSelector("#content", { visible: true, timeout: 5000 });

// Wait for conditions
await page.waitForFunction(() => window.dataReady === true);
await page.waitForFunction(
  (text) => document.body.innerText.includes(text),
  { polling: 1000 },
  "Success"
);

// Wait for file chooser
const fileChooserPromise = page.waitForFileChooser();
await page.click("#upload-button");
const fileChooser = await fileChooserPromise;
await fileChooser.accept(["path/to/file.pdf"]);

FileChooser Class

Handle file chooser dialogs for file upload interactions.

/**
 * File chooser dialog for file uploads
 */
class FileChooser {
  /** Check if multiple file selection is allowed */
  isMultiple(): boolean;
  
  /** Accept file chooser with file paths */
  accept(filePaths: string[]): Promise<void>;
  
  /** Cancel file chooser */
  cancel(): Promise<void>;
}

Usage Examples:

// Handle file upload
const fileChooserPromise = page.waitForFileChooser();
await page.click("#file-upload-button");
const fileChooser = await fileChooserPromise;

// Check if multiple files allowed
if (fileChooser.isMultiple()) {
  // Upload multiple files
  await fileChooser.accept([
    "/path/to/file1.pdf",
    "/path/to/file2.jpg",
    "/path/to/file3.txt"
  ]);
} else {
  // Upload single file
  await fileChooser.accept(["/path/to/document.pdf"]);
}

// Cancel file chooser
// await fileChooser.cancel();

Install with Tessl CLI