DEV Community

Cover image for Introducing Playwright Labs: Best Practices as Code
Vitali Haradkou
Vitali Haradkou

Posted on

Introducing Playwright Labs: Best Practices as Code

#playwright #ai #typescript #testing

What is Playwright Labs?

Playwright Labs is a curated monorepo of skills and best practices designed specifically for modern testing workflows. Think of it as a knowledge base that integrates seamlessly with your development environment, providing contextual guidance powered by AI and LLM agents.

The first package in this collection is playwright-best-practices - a comprehensive guide to writing better, faster, and more reliable Playwright tests.

Video Overview

Watch this quick introduction to Playwright Labs and learn how to get started:

Why Playwright Labs?

Testing best practices are often scattered across documentation, blog posts, and tribal knowledge. Playwright Labs solves this by:

  • 📚 Centralized Knowledge - All best practices in one structured repository
  • 🤖 AI-Optimized - Formatted specifically for LLM consumption and agent workflows
  • 🎯 Impact-Driven - Practices ranked by their impact on test quality
  • 🔄 Always Updated - Community-driven and version-controlled
  • 💻 Code-First - Every rule includes practical code examples

The playwright-best-practices Package

This package contains 8 categories of Playwright best practices, each with multiple rules and examples:

1. Test Stability & Reliability (CRITICAL)

Focus on eliminating flaky tests and ensuring consistent results.

2. Test Execution Speed (CRITICAL)

Optimize test performance for faster feedback loops.

3. Locator Best Practices (HIGH)

Master element selection strategies for robust tests.

4. Assertions & Waiting (HIGH)

Learn proper synchronization and validation techniques.

5. Parallel Execution (MEDIUM-HIGH)

Harness the power of parallel test execution.

6. Fixtures & Test Organization (MEDIUM)

Structure tests for maintainability and reusability.

7. Debugging & Maintenance (MEDIUM)

Streamline troubleshooting and test maintenance.

8. Advanced Patterns (LOW)

Explore advanced techniques for complex scenarios.

Installation

The package uses a unique installation method optimized for skill packages:

# Install via pnpx
pnpx add-skill https://github.com/vitalics/playwright-labs/tree/main/packages/playwright-best-practices
Enter fullscreen mode Exit fullscreen mode

This command integrates the best practices directly into your development environment, making them accessible to AI coding assistants and LLM agents.

Repository Structure 

packages/
└── playwright-best-practices/
    ├── rules/
    │   ├── stable-use-waitfor.md          # CRITICAL: Wait for elements
    │   ├── stable-avoid-timeouts.md       # Avoid hardcoded timeouts
    │   ├── speed-parallel-tests.md        # Enable parallel execution
    │   ├── locator-use-role.md            # Prefer role-based selectors
    │   ├── assertion-use-expect.md        # Use proper assertions
    │   └── ...                            # More rules...
    ├── src/
    │   ├── build.ts                       # Compile rules to AGENTS.md
    │   ├── validate.ts                    # Rule compliance checker
    │   └── extract-tests.ts               # Test case extractor
    ├── AGENTS.md                          # Auto-generated compiled output
    ├── metadata.json                      # Package metadata
    ├── test-cases.json                    # LLM evaluation tests
    ├── package.json
    └── README.md
Enter fullscreen mode Exit fullscreen mode

Rule Format

Each rule follows a standardized format designed for both human and machine readability:

---
title: "Use proper waits instead of timeouts"
impact: CRITICAL
description: "Avoid hardcoded sleeps and use Playwright's built-in waiting"
tags: [stability, waiting, async]
---

## Problem

Using hardcoded timeouts makes tests slow and unreliable.

