Workflow:Microsoft Playwright End to end test authoring
| Knowledge Sources | |
|---|---|
| Domains | Web_Testing, Test_Automation, Cross_Browser |
| Last Updated | 2026-02-11 22:00 GMT |
Overview
End-to-end process for writing, configuring, and running cross-browser web application tests using the Playwright Test framework.
Description
This workflow covers the standard procedure for authoring automated end-to-end tests with Playwright. It starts from project initialization, through test configuration for multiple browsers and devices, to writing test files using the Playwright Test runner's built-in fixtures, locators, and assertions. The process encompasses defining test suites with describe blocks, selecting elements with role-based and text-based locators, and verifying application state with auto-retrying web-first assertions. Tests can target Chromium, Firefox, and WebKit simultaneously through project configuration.
Usage
Execute this workflow when you need to create a new end-to-end test suite for a web application, or add tests to an existing Playwright project. This applies when you have a web application accessible via URL and need to verify user-facing behavior across one or more browsers.
Execution Steps
Step 1: Project initialization
Initialize a new Playwright project using the init command or by manually installing the @playwright/test package. This scaffolds the project with a configuration file, example tests, and optionally a GitHub Actions workflow for CI. Browser binaries are downloaded during installation.
Key considerations:
- Choose between npm init playwright@latest for scaffolding or manual npm i -D @playwright/test for existing projects
- Run npx playwright install to download required browser binaries
- The init command creates a playwright.config.ts and example spec file
Step 2: Test configuration
Configure the test runner through playwright.config.ts, defining global settings (timeouts, retries, base URL) and browser projects. Each project specifies a browser (Chromium, Firefox, WebKit) and optional device emulation. Configure reporters (HTML, JSON, JUnit), trace collection strategy, and parallelism settings.
Key considerations:
- Define separate projects for each browser/device combination
- Use testDir to specify where test files live
- Configure trace: 'on-first-retry' for debugging failed tests
- Set workers count for parallel execution
- Use baseURL to avoid hardcoding URLs in tests
Step 3: Test file creation
Create test files following the .spec.ts naming convention. Structure tests using test.describe() for logical grouping and test() for individual test cases. Use Playwright's built-in page fixture which provides a fresh browser context per test for full isolation.
Key considerations:
- Each test receives an isolated browser context by default
- Use test.beforeEach() and test.afterEach() for shared setup and teardown
- Organize related tests under test.describe() blocks
- Test files must import from @playwright/test
Step 4: Element location and interaction
Locate page elements using Playwright's locator API, which provides resilient element selection through role-based, text-based, and test-ID-based strategies. Interact with elements using action methods (click, fill, press, check) which auto-wait for elements to be actionable.
Key considerations:
- Prefer getByRole(), getByText(), and getByTestId() over CSS selectors
- Locators auto-wait for elements to be visible and enabled before acting
- Chain locators with .filter() and .locator() for precise targeting
- Use page.goto() for navigation
Step 5: Assertion and verification
Verify application state using Playwright's web-first assertions, which automatically retry until the expected condition is met or a timeout is reached. Assert element visibility, text content, URL state, input values, and more.
Key considerations:
- Use expect(locator).toBeVisible(), toHaveText(), toHaveValue() for element assertions
- Assertions auto-retry, eliminating the need for manual waits
- Use expect(page).toHaveURL() for navigation verification
- Array assertions with toHaveText([...]) verify lists of elements
Step 6: Test execution and reporting
Run the test suite using the Playwright CLI, targeting specific browsers, test files, or grep patterns. Review results through the HTML reporter, which provides a visual dashboard of passed, failed, and skipped tests with trace attachments for debugging failures.
Key considerations:
- Run npx playwright test to execute all tests across configured projects
- Use --project=chromium to target a specific browser
- Use --grep to filter tests by name pattern
- Run npx playwright show-report to view the HTML report
- Traces and screenshots are automatically attached to failed test reports