DEV Community

Cover image for Getting Started with Claude Code and Playwright CLI: A Step-by-Step Guide
Aswani Kumar
Aswani Kumar

Posted on

Getting Started with Claude Code and Playwright CLI: A Step-by-Step Guide

#ai #claude #testing #playwright

AI coding agents like Claude Code are changing how SDETs approach browser automation. Instead of writing every locator and assertion by hand, you can describe a test scenario in plain English and let Claude drive the browser for you. In this guide, we'll set up Claude Code with Playwright CLI — Microsoft's token-efficient, agent-friendly companion to Playwright — and run our first automated browser test.

By the end of this guide, you'll have Claude Code testing a real form on a real page, using nothing but shell commands under the hood.

Why Use Claude Code with Playwright CLI?

  • Natural language test execution: Describe what to test instead of writing every selector manually.
  • Token efficiency: Playwright CLI writes browser state to disk instead of streaming it into the AI's context on every action, which keeps sessions cheaper and longer-running.
  • No new protocol to learn: It runs as plain shell commands, the same way Claude Code already runs git or npm.
  • Skill-based workflows: Pairs directly with Claude Code Skills (more on that in a later post), so your team can reuse the exact same testing conventions across projects.
  • CI-ready: The same commands that work interactively in your terminal can run inside a pipeline.

Table of Contents

  1. Prerequisites
  2. Step 1: Install Node.js and Verify Your Environment
  3. Step 2: Install Playwright CLI
  4. Step 3: Install a Browser Engine
  5. Step 4: Install the Playwright Skill for Claude Code
  6. Step 5: Run Your First Automated Test
  7. Troubleshooting
  8. Conclusion

Prerequisites

Before you begin, make sure you have:

  • Node.js 18 or newer installed (Playwright CLI requires it; older versions can throw obscure errors).
  • Claude Code installed and authenticated. If you don't have it yet: npm install -g @anthropic-ai/claude-code
  • A terminal you're comfortable working in (iTerm2, Windows Terminal, or any modern shell).
  • A local web app or public URL you want to test against (we'll use a demo TodoMVC app for this walkthrough).

Step 1: Verify Your Environment

Start by confirming your Node.js version:

node --version
Enter fullscreen mode Exit fullscreen mode
  • You need v18+. If you're on an older version, upgrade before continuing — Playwright CLI depends on newer JavaScript runtime features.
  • Also confirm Claude Code is installed and working: 
claude --version
Enter fullscreen mode Exit fullscreen mode

If that command isn't recognized, install it first with npm install -g @anthropic-ai/claude-code, then re-run the check.

Step 2: Install Playwright CLI

Install the CLI globally so it's available from any project:

npm install -g @playwright/cli@latest
Enter fullscreen mode Exit fullscreen mode

The @latest tag pulls the newest release. For CI pipelines, consider pinning to a specific version (e.g. @playwright/cli@1.2.0) so your pipeline doesn't break when a new version ships mid-run.
Confirm the install worked:

playwright-cli --help
Enter fullscreen mode Exit fullscreen mode

You should see a list of available commands (navigate, snapshot, click, fill, screenshot, and more).

Step 3: Install a Browser Engine

Playwright CLI needs at least one browser binary to control:

npx playwright install chromium
Enter fullscreen mode Exit fullscreen mode

You can swap chromium for firefox or webkit depending on which engine you want to test against.
This step downloads roughly 100–300 MB per browser, so make sure you have disk space and a stable connection.

Step 4: Install the Playwright Skill for Claude Code

This is the step most setup guides skip — and it's the one that actually makes Claude reliable with the CLI's exact command syntax instead of guessing:

playwright-cli install --skills
Enter fullscreen mode Exit fullscreen mode

This drops a SKILL.md file into your Claude Code configuration that documents every available CLI command.
Without this step, Claude may occasionally hallucinate flags or fall back to running raw Playwright test scripts instead of using the CLI directly.
You only need to run this once per machine (or once per project, if you're using project-scoped skills).

Step 5: Run Your First Automated Test

Open a Claude Code session in your project directory:

claude
Enter fullscreen mode Exit fullscreen mode

Now, in plain language, describe the test:

Use the Playwright CLI to open https://demo.playwright.dev/todomvc,
add a todo item called "Write blog post", and confirm it appears in the list.
Enter fullscreen mode Exit fullscreen mode

Behind the scenes, Claude Code will run a sequence like this:

playwright-cli navigate https://demo.playwright.dev/todomvc
playwright-cli snapshot                        # saves page state to disk as YAML
playwright-cli fill e12 "Write blog post"
playwright-cli press e12 Enter
playwright-cli snapshot                        # verify the todo now appears
Enter fullscreen mode Exit fullscreen mode
  • snapshot captures a compact accessibility-tree representation of the page and saves it to disk — Claude only reads the parts it needs, rather than the whole page being pushed into the conversation.
  • The e12 reference comes directly from that snapshot; Playwright CLI and Playwright MCP both use this referencing system, so if you've used MCP before, the mental model will feel familiar.
  • Claude will report back with a plain-language summary: whether the todo was added successfully, and what it saw in the final page state.

Troubleshooting

  • "Command not found: playwright-cli" — the global install didn't add it to your PATH. Try npx playwright-cli --help instead, or re-run the global install.
  • Claude falls back to raw Playwright scripts instead of the CLI — confirm the Skill installed correctly with playwright-cli install --skills, and restart your Claude Code session (Skills load at session start).
  • Browser fails to launch — re-run npx playwright install chromium and check you have enough disk space.
  • Tests behave differently on your CI server — pin your Playwright CLI and browser versions explicitly rather than relying on @latest.

Conclusion

You now have Claude Code and Playwright CLI working together, with Claude driving a real browser through natural language instructions instead of you hand-writing every step. This is just the foundation — in the next post, we'll compare Playwright CLI against Playwright MCP in detail, including real token benchmarks, so you know exactly when to reach for each one.

Have you tried Claude Code for browser testing yet? Drop your experience — or questions — in the comments below!

Top comments (0)