Playwright-elements

Playwright-elements is a powerful testing framework that extends Playwright with:

• Reusable Components - Build hierarchical UI components with child elements
• Type Safety - Full TypeScript support with branded types for test IDs
• Chainable API - Fluent interface mixing selectors with synchronous methods
• Test ID System - Type-safe, collision-resistant test ID generation with production stripping
• Page Object Pattern - Clean architecture for maintainable tests

Installation

npm install -D playwright-elements

For projects that only need test ID generation without Playwright:

npm install -D @playwright-elements/testids

Quick Start

import { $, test } from 'playwright-elements';

const loginForm = $('.login-form').with({
  username: $('input[name="username"]'),
  password: $('input[name="password"]'),
  submit: $('button[type="submit"]'),
  async login(user: string, pass: string) {
    await this.username.fill(user);
    await this.password.fill(pass);
    await this.submit.click();
  }
});

test('user login', async ({ goto }) => {
  await goto('/login');
  await loginForm.login('admin', 'password123');
  await loginForm.submit.expect().toBeVisible();
});

🏗️ Core Concepts

Component Hierarchy

Create nested component structures that mirror your application's DOM:

// Multi-level component structure
const app = $('.app').with({
  header: $('.header').with({
    logo: $('.logo'),
    navigation: $('.nav').with({
      items: $('.nav-item')
    })
  }),
  main: $('.main-content'),
  footer: $('.footer')
});

// Usage in tests
await app.header.navigation.items.first().click();

Type-Safe Test IDs

Prevent selector typos and ensure type safety across your entire test suite using branded types:

import { factory, sid, bareFactory, $byTestId, testIdProps, assertNoPrefixCollisions } from 'playwright-elements';

// Define typed IDs with branded types for compile-time safety
const ids = {
  login: {
    username: sid<'login.username'>('username-input'),
    password: sid<'login.password'>('password-input'),
  },
  button: factory<'button'>('btn')
} as const;

// Validate no prefix collisions at module load time
assertNoPrefixCollisions(ids);

// Use in React/Vue/Angular components
function MyComponent() {
  return <input {...testIdProps(ids.login.username)} />;
}

// Use in tests
const usernameField = $byTestId(ids.login.username);
await usernameField.fill('admin');

// bareFactory for entity-based IDs (no prefix)
const ruleRow = bareFactory<'rules.row'>();
// Usage: ruleRow(123) -> TestId<'rules.row'> with value '123'

Benefits of Branded Types:

• Compile-time safety: TypeScript prevents mixing IDs from different categories
• Autocompletion: IDE suggests available IDs with correct types
• Refactoring support: Change ID types in one place, errors appear throughout
• Zero runtime overhead: All types are erased at compile time

Zero-dependency import: For projects that only need the test IDs module without Playwright dependencies:

Option 1 — Standalone package (recommended for unit tests and production code):

npm install -D @playwright-elements/testids

import { sid, factory, bareFactory, testIdProps } from '@playwright-elements/testids';

This installs a separate package with zero runtime dependencies — no Playwright, no lodash in node_modules.

Option 2 — Subpath re-export (backward compatible):

import { sid, factory, bareFactory, testIdProps } from 'playwright-elements/testids';

This has zero import-time dependencies (loads no Playwright at runtime) but still installs the full playwright-elements package.

Advanced Component Methods

The .with() method supports both elements and methods for complete component encapsulation:

const loginForm = $('.login-form').with({
  // Child elements
  username: $('input[name="username"]'),
  password: $('input[name="password"]'),
  submit: $('button[type="submit"]'),
  
  // Methods for component actions
  async login(user: string, pass: string) {
    await this.username.fill(user);
    await this.password.fill(pass);
    await this.submit.click();
  }
});

// Usage
await loginForm.login('admin', 'password123');

Browser and Page Management

Access the current page and context through BrowserInstance:

import { BrowserInstance, $, usePage, test } from 'playwright-elements';

// Get the current page
const currentPage = BrowserInstance.currentPage;

// Check if running in mobile context (uses Playwright's public isMobile fixture)
if (BrowserInstance.isContextMobile) {
  // Mobile-specific logic
}

// Use with custom pages - execute code in specific page context
const result = await usePage(customPage, async () => {
  // All playwright-elements operations here use the provided page
  const element = $('.my-element');
  await element.click();
  return await element.textContent();
});

// In Playwright Test, isContextMobile is automatically set from the test fixture
test.use({ ...devices['iPhone 13'] });
test('mobile test', async ({}) => {
  // BrowserInstance.isContextMobile will be true
});

Assertion Configuration

WebElement provides seamless integration with @playwright/test assertions. No configuration needed!

Automatic Setup

When importing from 'playwright-elements', assertions work automatically:

import { test } from 'playwright-elements';

test('my test', async ({}) => {
  // Works automatically
  await $('.element').expect().toBeVisible();
  await $('.element').softExpect().toBeVisible();
});

Custom Matchers

Extend Playwright's expect with custom matchers - they will work automatically with WebElement:

import { expect } from '@playwright/test';
import { test } from 'playwright-elements';
import { $ } from 'playwright-elements';

// Extend expect with custom matcher
expect.extend({
  async toHaveCustomValue(locator, expected) {
    const actual = await locator.getAttribute('data-custom');
    return {
      pass: actual === expected,
      message: () => `Expected custom value to be ${expected}, but got ${actual}`
    };
  }
});

test('custom matcher', async ({ goto }) => {
  await goto('/');
  // Custom matcher works with full TypeScript autocomplete
  await $('.element').expect().toHaveCustomValue('test');
});

