tessl/npm-playwright

A high-level API to automate web browsers and comprehensive framework for web testing

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Page Interaction

Name: tessl/npm-playwright
Author: tessl

Page navigation, element interaction, and content manipulation with automatic waiting, cross-frame support, and reliable element selection.

Capabilities

Page Navigation

Navigate pages, handle navigation events, and manage page lifecycle.

interface Page {
  /** Navigate to URL */
  goto(url: string, options?: PageGotoOptions): Promise<Response | null>;
  /** Reload the page */  
  reload(options?: PageReloadOptions): Promise<Response | null>;
  /** Go back in navigation history */
  goBack(options?: PageGoBackOptions): Promise<Response | null>;
  /** Go forward in navigation history */
  goForward(options?: PageGoForwardOptions): Promise<Response | null>;
  /** Get current URL */
  url(): string;
  /** Get page title */
  title(): Promise<string>;
  /** Close the page */
  close(options?: PageCloseOptions): Promise<void>;
  /** Check if page is closed */
  isClosed(): boolean;
}

interface PageGotoOptions {
  /** Navigation timeout in milliseconds */
  timeout?: number;
  /** Wait until condition */
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
  /** Referer header value */
  referer?: string;
}

Usage Examples:

// Basic navigation
await page.goto('https://example.com');
await page.goto('https://example.com', { 
  waitUntil: 'networkidle' 
});

// Navigation with timeout
await page.goto('https://slow-site.com', { 
  timeout: 60000 
});

// Get page info
const title = await page.title();
const url = page.url();

// Navigation history
await page.goBack();
await page.goForward();
await page.reload();

Element Interaction

Interact with page elements using selectors, automatic waiting, and reliable actions.

interface Page {
  /** Click element */
  click(selector: string, options?: PageClickOptions): Promise<void>;
  /** Double-click element */
  dblclick(selector: string, options?: PageDblclickOptions): Promise<void>;
  /** Fill input element */
  fill(selector: string, value: string, options?: PageFillOptions): Promise<void>;
  /** Type text into element */
  type(selector: string, text: string, options?: PageTypeOptions): Promise<void>;
  /** Press key */
  press(selector: string, key: string, options?: PagePressOptions): Promise<void>;
  /** Check checkbox or radio */
  check(selector: string, options?: PageCheckOptions): Promise<void>;
  /** Uncheck checkbox */
  uncheck(selector: string, options?: PageUncheckOptions): Promise<void>;
  /** Select option(s) */
  selectOption(selector: string, values: string | string[] | SelectOption | SelectOption[], options?: PageSelectOptionOptions): Promise<string[]>;
  /** Set input files */
  setInputFiles(selector: string, files: string | string[] | FilePayload | FilePayload[], options?: PageSetInputFilesOptions): Promise<void>;
  /** Hover over element */
  hover(selector: string, options?: PageHoverOptions): Promise<void>;
  /** Focus element */
  focus(selector: string, options?: PageFocusOptions): Promise<void>;
  /** Blur element */
  blur(selector: string, options?: PageBlurOptions): Promise<void>;
}

interface PageClickOptions {
  /** Button to click */
  button?: 'left' | 'right' | 'middle';
  /** Number of clicks */
  clickCount?: number;
  /** Modifier keys */  
  modifiers?: ('Alt' | 'Control' | 'Meta' | 'Shift')[];
  /** Click position */
  position?: { x: number; y: number };
  /** Timeout in milliseconds */
  timeout?: number;
  /** Force click even if element is not actionable */
  force?: boolean;
  /** Skip actionability checks */
  noWaitAfter?: boolean;
  /** Trial run mode */
  trial?: boolean;
}

Usage Examples:

// Basic interactions
await page.click('#submit-button');
await page.fill('#email', 'user@example.com');
await page.type('#password', 'secret123');
await page.press('#search', 'Enter');

// Advanced interactions  
await page.click('.menu-item', { 
  button: 'right',
  modifiers: ['Control'] 
});

await page.hover('.tooltip-trigger');
await page.focus('#first-input');

// Form interactions
await page.check('#agree-terms');
await page.selectOption('#country', 'USA');
await page.setInputFiles('#file-upload', './document.pdf');

Locators

Modern element selectors with auto-waiting and retry logic.

interface Page {
  /** Create locator for selector */
  locator(selector: string, options?: PageLocatorOptions): Locator;
  /** Get element handle (deprecated - use locator) */
  $(selector: string): Promise<ElementHandle | null>;
  /** Get multiple element handles (deprecated - use locator) */
  $$(selector: string): Promise<ElementHandle[]>;
}

