API Reference Overview

Complete reference for Playwright Test API including test functions, fixtures, and configuration

API Reference Overview

Playwright Test provides a comprehensive API for writing and running end-to-end tests. This reference covers the core APIs, fixtures, and configuration options available.

Core Test API

The test API is the foundation of Playwright Test. It provides functions for defining tests, organizing them into suites, and managing test execution.

Main Functions

• test() - Define a test case
• test.describe() - Group tests into a suite
• test.beforeEach() - Run setup before each test
• test.afterEach() - Run cleanup after each test
• test.beforeAll() - Run setup once before all tests
• test.afterAll() - Run cleanup once after all tests

Test Modifiers

• test.skip() - Skip a test
• test.only() - Run only this test
• test.fixme() - Mark a test as broken
• test.fail() - Expect a test to fail
• test.slow() - Mark a test as slow

Advanced Features

• test.step() - Create a custom test step
• test.use() - Override fixtures for a file
• test.extend() - Add custom fixtures
• test.info() - Get current test information

Fixtures

Playwright Test uses fixtures to establish the test environment. Fixtures are automatically set up and torn down for each test.

Built-in Fixtures

• Test Fixtures - Fixtures available to each test (page, context, request, agent)
• Worker Fixtures - Fixtures shared across tests (browser, playwright)

Fixture Types

interface PlaywrightTestArgs {
  page: Page;
  context: BrowserContext;
  request: APIRequestContext;
  agent: PageAgent;
}

interface PlaywrightWorkerArgs {
  browser: Browser;
  playwright: typeof import('playwright-core');
}

Configuration

Playwright Test is configured through a configuration file that defines how tests are run, which browsers to use, and various other options.

Configuration Options

• Test Config - Main configuration interface
• Project Config - Per-project configuration
• Use Options - Browser and context options

Key Configuration Areas

• Test execution - workers, timeout, retries, fullyParallel
• Browser options - browserName, headless, channel, launchOptions
• Context options - viewport, baseURL, storageState, permissions
• Recording options - screenshot, video, trace
• Reporting - reporter, reportSlowTests

Common Patterns

Basic Test

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

test('basic test', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example/);
});

Test with Custom Fixtures

import { test as base } from '@playwright/test';

const test = base.extend<{ userName: string }>({
  userName: async ({}, use) => {
    await use('testuser');
  },
});

test('test with custom fixture', async ({ page, userName }) => {
  await page.goto(`/user/${userName}`);
});

Grouped Tests

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

test.describe('feature tests', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/feature');
  });

  test('feature works', async ({ page }) => {
    await expect(page.getByRole('heading')).toBeVisible();
  });

  test('feature handles input', async ({ page }) => {
    await page.getByRole('textbox').fill('test');
  });
});

Type Definitions

Playwright Test is written in TypeScript and provides complete type definitions. Import types from @playwright/test:

import type {
  TestType,
  TestInfo,
  PlaywrightTestArgs,
  PlaywrightTestOptions,
  PlaywrightWorkerArgs,
  PlaywrightWorkerOptions,
  Fixtures,
} from '@playwright/test';

Next Steps

• Explore the Test API for detailed method documentation
• Learn about Test Fixtures and available fixtures
• Configure your tests with Test Config
• Review examples in the Guides section