Imported from outerbounds/ob-quality (e2e/.claude/skills/anaconda-playwright-utils/SKILL.md). Install upstream with npx skills add outerbounds/ob-quality --skill anaconda-playwright-utils. Copyright stays with the author.

@anaconda/playwright-utils

A Playwright TypeScript utility library that simplifies browser automation with reusable helper functions for actions, assertions, locators, element queries, page management, and API requests.

Setup Requirement

The library uses a singleton page pattern. setPage(page) must be called once per test before any utility function runs — but the fixture handles this automatically. When you import test from @fixture, setPage(page) is called before every test without any manual setup.

import { test } from '@fixture'; // setPage(page) is called automatically — nothing else needed

Only call setPage(page) manually if you are NOT using the fixture (e.g., raw @playwright/test in a standalone script).

Import Patterns

Main export (all utilities)

import { click, expectElementToBeVisible, fill, getLocator, logger } from '@anaconda/playwright-utils';

logger is a Winston-based logger exported from the library. Use it in page objects only for informational or warning messages — never in spec files and never with console.log.

Subpath exports (tree-shakable)

import { click, clickAndNavigate, fill } from '@anaconda/playwright-utils/action-utils';
import { expectElementToBeVisible, expectPageToHaveURL } from '@anaconda/playwright-utils/assert-utils';
import { getLocator, getLocatorByRole, getLocatorByText } from '@anaconda/playwright-utils/locator-utils';
import { getText, isElementVisible, waitForElementToBeVisible } from '@anaconda/playwright-utils/element-utils';
import { getPage, gotoURL, setPage, switchPage } from '@anaconda/playwright-utils/page-utils';
import { getRequest, postRequest } from '@anaconda/playwright-utils/api-utils';
import { ACTION_TIMEOUT, SMALL_TIMEOUT, STANDARD_TIMEOUT, TEST_TIMEOUT } from '@anaconda/playwright-utils/constants';
import { ClickOptions, FillOptions } from '@anaconda/playwright-utils/types';
import { logger } from '@anaconda/playwright-utils'; // named export

Core Pattern

Most functions accept string | Locator as their first argument (the input parameter). This means you can pass either a CSS/XPath selector string or a Playwright Locator object.

Standard action functions enforce visibility by default (onlyVisible: true); override with { onlyVisible: false }. Exceptions (canonical list): the JS helpers (clickByJS, clearByJS), scrollLocatorIntoView, and the alert helpers accept only { timeout } (acceptAlert additionally accepts promptText) and do not filter to visible elements. For alert helpers, timeout bounds both the trigger click and dialog wait; trigger click failures are rethrown unchanged instead of being reported as dialog timeouts.

Most functions accept an optional options object as the last parameter, extending Playwright's native options with:

