Review

What Is Review?

The Review skill is a Claude Code extension designed to automate and standardize the review of Playwright end-to-end test code. Integrated as part of a broader workflow for engineering teams, Review systematically examines Playwright test files, identifying anti-patterns, missed best practices, and potential coverage gaps. By leveraging a curated set of rules and checks, it assists developers in maintaining high-quality, maintainable, and reliable test suites.

Why Use Review?

As teams scale their test automation efforts with Playwright, maintaining consistent test quality becomes increasingly challenging. Manual code reviews for Playwright tests are often inconsistent and time-consuming, leading to missed issues and technical debt. Review addresses these challenges by:

• Automating the detection of critical test anti-patterns that can lead to unreliable or slow tests.
• Enforcing Playwright best practices across all test files, regardless of team size or project maturity.
• Highlighting code smells and maintainability issues before they reach production.
• Reducing the burden on manual reviewers, allowing them to focus on higher-level feedback and architectural concerns.

By integrating Review into your development workflow, you can ensure that all test code adheres to a consistent standard, reducing flakiness and improving overall confidence in your end-to-end test suite.

How to Get Started

To begin using the Review skill, follow these steps:

1. Install and Configure

   • Clone or download the skill from the official repository.
   • Ensure your project contains Playwright test files (*.spec.ts or *.spec.js) and a valid playwright.config.ts.

2. Triggering a Review

   • You can invoke the Review skill using natural language prompts such as "review tests", "check test quality", or "audit tests".
   • Alternatively, specify a file or directory as an argument:
     plaintext

     review path/to/test.spec.ts
     review tests/
     review

     If no argument is provided, the skill defaults to the test directory configured in your playwright.config.ts.

3. Execution Flow

   • Review will read the Playwright configuration, identify the scope of test files, and analyze them one by one.
   • For single-file reviews, it will also gather context from related page objects and fixtures for a comprehensive assessment.

Key Features

Comprehensive Anti-Pattern Detection

Review scans each Playwright test file for a curated set of 20 anti-patterns, sourced from real-world experience and Playwright best practices. The anti-patterns are categorized by severity:

• Critical (Must Fix): These include issues like the use of waitForTimeout(), missing await on Playwright calls, hardcoded URLs, reliance on non-web-first assertions, and shared mutable state across tests.
• Warning (Should Fix): These include tests that are too long, overuse of magic strings, missing edge-case coverage, excessive nesting of test.describe(), and generic test names.

Example – Detecting a Critical Anti-Pattern:

test('waits for element', async ({ page }) => {
  await page.goto('/dashboard');
  await page.waitForTimeout(2000); // Detected as a critical anti-pattern
  await expect(page.locator('.item')).toBeVisible();
});

Review flags the direct use of waitForTimeout() and recommends using web-first assertions instead.

Contextual Awareness

The skill reads the Playwright configuration and considers project-wide settings such as testDir and baseURL. When reviewing a single file, it also examines related page objects and fixtures to provide targeted feedback.

Automated Reporting

Results are presented with actionable recommendations, distinguishing between critical issues that must be fixed and warnings that should be addressed for maintainability.

Flexible Scope

You can apply Review to a single file, a whole directory, or your entire suite, enabling both targeted audits and broad quality sweeps.

Best Practices

To maximize the effectiveness of the Review skill, consider the following guidelines:

• Run Review as part of your CI pipeline to enforce quality gates before merging code.
• Address critical issues immediately; these often lead to flaky or unreliable tests if left unresolved.
• Refactor tests based on warnings to improve readability, maintainability, and future scalability.
• Use named constants for magic strings and prefer role-based selectors over brittle CSS or XPath selectors.
• Keep tests focused and concise; if a test exceeds 50 lines, split it for clarity and modularity.
• Ensure all Playwright API calls are properly awaited to avoid race conditions and unpredictable behavior.

Example – Improving a Warning:

// Before: Generic test name and magic string
test('should work', async ({ page }) => {
  await page.goto('/login');
  await expect(page.locator('#submit')).toBeEnabled();
});

// After: Descriptive name and named constant
const LOGIN_URL = '/login';

test('should enable the submit button on the login page', async ({ page }) => {
  await page.goto(LOGIN_URL);
  await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();
});

Important Notes

• Review is not a substitute for human judgment. While it covers a wide range of anti-patterns and best practices, complex test logic and edge cases may still require manual review.
• False positives may occur if code intentionally deviates from best practices for a valid reason. Use the tool’s recommendations as guidance, not as absolute rules.
• Custom anti-patterns can be added by extending the anti-patterns.md file in the skill directory to reflect team-specific standards.
• Review currently focuses on Playwright tests; for other frameworks or broader codebase checks, use complementary tools.
• Continuous improvement: Regularly update the skill and anti-pattern definitions to keep pace with evolving Playwright capabilities and team requirements.

Integrating the Review skill into your workflow will help you enforce consistent, high-quality Playwright tests, reduce maintenance overhead, and build a more robust automation strategy.