Understanding Playwright: Concepts Explained

Leave a Comment / By

Before installing anything, understand what you’re installing, where it goes, and why it’s needed.

The Big Picture

┌─────────────────────────────────────────────────────────┐
│                    Claude Code                          │
│                   (Your AI Assistant)                   │
└─────────────────────┬───────────────────────────────────┘
                      │ communicates via
                      ▼
┌─────────────────────────────────────────────────────────┐
│                 Playwright MCP Server                   │
│            (The "Bridge" / Translator)                  │
│         Converts Claude's requests into                 │
│            browser automation commands                  │
└─────────────────────┬───────────────────────────────────┘
                      │ controls
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Playwright Library                         │
│           (The "Remote Control")                        │
│      Node.js package that sends commands                │
│              to browsers                                │
└─────────────────────┬───────────────────────────────────┘
                      │ automates
                      ▼
┌─────────────────────────────────────────────────────────┐
│          Browser (Chromium/Firefox/WebKit)              │
│              (The Actual Browser)                       │
│     Real browser that renders and displays              │
│                  web pages                              │
└─────────────────────────────────────────────────────────┘

What Is Each Component?

1. Browser (Chromium, Firefox, WebKit)

What it is: The actual web browser – the same thing you use to browse the internet.

  • Chromium = Open-source version of Chrome (most commonly used)
  • Firefox = Mozilla’s browser
  • WebKit = Safari’s engine

Analogy: This is like your TV – the device that actually displays content.

2. Playwright Library

What it is: A Node.js automation tool created by Microsoft. It sends commands to browsers.

What it does:

  • Opens browser windows
  • Navigates to URLs
  • Clicks buttons
  • Fills forms
  • Takes screenshots
  • Extracts content

Analogy: This is like a TV remote control – it tells the TV (browser) what to do.

Important: Playwright is NOT a browser. It’s a tool that CONTROLS browsers.

3. Playwright MCP Server

What it is: A “translator” that connects Claude Code to Playwright.

MCP = Model Context Protocol – A standard way for AI assistants to use external tools.

What it does:

  • Listens for requests from Claude Code
  • Translates them into Playwright commands
  • Returns results back to Claude

Analogy: This is like a universal remote adapter – it lets Claude Code (which doesn’t natively speak “browser”) control browsers through Playwright.

Installation Breakdown

Important: Steps 1 and 2 are always global (no choice). Only Step 3 lets you choose between user scope or project scope.

Step 1: Install Playwright Library

npm install -g playwright
What it installs Playwright library (the “remote control” code)
Where it goes Global npm packages (/usr/local/lib/node_modules/)
Scope Global only – no choice
Why needed Provides the automation API that controls browsers
Size ~5 MB

Step 2: Install Browser

npx playwright install chromium
What it installs Actual browser binaries (Chromium, Firefox, WebKit)
Where it goes ~/Library/Caches/ms-playwright/ (macOS)
Scope Global only – no choice
Why needed Playwright needs real browsers to control
Size ~500 MB (all browsers) or ~150 MB (Chromium only)

Tip: For Claude Code, you typically only need Chromium.

Step 3: Configure MCP Server (You choose scope)

What it does Adds Playwright MCP server configuration
Where it goes ~/.claude.json (Claude Code’s config file)
Scope You choose: User (global) or Project (local)
Why needed Tells Claude Code how to start and communicate with Playwright
Size Just a config entry (text)

User scope (all projects):

claude mcp add playwright --scope user -- npx @playwright/mcp@latest

Project scope (current project only):

claude mcp add playwright -- npx @playwright/mcp@latest

Scope Summary

Step What Scope Can choose?
Step 1 Install Playwright Global only No
Step 2 Install browsers Global only No
Step 3 Configure MCP User or Project Yes

Where Everything Lives

Component Location Scope
Playwright library /usr/local/lib/node_modules/playwright Global (all projects)
Browser binaries ~/Library/Caches/ms-playwright/ Global (all projects)
MCP config (user scope) ~/.claude.json → mcpServers Global (all projects)
MCP config (project scope) ~/.claude.json → projects.[path].mcpServers Single project only

Why Each Part Is Needed

Without this… What happens
Browser binaries Playwright has nothing to control – “browser not found” error
Playwright library No way to send automation commands to browsers
Playwright MCP Claude Code can’t communicate with Playwright – “MCP failed” error

Scope: User vs Project

When adding Playwright MCP, you choose where the config is stored:

User Scope (Recommended)

claude mcp add playwright --scope user -- npx @playwright/mcp@latest
  • Stored in: ~/.claude.json under User MCPs
  • Works in: All projects
  • Best for: Tools you want everywhere

Project Scope (Default)

claude mcp add playwright -- npx @playwright/mcp@latest
  • Stored in: ~/.claude.json under projects.[current-path]
  • Works in: Current project only
  • Best for: Project-specific tools

Common Questions

“Do I need to run pnpm dev for Playwright to work?”

It depends on what you’re testing:

Scenario Need dev server?
Browsing external sites (linear.app, google.com) No
Testing your local app (localhost:3000) Yes
Updating WordPress (adventuretube.net) No

“Why did Playwright MCP fail in one project but work in another?”

The MCP server config is project-specific by default. If you added it with --scope user, it works everywhere. Without that flag, each project needs its own config.

Quick Verification Commands

Check if browsers are installed:

ls ~/Library/Caches/ms-playwright/

Check MCP configuration:

claude mcp list

Test Playwright MCP manually:

npx @playwright/mcp@latest

(Should hang waiting for connections – that means it works. Press Ctrl+C to exit.)

Summary

You’re installing What it is One-time?
npm install -g playwright The automation library Yes
npx playwright install chromium The actual browser Yes
claude mcp add playwright... The Claude Code connection Yes (if user scope)

Related

Related Posts

Leave a Comment

Your email address will not be published. Required fields are marked *