Playwright Rules
A comprehensive guide to Playwright best practices, patterns, and anti-patterns for writing reliable end-to-end tests.
Quick Reference
Locators (Most Important)
| Do | Don't |
|---|---|
getByRole('button', { name: 'Submit' }) | locator('.btn-submit') |
getByTestId('user-avatar') | locator('#avatar-12345') |
getByLabel('Email') | locator('input[type="email"]') |
locator('.item').first() | locator('.item') (when multiple) |
Waits (Critical for Stability)
| Do | Don't |
|---|---|
await expect(el).toBeVisible() | await page.waitForTimeout(1000) |
await page.waitForURL('/dashboard') | await page.waitForLoadState('networkidle') |
await response.finished() | await page.waitForTimeout(500) |
Assertions (Web-First Always)
| Do | Don't |
|---|---|
await expect(locator).toHaveText('Hello') | expect(await locator.textContent()).toBe('Hello') |
await expect(locator).toBeVisible() | expect(await locator.isVisible()).toBe(true) |
await expect(page).toHaveURL('/home') | expect(page.url()).toBe('/home') |
Rule Categories
- •Locators - Finding elements reliably
- •Waits & Timing - Handling async operations
- •Assertions - Verifying outcomes
- •Page Objects - Organizing locators
- •Test Organization - Structuring tests
- •Network - Mocking and interception
- •Debugging - Troubleshooting failures
- •Parallelization - Running tests safely
Usage
In Triqual Workflows
This skill is automatically consulted when:
- •Writing new
.spec.tsfiles - •Debugging flaky tests
- •Reviewing test code
Manual Invocation
code
/rules
In Code Reviews
Reference specific rules:
code
This violates [wait-no-timeout](./rules/wait-no-timeout.md) - use `await expect(element).toBeVisible()` instead of `waitForTimeout`.
All Rules
See rules/_sections.md for the complete index.
Contributing
See rules/_contributing.md for guidelines on adding new rules.