Playright

0.0.22 verified Sat Apr 25 auth: no javascript

Playright is a user-oriented test wrapper for Playwright, porting Selenide/Selene patterns from the Selenium world. At version 0.0.22, it is an early-stage experimental API with release cadence TBD. Key differentiators: fluent API with 'element', 'elements', 'perform', 'have' helpers; supports multi-context/browser/page tests; ships TypeScript types. Unlike raw Playwright, it provides a higher-level declarative style inspired by Selenide, but is still in very early draft and not production-ready.

Common errors

error TypeError: Cannot read properties of undefined (reading 'page') ↓

cause Trying to use goto or element without first calling director.assign() or disposing previous context.

fix

Ensure director.assign is called in beforeAll and director.dispose in afterEach/afterAll.

error Error: When using director, you must first call director.assign() ↓

cause director is used before initialization.

fix

Move director.assign() to the start of the test suite.

Warnings

breaking Early draft: API is unstable and may change without notice in minor version bumps (0.x). ↓

fix Pin exact version and expect breaking changes.

gotcha director.assign must be called before any other API calls (like goto). If not assigned, default settings are used but can lead to unexpected states. ↓

fix Always call director.assign with desired options at the start of the test or beforeAll.

gotcha The 'element' function does not support chaining on elements other than the first one; to filter use elements().by() or elements().firstBy(). ↓

fix Use elements() with methods like .by(), .first(), .element(index) for collection operations.

deprecated As of v0.0.22, there is no dedicated warning system; check CHANGELOG for deprecations. ↓

fix Watch GitHub releases and CHANGELOG.

Install

npm install playright

yarn add playright

pnpm add playright

Imports

director
wrong
```
const director = require('playright').director
```
correct
```
import { director } from 'playright'
```
ESM-only; director is a named export that manages browser, context, and page lifecycle
element
```
import { element } from 'playright'
```
Named export for locating a single element by CSS selector
elements
```
import { elements } from 'playright'
```
Named export for locating multiple elements by CSS selector
goto
```
import { goto } from 'playright'
```
Named export to navigate the current page to a URL
perform
```
import { perform } from 'playright'
```
Named export containing actions like press, click, etc.
have
```
import { have } from 'playright'
```
Named export for assertions such as texts, cssClass, count, etc.
stage
```
import { stage } from 'playright'
```
Named export for managing test stages or contexts

Quickstart

Shows basic Playright API: director setup, navigating, typing, chaining actions with perform, and asserting with have on element collections.

import { director, goto, element, elements, perform, have } from 'playright';

describe('TodoMVC', () => {
  beforeAll(async () => {
    jest.setTimeout(60 * 1000);
    director.assign({ launchOptions: { headless: false } }); // true by default
  });
  afterEach(async () => {
    await director.dispose();
  });

  it('should complete todo', async () => {
    await goto('http://todomvc.com/examples/emberjs');
    await element('#new-todo').type('a').then(perform.press('Enter'));
    await element('#new-todo').type('b').then(perform.press('Enter'));
    await elements('#todo-list li').should(have.texts('a', 'b'));

    await elements('#todo-list li').first.element('.toggle').click();
    await elements('#todo-list li').by(have.cssClass('completed')).should(have.texts('a'));
  });
});