❌ **Bad:**
\`\`\`typescript
await page.goto('https://example.com')
await new Promise(resolve => setTimeout(resolve, 5000)) // Bad!
await page.click('button')
\`\`\`

✅ **Good:**
\`\`\`typescript
await page.goto('https://example.com')
await page.waitForLoadState('networkidle')
await page.click('button')
\`\`\`

## Why

Playwright has built-in auto-waiting that makes tests faster and more reliable.
Enter fullscreen mode Exit fullscreen mode

Frontmatter Metadata

  • title - Clear, actionable rule name
  • impact - CRITICAL, HIGH, MEDIUM-HIGH, MEDIUM, or LOW
  • description - Optional detailed explanation
  • tags - Searchable categories

Key Best Practices Highlights

Let me share some of the most impactful practices from the package:

1. Use Built-in Auto-Waiting

Playwright automatically waits for elements to be ready. Don't fight it:

// ❌ Manual waiting
await page.waitForSelector("button");
await page.click("button");

// ✅ Auto-waiting (preferred)
await page.click("button"); // Automatically waits for button to be actionable
Enter fullscreen mode Exit fullscreen mode

2. Prefer Role-Based Selectors

Use accessible locators for robust tests:

// ❌ Fragile CSS selectors
await page.click(".btn-primary");

// ✅ Semantic role selectors
await page.getByRole("button", { name: "Submit" }).click();
Enter fullscreen mode Exit fullscreen mode

3. Use Test Fixtures

Organize common setup with fixtures:

// Define fixture
export const test = base.extend<{ authenticatedPage: Page }>({
  authenticatedPage: async ({ page }, use) => {
    await page.goto("/login");
    await page.fill('[name="username"]', "testuser");
    await page.fill('[name="password"]', "password");
    await page.click('button[type="submit"]');
    await use(page);
  },
});

// Use in tests
test("user dashboard", async ({ authenticatedPage }) => {
  await authenticatedPage.goto("/dashboard");
  await expect(authenticatedPage.getByText("Welcome")).toBeVisible();
});
Enter fullscreen mode Exit fullscreen mode

4. Enable Parallel Execution

Maximize test speed with parallelization:

export default defineConfig({
  // Run tests in parallel across 4 workers
  workers: process.env.CI ? 2 : 4,

  // Fully parallel execution mode
  fullyParallel: true,

  // Retry failed tests
  retries: process.env.CI ? 2 : 0,
});
Enter fullscreen mode Exit fullscreen mode

5. Use Proper Assertions

Playwright provides auto-retrying assertions:

// ❌ Manual checks (no retry)
const text = await page.locator(".status").textContent();
expect(text).toBe("Success");

// ✅ Auto-retrying assertions
await expect(page.locator(".status")).toHaveText("Success");
Enter fullscreen mode Exit fullscreen mode

Impact Levels Explained

Rules are categorized by their impact on test quality:

Impact Level Description Focus Area
CRITICAL Major improvements to stability or speed Must implement
HIGH Significant quality improvements High priority
MEDIUM-HIGH Notable benefits with some effort Recommended
MEDIUM Incremental improvements Nice to have
LOW Advanced patterns for specific cases Optional

This prioritization helps teams focus on high-value practices first.

How AI Agents Use This

The package is optimized for LLM consumption through:

  1. Structured Format - Consistent markdown with clear sections
  2. AGENTS.md - Compiled single-file output for easy ingestion
  3. Metadata - JSON metadata for programmatic access
  4. Test Cases - Evaluation data for LLM fine-tuning
  5. Clear Examples - Before/after code comparisons

AI coding assistants can:

  • Suggest best practices contextually
  • Detect anti-patterns in your code
  • Provide refactoring suggestions
  • Generate test code following best practices

Real-World Benefits

Teams using these practices report:

  • 50-70% reduction in flaky tests
  • 30-40% faster test execution
  • Improved maintainability - easier to update tests
  • Better debugging - clearer failure messages
  • Increased confidence - reliable CI/CD pipelines

What's Next for Playwright Labs?

The monorepo is designed for growth. Future packages might include:

  • playwright-api-testing - Best practices for API testing
  • playwright-mobile - Mobile testing patterns
  • playwright-performance - Performance testing techniques
  • playwright-accessibility - A11y testing guidelines
  • playwright-visual - Visual regression testing

Contributing

Playwright Labs is open-source and community-driven. You can contribute by:

  1. Adding new rules - Share your hard-earned lessons
  2. Improving existing rules - Better examples and explanations
  3. Reporting issues - Found a problem? Let us know
  4. Creating packages - New skill packages are welcome

Check out the repository: github.com/vitalics/playwright-labs

Conclusion

Playwright Labs represents a new way of sharing and learning best practices - one that's optimized for both human developers and AI assistants. The playwright-best-practices package is just the beginning.

By installing this skill package, you're not just getting documentation - you're getting an AI-powered testing advisor that helps you write better tests from day one.

Key Takeaways:

  • ✅ 8 categories covering all aspects of Playwright testing
  • ✅ Impact-ranked practices for focused improvements
  • ✅ AI-optimized format for intelligent tooling
  • ✅ Open-source and community-driven
  • ✅ Easy installation via pnpx add-skill

Ready to level up your Playwright testing? Install the skill package and let AI-powered best practices guide your testing journey!

pnpx add-skill https://github.com/vitalics/playwright-labs/tree/main/packages/playwright-best-practices
Enter fullscreen mode Exit fullscreen mode

Resources

Happy testing! 🎭

Made with ❤️ by Vitali!

Top comments (0)