interface Locator {
  /** Click the element */  
  click(options?: LocatorClickOptions): Promise<void>;
  /** Double-click the element */
  dblclick(options?: LocatorDblclickOptions): Promise<void>;
  /** Fill input element */
  fill(value: string, options?: LocatorFillOptions): Promise<void>;
  /** Type text */
  type(text: string, options?: LocatorTypeOptions): Promise<void>;
  /** Press key */
  press(key: string, options?: LocatorPressOptions): Promise<void>;
  /** Check checkbox/radio */
  check(options?: LocatorCheckOptions): Promise<void>;
  /** Uncheck checkbox */
  uncheck(options?: LocatorUncheckOptions): Promise<void>;
  /** Select options */
  selectOption(values: string | string[] | SelectOption | SelectOption[], options?: LocatorSelectOptionOptions): Promise<string[]>;
  /** Set input files */
  setInputFiles(files: string | string[] | FilePayload | FilePayload[], options?: LocatorSetInputFilesOptions): Promise<void>;
  /** Hover over element */
  hover(options?: LocatorHoverOptions): Promise<void>;
  /** Focus element */
  focus(options?: LocatorFocusOptions): Promise<void>;
  /** Blur element */
  blur(options?: LocatorBlurOptions): Promise<void>;

  /** Get text content */
  textContent(options?: LocatorTextContentOptions): Promise<string | null>;
  /** Get inner text */
  innerText(options?: LocatorInnerTextOptions): Promise<string>;
  /** Get inner HTML */
  innerHTML(options?: LocatorInnerHTMLOptions): Promise<string>;
  /** Get attribute */
  getAttribute(name: string, options?: LocatorGetAttributeOptions): Promise<string | null>;
  /** Get input value */
  inputValue(options?: LocatorInputValueOptions): Promise<string>;
  
  /** Check if element is visible */
  isVisible(options?: LocatorIsVisibleOptions): Promise<boolean>;
  /** Check if element is hidden */
  isHidden(options?: LocatorIsHiddenOptions): Promise<boolean>;  
  /** Check if element is enabled */
  isEnabled(options?: LocatorIsEnabledOptions): Promise<boolean>;
  /** Check if element is disabled */
  isDisabled(options?: LocatorIsDisabledOptions): Promise<boolean>;
  /** Check if element is editable */
  isEditable(options?: LocatorIsEditableOptions): Promise<boolean>;
  /** Check if checkbox is checked */
  isChecked(options?: LocatorIsCheckedOptions): Promise<boolean>;

  /** Get element count */
  count(): Promise<number>;
  /** Get nth element */
  nth(index: number): Locator;
  /** Get first element */
  first(): Locator;
  /** Get last element */
  last(): Locator;
  /** Filter by text */
  filter(options?: LocatorFilterOptions): Locator;
}

interface PageLocatorOptions {
  /** Has text content */
  hasText?: string | RegExp;
  /** Has attribute */
  has?: Locator;
}

interface LocatorFilterOptions {
  /** Filter by text content */
  hasText?: string | RegExp;
  /** Filter by contained locator */
  has?: Locator;
}

Usage Examples:

// Basic locators
const submitButton = page.locator('#submit');
const menuItems = page.locator('.menu-item');

// Locator actions  
await submitButton.click();
await page.locator('#email').fill('user@example.com');
await page.locator('#search').press('Enter');

// Locator queries
const text = await page.locator('h1').textContent();
const count = await page.locator('.item').count();
const isVisible = await page.locator('#banner').isVisible();

// Locator filtering
const activeItems = page.locator('.item').filter({ hasText: 'active' });
const firstItem = page.locator('.item').first();
const lastItem = page.locator('.item').last();
const thirdItem = page.locator('.item').nth(2);

// Complex locators
const buttonInCard = page.locator('.card').filter({ 
  has: page.locator('h2', { hasText: 'Premium' }) 
}).locator('button');

Frame Interaction

Work with iframes and nested browsing contexts.

interface Page {
  /** Get main frame */
  mainFrame(): Frame;
  /** Get all frames */
  frames(): Frame[];
  /** Get frame by name or URL */
  frame(options: { name?: string; url?: string | RegExp }): Frame | null;
  /** Create frame locator */
  frameLocator(selector: string): FrameLocator;
}

interface Frame {
  /** Navigate frame to URL */
  goto(url: string, options?: FrameGotoOptions): Promise<Response | null>;
  /** Get frame URL */
  url(): string;
  /** Get frame name */
  name(): string;
  /** Get parent frame */
  parentFrame(): Frame | null;
  /** Get child frames */
  childFrames(): Frame[];
  /** Check if frame is detached */
  isDetached(): boolean;

