playwright-ts-lib: Instructions file for Claude Code

Project: vasu-playwright-utils

Playwright TypeScript utility library providing reusable helper methods for browser automation and testing.

Build & Run

• Build: npm run build (runs tsc -p tsconfig.build.json, cleans dist/ first)
• Type check: npm run validate (runs tsc --noEmit)
• Clean: npm run clean (removes dist/)
• Full reset: npm run ready (removes dist, node_modules, reinstalls, validates, builds, tests)

Test

• All tests: npm test (Playwright Test)
• Chromium only: npm run test:chromium
• Headed (local dev): npm run local
• Smoke/Regression: npm run test:smoke, npm run test:reg

Lint & Format

• Lint: npm run lint
• Lint fix: npm run lint:fix
• Format: npm run format (Prettier)

Architecture

src/vasu-playwright-lib/
  index.ts              # Main entry, re-exports everything
  utils/
    action-utils.ts     # click, fill, hover, drag, alerts, download, upload
    assert-utils.ts     # expectElement*, expectPage* assertions
    locator-utils.ts    # getLocator, getLocatorByRole/Text/TestId, frames
    element-utils.ts    # getText, isElementVisible, waitForElement*
    page-utils.ts       # setPage/getPage, gotoURL, navigation, switchPage
    api-utils.ts        # getRequest, postRequest, putRequest, deleteRequest
  types/
    optional-parameter-types.ts  # All option types (ClickOptions, FillOptions, etc.)
  constants/            # Timeouts, load state defaults
  setup/                # Test setup helpers, custom logger

Subpath Exports

Consumers can import from the main package or specific subpaths:

import { click, fill } from 'vasu-playwright-utils';
import { click } from 'vasu-playwright-utils/action-utils';
import { expectElementToBeVisible } from 'vasu-playwright-utils/assert-utils';

Coding Conventions

• All exported functions have JSDoc comments
• Functions are async and accept string | Locator as input
• Options use the pattern: options?: XxxOptions (intersection types from Playwright + custom extensions)
• Visibility is enforced by default (onlyVisible: true); callers can opt out with { onlyVisible: false }
• setPage(page) must be called before using any utility functions