How it works: WebElement.expect() directly uses @playwright/test's expect, so any matchers added via expect.extend() are automatically available.

Advanced Selectors

Filter elements by text and other criteria:

// Filter by text content
const items = $('.item').filter({ hasText: 'Product' });

// Get all matching elements
const allButtons = $('.button').getAll();

// Chain filters
const visibleProducts = $('.product')
  .filter({ hasText: /Product/ })
  .filter({ isVisible: true });

Accessing Underlying Playwright Locator

Every WebElement has a .locator property that provides access to the underlying Playwright Locator. Use this to access Playwright methods not directly exposed by WebElement:

// Access the underlying Playwright Locator
const element = $('.my-element');
const locator = element.locator;

// Use Playwright methods directly
const value = await locator.evaluate((el) => el.getAttribute('data-value'));
const boundingBox = await locator.boundingBox();
const screenshot = await locator.screenshot();

// Or use the shorthand alias
const result = await element._.evaluate((el) => el.textContent);

Common use cases:

• Measuring element geometry with boundingBox()
• Reading computed styles with evaluate()
• Taking element screenshots with screenshot()
• Accessing multi-node relationships in one round trip

Utility Functions

Generate index files and initialize test environments:

import { generateIndexFile, initDesktopOrMobile } from 'playwright-elements';

// Generate index.ts files in a directory
generateIndexFile('./test', { watch: false });

// Initialize test environment for desktop or mobile
initDesktopOrMobile('desktop');

Use the CLI for index generation:

npx generate-index ./test

Page Object Pattern

Traditional page object approach with automatic instantiation:

// pages/loginPage.ts
import { $ } from 'playwright-elements';

export class LoginPage {
  readonly header = $('.header').with({
    logo: $('.header-logo'),
    avatar: $('.avatar')
  });
  
  readonly form = $('.login-form').with({
    usernameInput: $('input[name="username"]'),
    passwordInput: $('input[name="password"]'),
    loginButton: $('button[type="submit"]'),
    async fillForm(userName: string, password: string) {
      await this.usernameInput.fill(userName);
      await this.passwordInput.fill(password);
      await this.loginButton.click();
    }
  });
}

// fixtures.ts
import { test as baseTest, buildPageObject, PageObject } from 'playwright-elements';
import * as pageObjectModule from '../pages';

type TestFixtures = { pageObject: PageObject<typeof pageObjectModule> };

export const test = baseTest.extend<TestFixtures>({
  pageObject: [async ({}, use) => {
    // IMPORTANT: First parameter MUST use object destructuring pattern
    // async (_deps, use) => { ... } will fail at collection time
    await use(buildPageObject(pageObjectModule));
  }, { scope: 'test' }],
});

// test.ts
test('check login page', async ({ pageObject }) => {
  await pageObject.login.form.fillForm('UserName', 'Pass!');
  await pageObject.login.header.logo.expect().toBeVisible();
  await pageObject.login.header.avatar.expect().toBeVisible();
});

Type-Safe Test IDs with playwright-elements

Use type-safe test IDs with playwright-elements component structure:

// testIds.ts
import { factory, sid } from 'playwright-elements';

export const ids = {
  login: {
    usernameInput: sid<'login.username'>('username-input'),
    passwordInput: sid<'login.password'>('password-input'),
    submitButton: sid<'login.submit'>('submit-button'),
  },
  header: {
    logo: sid<'header.logo'>('header-logo'),
  },
} as const;

// components/LoginForm.tsx
import { testIdProps } from 'playwright-elements';
import { ids } from '../testIds';

export function LoginForm() {
  return (
    <form>
      <input {...testIdProps(ids.login.usernameInput)} type="text" />
      <input {...testIdProps(ids.login.passwordInput)} type="password" />
      <button {...testIdProps(ids.login.submitButton)} type="submit">Login</button>
    </form>
  );
}

// elements.ts - define component structure using test IDs
import { $, $byTestId } from 'playwright-elements';
import { ids } from './testIds';

export const loginForm = $('.form-login').with({
  usernameInput: $byTestId(ids.login.usernameInput),
  passwordInput: $byTestId(ids.login.passwordInput),
  submitButton: $byTestId(ids.login.submitButton),
  async login(username: string, password: string) {
    await this.usernameInput.fill(username);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
});

export const header = $('.app-header').with({
  logo: $byTestId(ids.header.logo)
});

// tests/login.spec.ts
import { test } from 'playwright-elements';
import { loginForm, header } from '../elements';

test('login form submission', async ({ goto }) => {
  await goto('/login');
  await loginForm.login('admin', 'password123');
  await header.logo.expect().toBeVisible();
});

See Test IDs Module for complete documentation.

🎯 Use Cases

✅ When to Use playwright-elements:

• Complex Applications with many reusable components
• Teams needing maintainable, type-safe test code
• Large Test Suites requiring clean architecture
• React/Vue/Angular applications with component-driven testing
• Migration from Selenium or other frameworks

❌ When NOT to Use:

• Simple scripts or one-off tests
• Projects already committed to pure Playwright
• Non-TypeScript projects (limited benefit)

Documentation

| Section | Description | |---------|-------------| | Get Started | Installation and basic usage | | Web Element | Complete WebElement API reference | | Test IDs | Type-safe test ID system with production stripping | | Page Objects | Page object pattern guide | | Fixtures | Test fixture configuration | | Browser Management | Advanced browser control | | Architecture | Framework design principles | | Best Practices | Recommended patterns and tips | | Migration Guide | Upgrade instructions | | FAQ | Common questions and solutions |

For version-specific changes and release notes, see the CHANGELOG.