@playwright/test 1.x

Complete instructions

Verified against @playwright/test@1.63.0 on 2026-09-07. 5 of 5 examples executed.

The five historical examples below exercise standalone imports and API shape. They do not run browser tests. The separate runner fixture verifies Chromium interaction, context isolation and custom fixture setup/teardown.

@playwright/test

Scope and package shape

@playwright/test is the Playwright Test runner package. The ^1.0.0 range stays within the 1.x major; the researched npm entry currently shows 1.63.0.

The package entry point re-exports playwright/test and its default export. The main authoring surface is:

import { test, expect } from "@playwright/test";

test(title, body) and test(title, details, body) declare tests. expect(value) provides generic assertions and web-first asynchronous assertions.

Tests are normally executed by the Playwright runner:

npm i -D @playwright/test
npx playwright test

The runner supplies fixtures such as { page }, handles isolation, retries, workers, and reporters, and consumes configuration. A fixture argument is not created merely by calling a test function in an ordinary script.

The common shape mistake

Do not translate older Puppeteer or Jest-style code directly into this package. The older pattern manually launches a browser, creates a page, uses describe/it, and manages lifecycle with hooks. The Playwright Test shape imports test and expect, and receives an isolated fixture from the runner:

import { test, expect } from "@playwright/test";

test("basic test", async ({ page }) => {
  await page.goto("https://playwright.dev/");
  await expect(page).toHaveTitle(/Playwright/);
});

describe, it, beforeAll, and afterAll are not globals supplied to a file run directly with Bun. Do not write a standalone script that expects Playwright Test to inject { page }; put that code in a spec and run it with npx playwright test.

The package is runner-oriented rather than a general standalone browser-automation API. For direct browser automation, the researched alternative is the separate Playwright Library surface, such as playwright.chromium.launch().

Plain-script surface

The following examples are deliberately runnable as independent files with bun example.ts. They do not start the test runner, launch a browser, use the network, or require a config file.

Generic expect

expect can be used for ordinary synchronous assertions without a runner.

import { expect } from "@playwright/test";

const value = { status: "ready", count: 2 };
expect(value.status).toBe("ready");
expect(value.count).toBeGreaterThan(1);
expect(value).toEqual({ status: "ready", count: 2 });

Configuration with defineConfig

defineConfig returns configuration for the Playwright runner. It does not execute the runner in a plain script.

import { strict as assert } from "node:assert";
import { defineConfig } from "@playwright/test";

const config = defineConfig({ fullyParallel: true });
assert.equal(config.fullyParallel, true);

Device descriptors

devices supplies device descriptors for project configuration. The descriptor can be inspected without launching a browser.

import { strict as assert } from "node:assert";
import { devices } from "@playwright/test";

const desktopChrome = devices["Desktop Chrome"];
assert.ok(desktopChrome);
assert.equal(typeof desktopChrome, "object");

Custom fixtures with test.extend

test.extend() creates a test object with custom fixtures. The fixture callback is consumed when the Playwright runner executes a test; creating the extended test object itself is safe in a plain script.

import { strict as assert } from "node:assert";
import { test as base } from "@playwright/test";

const customTest = base.extend<{ account: { username: string } }>({
  account: async ({}, use) => {
    await use({ username: "user" });
  },
});

assert.equal(typeof customTest, "function");
assert.equal(typeof customTest.extend, "function");

A normal fixture-backed spec exports or uses this extended test with the runner:

import { test as base, expect } from "@playwright/test";

export const test = base.extend<{ account: { username: string } }>({
  account: async ({}, use) => {
    await use({ username: "user" });
  },
});

export { expect } from "@playwright/test";

Built-in fixtures include page, context, browser, browserName and request. Their values are prepared by Playwright Test rather than by a direct script. mount belongs to the separate component-testing packages; it is not supplied by the ordinary @playwright/test runner.

Combining test and assertion extensions

mergeTests combines fixture-bearing test objects, while mergeExpects combines assertion libraries. These are composition helpers for runner-oriented test modules.

import { strict as assert } from "node:assert";
import {
  mergeTests,
  mergeExpects,
  test as base,
  expect as baseExpect,
} from "@playwright/test";

const mergedTest = mergeTests(base, base);
const mergedExpect = mergeExpects(baseExpect, baseExpect);

assert.equal(typeof mergedTest, "function");
assert.equal(typeof mergedExpect, "function");

Runner-only operations

Use a Playwright spec and invoke the runner for:

• Tests that receive fixtures such as { page }.
• Browser navigation and web-first assertions involving a page.
• Fixture setup and teardown.
• Retries, workers, isolation, reporters, and test.use().
• Configuration supplied through defineConfig.

The runner can also be invoked with npx playwright test --ui, and its report can be displayed with npx playwright show-report.

Execute the actual runner

Use the installed package's browser revisions. Updating Playwright can require updating its browsers; inspect executable availability before downloading or forcing a different executable. A cached Chromium from another revision is not proof that the selected Playwright version is supported. Use the project's approved browser-install procedure when installation is necessary.

import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  workers: 1,
  retries: 0,
  forbidOnly: true,
  use: { headless: true },
  projects: [{ name: "chromium", use: { browserName: "chromium" } }],
});

Workers and retries are product-specific choices; one worker and no retries keep a bounded verification fixture explicit. Review failed checks before masking them with retries. Await locator actions and web-first assertions. Prefer accessible role/name locators over CSS internals or arbitrary sleep delays.

test("increments the visible count", async ({ page }) => {
  await page.goto("/");
  await page.getByRole("button", { name: "Increment", exact: true }).click();
  await expect(page.getByRole("status")).toHaveText("1");
});

For application navigation, configure baseURL and an owned webServer with a readiness URL, bounded startup timeout and teardown. Do not attach a fixture to an unrelated existing production server. Use page.setContent for a deliberately self-contained DOM/browser fixture; it does not verify application routing, network behavior or deployment assets.

Browser contexts isolate tests. Keep authentication state and credentials out of published fixtures. Custom fixtures bracket their resources around await use and clean up afterward. Inspect the runner report for unexpected, skipped and flaky results, not just a zero process exit code. The current fixture runs two browser tests and separately verifies the recorded lifecycle teardown.

Does not cover

This skill does not cover every matcher, component-testing mount APIs, application authentication, production deployment or the separate playwright library's complete API. Use the actual project environment for routing and end-to-end integration; standalone helpers do not replace the runner.

Sources

• Runner configuration
• Browser installation and revisions
• Test fixtures
• Locators
• Owned web servers