• onlyVisible?: boolean - Filter to visible elements only (default: true for actions)
• stable?: boolean - Wait for element position to stabilize before acting
• loadState?: WaitForLoadStateOptions - Wait for load state after navigation actions
• soft?: boolean - Use soft assertions (won't stop test on failure)

Module Reference

115 Playwright utility functions across six modules — the tables below are the canonical count and name list for utility wrappers. Additional public exports that are not Playwright wrappers are documented separately after the utility tables.

Action Utils (action-utils)

Interact with page elements.

Assert Utils (assert-utils)

Playwright auto-retrying assertions.

Additional Public Exports

These exports are not counted in the 115 Playwright utility functions.

Locator Utils (locator-utils)

Find elements on the page.

Element Utils (element-utils)

Retrieve data and check element state.

Page Utils (page-utils)

Page management and navigation.

API Utils (api-utils)

HTTP requests via Playwright's API context.

Constants

Timeout constants for use in options.timeout overrides and playwright.config.ts. Import from the main entry or the ./constants subpath.

import { SMALL_TIMEOUT, STANDARD_TIMEOUT } from '@anaconda/playwright-utils';
// or tree-shakable:
import {
  ACTION_TIMEOUT,
  BIG_TIMEOUT,
  SMALL_TIMEOUT,
  STANDARD_TIMEOUT,
  TEST_TIMEOUT,
} from '@anaconda/playwright-utils/constants';

Example Test

Tests are always structured with three files: a Page Object class, a Fixture registration, and a Spec file. All actions and assertions live in the page object class — the spec only calls page object methods via injected fixtures.

Page Object Class (tests/pages/login-page.ts)

import {
  click,
  clickAndNavigate,
  expectElementToBeAttached,
  expectElementToBeVisible,
  fill,
  getLocator,
  getLocatorByPlaceholder,
  getLocatorByRole,
  gotoURL,
} from '@anaconda/playwright-utils';
import { urlData } from '@testdata/<url-module>'; // NOTE: replace <url-module> with your project URL testdata module (under tests/testdata/)
import { invalidUser, validUser } from '@testdata/<user-module>'; // NOTE: replace <user-module> with your project user testdata module (under tests/testdata/)

export class LoginPage {
  // Static selectors — raw CSS/XPath strings (no library call at class instantiation)
  private readonly usernameInput = '#username';
  private readonly welcomeMessage = '[data-test="welcome-message"]';
  private readonly errorMessage = '[data-test="error-message"]';

  // Arrow functions — any library locator call (any tier); defers getPage() to test execution
  private readonly passwordInput = () => getLocator('#password').or(getLocatorByPlaceholder('Password'));
  private readonly loginButton = () => getLocatorByRole('button', { name: 'Login' });

  async navigateToLoginPage(): Promise<void> {
    await gotoURL(urlData.loginPageUrl);
  }

  async loginWithValidCredentials(username = validUser.username, password = validUser.pwd): Promise<void> {
    await fill(this.usernameInput, username);
    await fill(this.passwordInput(), password);
    await clickAndNavigate(this.loginButton());
  }

  async loginWithInvalidCredentials(username = invalidUser.username, password = invalidUser.pwd): Promise<void> {
    await fill(this.usernameInput, username);
    await fill(this.passwordInput(), password);
    await click(this.loginButton());
  }

  async verifyLoginSuccessful(): Promise<void> {
    await expectElementToBeAttached(this.welcomeMessage, 'User should be logged in successfully');
  }

  async verifyInvalidLoginError(): Promise<void> {
    await expectElementToBeVisible(this.errorMessage, 'Error message should be displayed for invalid credentials');
  }

  async verifyLoginPageIsDisplayed(): Promise<void> {
    await expectElementToBeVisible(this.usernameInput, 'Login page should be displayed');
  }
}

Fixture Registration (tests/fixtures/fixture.ts)

import { test as baseTest } from '@anaconda/playwright-utils';
import { LoginPage } from '@pages/login-page';
import { ProductsPage } from '@pages/products-page';

export const test = baseTest.extend<{
  loginPage: LoginPage;
  productsPage: ProductsPage;
}>({
  loginPage: async ({}, use) => {
    await use(new LoginPage());
  },
  productsPage: async ({}, use) => {
    await use(new ProductsPage());
  },
});

Spec File

import { test } from '@fixture';

test.describe('Login @smoke', () => {
  test.beforeEach(async ({ loginPage }) => {
    await loginPage.navigateToLoginPage();
  });

  test('should login with valid credentials', async ({ loginPage }) => {
    await loginPage.loginWithValidCredentials();
    await loginPage.verifyLoginSuccessful();
  });

  test('should show error with invalid credentials', async ({ loginPage }) => {
    await loginPage.loginWithInvalidCredentials();
    await loginPage.verifyInvalidLoginError();
  });
});

Key rules:

• Import test from @fixture — this auto-calls setPage(page) before each test (no manual setup needed)
• Page objects are classes registered in fixture.ts and injected via destructuring: async ({ loginPage }) => {}
• No actions or assertions in spec files — fill, click, gotoURL, expectElementToBeVisible, etc. all belong in the page object class; spec files only call page object methods
• Separate actions from assertions — action methods contain interactions only; verify* methods contain expect* only. Click→navigate flows use click* + verify* pairs — never bundled navigateTo* methods mixing clickAndNavigate with URL assertions
• No raw expect() in spec files — use verify* methods in page objects instead
• Use logger from @anaconda/playwright-utils in page objects only — never in specs, and never console.log
• Wrap all tests in a test.describe block with a descriptive name and tag (@smoke, @reg)
• Use test.beforeEach for shared setup (navigation, login) that every test in the describe needs

CLI-to-Library Code Mapping

When using playwright-cli to explore pages, translate the generated Playwright code to @anaconda/playwright-utils equivalents. The same table covers raw Playwright API calls found in existing tests when healing:

Skill Precedence and CLI Discovery

Precedence (highest → lowest): project skill → @anaconda/playwright-utils → playwright-cli

When writing test code, respect this order:

1. Project skill wins — if a project-specific skill defines patterns, login flows, or feature-flag helpers, they take priority over library defaults.
2. @anaconda/playwright-utils wins over playwright-cli — every interaction discovered with the CLI must be translated to library equivalents before writing. The CLI-to-Library mapping table above is the contract.
3. playwright-cli is discovery-only — use it to open pages, take snapshots, run eval for selectors, and read console/network output. Never copy its raw output (page.click(), expect(locator)) into page objects or specs. Translate every interaction before writing, and write the wrapped form directly. Do not stage raw Playwright code to rewrite later. When playwright-cli and the library disagree on a pattern, the library wins, always.

Project Skill Discovery (BLOCKING — do this FIRST, before any other reference)

A repo MAY ship a project router skill: a SKILL.md under .claude/skills/ whose directory name is NOT a distributed common skill {anaconda-playwright-utils, playwright-cli, qa-automation-quality}. It encodes this repo's navigation, auth, feature-flag, known-locator, and planning context and usually exposes an Intent-routing table. On conflict it OVERRIDES library/tool defaults.

Run once, before you explore, survey coverage, plan, write, or diagnose:

1. Glob .claude/skills/*/SKILL.md.
2. Identify the project router = any matched skill whose directory name is NOT in the common-skill set above.
   • If CLAUDE.md / AGENTS.md names a "load first" project skill, that name wins.
   • Exactly one non-common skill → that is the router.
   • Several → pick the one whose description / Intent-routing best matches your task; load others only if its routing points to them.
   • None → record "Project skill: none found" and proceed with common skills only.
3. Load the project router SKILL.md FIRST and follow its Intent-routing: pick the row matching your task and load the FIRST reference it names before anything else — planning → its planning-context reference; navigation / test runs → its repo-structure reference; writing code → anaconda-playwright-utils; auth → its login-flow reference; feature flags → its feature-flag reference.
4. Do NOT Glob tests/, open a browser, Write, or Edit until the router is loaded (and its first routed reference read) or "none found" is recorded.

Project-agnostic: never hardcodes a router name, derives the project skill by EXCLUDING the shipped common skills, degrades cleanly to "none found".

When to Load a Reference

The tables above are sufficient for most test generation — function names, signatures, and the CLI mapping are all here. Load a references/*.md file only when you need exact option types, return shapes, or worked page-object examples for that module:

• references/actions.md — drag/upload/alert flows, or unusual click/fill options (stable, onlyVisible)
• references/assertions.md — choosing hard vs soft assertions; attribute, count, and alert assertions
• references/locators.md — 9-tier priority, tile/card link scoping, ancestor/duplicate-test-id patterns, locator field conventions (the planner, generator, and healer each load this before their locator work); pair with .claude/skills/playwright-cli/references/element-attributes.md § Step 1–3 (locator discovery)
• references/element-utils.md — extracting data, conditional checks, explicit waits
• references/api-utils.md — the test makes HTTP requests
• references/page-utils.md — multi-tab flows, storage state, manual navigation control
• references/browser-strategy.md — before exploring an unfamiliar page (playwright-cli snapshot vs WebFetch)