  /** Click element in frame */
  click(selector: string, options?: FrameClickOptions): Promise<void>;
  /** Fill element in frame */
  fill(selector: string, value: string, options?: FrameFillOptions): Promise<void>;
  /** Create locator in frame */
  locator(selector: string, options?: FrameLocatorOptions): Locator;
}

interface FrameLocator {
  /** Create locator within frame */
  locator(selector: string): Locator;
  /** Create nested frame locator */
  frameLocator(selector: string): FrameLocator;
  /** Get first matching frame */
  first(): FrameLocator;
  /** Get last matching frame */
  last(): FrameLocator;
  /** Get nth matching frame */
  nth(index: number): FrameLocator;
}

Usage Examples:

// Work with frames
const frame = page.frame({ name: 'content-frame' });
if (frame) {
  await frame.click('#frame-button');
  await frame.fill('#frame-input', 'value');
}

// Frame locators (recommended)
const frameButton = page.frameLocator('#content-frame').locator('#button');
await frameButton.click();

// Nested frames
const nestedButton = page
  .frameLocator('#outer-frame')
  .frameLocator('#inner-frame')  
  .locator('#button');
await nestedButton.click();

Content Evaluation

Execute JavaScript in page context and extract data.

interface Page {
  /** Evaluate JavaScript expression */
  evaluate<R, Arg>(pageFunction: PageFunction<Arg, R>, arg: Arg): Promise<R>;
  evaluate<R>(pageFunction: PageFunction<void, R>, arg?: any): Promise<R>;
  /** Evaluate and return JSHandle */
  evaluateHandle<R, Arg>(pageFunction: PageFunction<Arg, R>, arg: Arg): Promise<JSHandle<R>>;
  evaluateHandle<R>(pageFunction: PageFunction<void, R>, arg?: any): Promise<JSHandle<R>>;
  /** Add script tag */
  addScriptTag(options: PageAddScriptTagOptions): Promise<ElementHandle>;
  /** Add style tag */
  addStyleTag(options: PageAddStyleTagOptions): Promise<ElementHandle>;
  /** Expose function to page */
  exposeFunction(name: string, callback: Function): Promise<void>;
  /** Expose binding to page */
  exposeBinding(name: string, callback: PageBinding, options?: PageExposeBindingOptions): Promise<void>;
}

type PageFunction<Arg, R> = string | ((arg: Arg) => R | Promise<R>);
type PageBinding = (source: BindingSource, ...args: any[]) => any;

interface PageAddScriptTagOptions {
  /** Script URL */
  url?: string;
  /** Script path */
  path?: string;
  /** Script content */
  content?: string;
  /** Script type */
  type?: string;
}

interface PageAddStyleTagOptions {
  /** Stylesheet URL */
  url?: string;
  /** Stylesheet path */
  path?: string;
  /** Stylesheet content */  
  content?: string;
}

Usage Examples:

// Evaluate JavaScript
const title = await page.evaluate(() => document.title);
const windowSize = await page.evaluate(() => ({
  width: window.innerWidth,
  height: window.innerHeight
}));

// Pass arguments to evaluation
const result = await page.evaluate((text) => {
  return document.querySelector('h1').textContent === text;
}, 'Welcome');

// Add external scripts
await page.addScriptTag({ url: 'https://code.jquery.com/jquery.min.js' });
await page.addScriptTag({ path: './my-script.js' });

// Expose function to page
await page.exposeFunction('generateId', () => Math.random().toString(36));
// Now page can call: const id = await generateId();

Types

Element Selection Types

interface SelectOption {
  value?: string;
  label?: string;
  index?: number;
}

interface FilePayload {
  name: string;
  mimeType: string;
  buffer: Buffer;
}

interface BindingSource {
  context: BrowserContext;
  page: Page;
  frame: Frame;
}

Wait Options

interface PageWaitForSelectorOptions {
  /** Wait for element state */
  state?: 'attached' | 'detached' | 'visible' | 'hidden';
  /** Wait timeout */
  timeout?: number;
  /** Wait for strict mode (single element) */
  strict?: boolean;
}

interface PageWaitForFunctionOptions {
  /** Function to wait for */
  timeout?: number;
  /** Polling interval */
  polling?: number | 'raf';
}

interface PageWaitForEventOptions {
  /** Event timeout */
  timeout?: number;
  /** Predicate function */
  predicate?: Function;
}

interface PageWaitForURLOptions {
  /** Navigation timeout */
  timeout?: number;
  /** Wait until condition */
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
}

Install with Tessl CLI