DOCSEARCHbyAlgolia
Submit Docs

playwright-skill

repository·main·Indexed 25 days ago

https://github.com/lackeyjb/playwright-skill

A Claude Skill enabling Claude Code to perform autonomous browser automation using Playwright. Version 4.1.0 allows Claude to write, execute, and observe custom automation scripts on-the-fly, providing screenshots and console output for verification. It supports general-purpose automation, visual testing, and smart test management with auto-detection.

Tokens
10.5K
Snippets
31
Records
42
Agent score
85%

What's inside playwright-skill

  1. Install Playwright Skill via Downloaded Release

    main
    1. Download and extract the latest release from GitHub Releases.
    2. Copy only the skills/playwright-skill/ folder to either your global directory (~/.claude/skills/playwright-skill) or your project directory (/path/to/your/project/.claude/skills/playwright-skill).
    3. Navigate to the skill directory and run npm run setup.
    cd ~/.claude/skills/playwright-skill  # or your project path
npm run setup

  2. Install and setup Playwright Skill

    main

    Before using this skill, ensure Playwright is installed in your environment. You can check the installation status and run the setup command within the skill directory to ensure all dependencies are met.

    # Check if Playwright is installed
npm list playwright 2>/dev/null || echo "Playwright not installed"

# Install (if needed)
cd ~/.claude/skills/playwright-skill
npm run setup

  3. Detect running dev servers

    main

    When testing local development environments, you must first identify which servers are running. Use the detectDevServers helper to find active local servers.

    Workflow:

    1. Run the detection command.
    2. If one server is found, use it.
    3. If multiple are found, select the correct one.
    4. If none are found, provide a URL manually.
    cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(servers => console.log(JSON.stringify(servers)))"

  4. Install Playwright Skill as a Standalone Skill (Global)

    main

    If you do not want to use the plugin system, you can install the skill directly into your global Claude skills directory. This makes the skill available everywhere for your user.

    1. Clone the repository to a temporary location.
    2. Copy only the skills/playwright-skill folder to ~/.claude/skills/.
    3. Navigate to the new skill directory and run npm run setup.
    4. Clean up the temporary files.
    # Clone to a temporary location
git clone https://github.com/lackeyjb/playwright-skill.git /tmp/playwright-skill-temp

# Copy only the skill folder to your global skills directory
mkdir -p ~/.claude/skills
cp -r /tmp/playwright-skill-temp/skills/playwright-skill ~/.claude/skills/

# Navigate to the skill and run setup
cd ~/.claude/skills/playwright-skill
npm run setup

# Clean up temporary files
rm -rf /tmp/playwright-skill-temp

  5. Execute a Playwright test script

    main

    To run a custom Playwright automation script, write the script to the /tmp directory and execute it using the skill's run.js entrypoint.

    Example Workflow:

    1. Write your script to /tmp/my-test.js.
    2. Execute it from the skill directory using node run.js followed by the script path.
    cd $SKILL_DIR && node run.js /tmp/playwright-test-page.js

  7. Implement the Page Object Model (POM)

    main

    Encapsulate page-specific logic and locators within classes to improve test maintainability. Create a class that accepts a page object in its constructor, defines locators as properties, and exposes high-level actions as methods.

    // pages/LoginPage.js
class LoginPage {
  constructor(page) {
    this.page = page;
    this.usernameInput = page.locator('input[name="username"]');
    this.passwordInput = page.locator('input[name="password"]');
    this.submitButton = page.locator('button[type="submit"]');
    this.errorMessage = page.locator('.error-message');
  }

  async navigate() {
    await this.page.goto('/login');
  }

  async login(username, password) {
    await this.usernameInput.fill(username);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }

  async getErrorMessage() {
    return await this.errorMessage.textContent();
  }
}

// Usage in test
test('login with valid credentials', async ({ page }) => {
  const loginPage = new LoginPage(page);
  await loginPage.navigate();
  await loginPage.login('user@example.com', 'password123');
  await expect(page).toHaveURL('/dashboard');
});

  8. Install Playwright Skill as a Standalone Skill (Project-Specific)

    main

    To use the skill only within a specific project, install it into that project's local .claude/skills/ directory.

    1. Clone the repository to a temporary location.
    2. Copy only the skills/playwright-skill folder to your project's .claude/skills/ directory.
    3. Navigate to the skill directory and run npm run setup.
    4. Clean up the temporary files.
    # Clone to a temporary location
git clone https://github.com/lackeyjb/playwright-skill.git /tmp/playwright-skill-temp

# Copy only the skill folder to your project
mkdir -p .claude/skills
cp -r /tmp/playwright-skill-temp/skills/playwright-skill .claude/skills/

# Navigate to the skill and run setup
cd .claude/skills/playwright-skill
npm run setup

# Clean up temporary files
rm -rf /tmp/playwright-skill-temp

  9. Use Playwright Skill for Browser Automation

    main

    Once installed, you can use the skill by describing browser tasks in natural language. Claude will write custom Playwright code, execute it using the universal executor (run.js), and return results including console output and screenshots.

    Common Task Examples:

    • Page Testing: "Test the homepage", "Check if the contact form works".
    • Visual Testing: "Take screenshots of the dashboard in mobile and desktop".
    • Interaction Testing: "Fill out the registration form and submit it".
    • Validation: "Check for broken links", "Verify all images load".

  10. Install Playwright Skill via Claude Code Plugin (Recommended)

    main

    Install the skill using Claude Code's plugin system to enable automatic updates and easy distribution. Follow these steps in order:

    1. Add the repository as a marketplace.
    2. Install the specific plugin.
    3. Navigate to the installed skill directory and run the setup script to install Playwright and its dependencies.

    Verify the installation by running /help in Claude Code to confirm the skill is available.

    # Add this repository as a marketplace
/plugin marketplace add lackeyjb/playwright-skill

# Install the plugin
/plugin install playwright-skill@playwright-skill

# Navigate to the skill directory and run setup
cd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
npm run setup

  11. Debug Playwright tests

    main

    You can debug tests using CLI flags or in-code commands.

    CLI Debugging:

    • Run with the Playwright Inspector: npx playwright test --debug
    • Run in headed mode (visible browser): npx playwright test --headed
    • Run in headed mode with slow motion: npx playwright test --headed --slowmo=1000

    In-Code Debugging:

    • Pause execution at a specific line: await page.pause();
    • Listen to browser console logs: page.on('console', msg => console.log('Browser log:', msg.text()));
    • Listen to page errors: page.on('pageerror', error => console.log('Page error:', error));
    # Run with inspector
npx playwright test --debug

# Headed mode
npx playwright test --headed

# Slow motion
npx playwright test --headed --slowmo=1000

  12. Optimize Playwright execution and stability

    main

    Follow these technical patterns for better automation results:

    • Slow Motion: Use slowMo: 100 to make actions visible and easier to follow.
    • Wait Strategies: Prefer waitForURL, waitForSelector, and waitForLoadState over fixed timeouts.
    • Error Handling: Wrap automation logic in try-catch blocks.
    • Progress Tracking: Use console.log() to track and report progress.