Verify and repair the local environment for Playwright-based QA training - node and npm, repo dependencies, browser binaries, playwright-cli, the Playwright MCP server, and .playwright.env - then prove it works with one smoke test. Covers macOS, Windows (PowerShell), and WSL.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Verify and repair the local environment for Playwright-based QA training - node and npm, repo dependencies, browser binaries, playwright-cli, the Playwright MCP server, and .playwright.env - then prove it works with one smoke test. Covers macOS, Windows (PowerShell), and WSL.
disable-model-invocation
true
Environment Check
Get one machine from "I cloned the repo" to "I can run a Playwright test and drive a real browser from my AI coding tool" in about ten minutes, and produce a short, honest list of anything still blocked.
This runs during Environment Setup Session 2, part two, with an instructor in the room. Speed matters, but a clear blocked list matters more than a forced pass. Anything you cannot fix in the room becomes a named follow-up before Foundational Training.
Rules
Verify everything first, then fix. Run all seven checks and print the report before you change anything. The attendee needs the whole picture, not a surprise install.
Ask before you install. State the exact command, and say whether it changes the project or the whole machine. Wait for a yes. Global installs and anything needing sudo always get an explicit ask.
One fix at a time. Apply a fix, re-run only that check, report the result, move on.
Never invent secrets.BASE_URL, credentials, and API keys come from the attendee. Do not guess values, do not read them out, and never commit .playwright.env.
Escalate instead of grinding. Two failed attempts on the same check means stop. Mark it BLOCKED, and tell the attendee to post the check ID and the error text in the session chat.
Stay in your lane. This skill changes environment, dependencies, and tool config only. Do not edit tests, page objects, playwright.config.ts, or any application code.
Step 0: Detect platform and tool
Record both before running checks. They change almost every fix command.
Platform. Run uname -s:
Result
Platform
Darwin
macOS
Linux, and /proc/version contains microsoft
WSL
Linux, no microsoft
Linux
command not found
Windows (PowerShell)
AI coding tool. Ask if it is not obvious from what is already in the repo. This determines where MCP config goes:
Tool
MCP config path
Claude Code
.mcp.json (repo root)
Cursor
.cursor/mcp.json
GitHub Copilot / VS Code
.vscode/mcp.json
Codex
~/.codex/config.toml
Confirm you are in the practice repo root before continuing: package.json and playwright.config.ts are both present.
The seven checks
Run all of them. Do not stop at the first failure.
ID
Check
Pass condition
Command
C1
Runtime
node 20 or newer, npm resolves
node --version && npm --version
C2
Repo dependencies
@playwright/test resolves locally
npm ls @playwright/test --depth=0
C3
Browser binaries
exits 0
npx playwright install chromium
C4
playwright-cli
exits 0
playwright-cli --version
C5
Playwright MCP
config entry present and server starts
see below
C6
Environment file
.playwright.env present, all keys filled, BASE_URL responds
see below
C7
Smoke test
one test passes
npx playwright test tests/auth/login.spec.ts --project=chromium --reporter=list
C3 is idempotent. If the browsers are already installed it returns in a second or two, so running it is also the check.
C5, in two parts. First, the config: read the path from Step 0 and confirm it contains a playwright server entry pointing at @playwright/mcp. Second, that the package actually starts: npx @playwright/mcp@latest --version. Config on disk is not the same as a connected server, and the tool only picks up new config on restart, so finish by asking the attendee to confirm from inside their tool (/mcp in Claude Code, MCP settings pane in Cursor, MCP: List Servers in VS Code).
C6, in three parts..playwright.env exists in the repo root; BASE_URL, ADMIN_EMAIL, ADMIN_PASSWORD, API_READ_KEY, and API_WRITE_KEY are all present and non-empty; and BASE_URL answers.
# Windows PowerShell
(Invoke-WebRequest -Uri $env:BASE_URL -UseBasicParsing).StatusCode
Any 2xx or 3xx is a pass. Report the key names only, never the values.
Report
Print this table once, after all seven checks, before proposing anything:
Check Status Detail
C1 Runtime PASS node v24.7.0, npm 11.6.0
C2 Repo dependencies FAIL node_modules missing
C3 Browser binaries FAIL chromium not installed
C4 playwright-cli FAIL command not found
C5 Playwright MCP FAIL no playwright entry in .mcp.json
C6 Environment file FAIL .playwright.env missing
C7 Smoke test SKIPPED blocked by C2, C6
Statuses: PASS, FAIL, BLOCKED (cannot be fixed on this machine, needs someone else), SKIPPED (a prerequisite check failed). Mark C7 SKIPPED rather than FAIL when C2, C3, or C6 failed. A failing smoke test only means something when its prerequisites passed.
Then list the proposed fixes in order, numbered, each with its command, and ask for a go-ahead.
Fixes
F1: Runtime (C1)
Do not install a node version manager unattended. Tell the attendee which one fits their platform and let them run it:
macOS, Linux, WSL: nvm or fnm, then nvm install 24 && nvm use 24
Windows: winget install OpenJS.NodeJS.LTS, or nvm-windows
Node older than 20 fails everything downstream, so fix this first and re-run all checks afterward.
F2: Repo dependencies (C2)
npm ci # preferred, package-lock.json is committed
npm install # fall back to this if npm ci errors
Project-scoped, so no permission concerns. On a cold clone this is the slowest step in the session, usually one to three minutes.
F3: Browser binaries (C3)
npx playwright install chromium
On WSL and Linux the browser also needs system libraries:
npx playwright install-deps chromium # uses sudo, ask first
Chromium alone is enough for training. Do not install all three browser engines in the room; it triples the download for no benefit today.
F4: playwright-cli (C4)
npm install -g @playwright/cli
This one is global, so ask first, and it is the single most common place a corporate laptop says no.
EACCES on macOS or Linux: do not reach for sudo. Point npm at a user-owned prefix instead: npm config set prefix ~/.npm-global, add ~/.npm-global/bin to PATH in the shell profile, open a new shell, retry.
Installs but command not found on Windows: the npm global bin directory is not on PATH yet. npm config get prefix shows where it landed. A fresh PowerShell window usually resolves it.
WSL: confirm you are using the Linux node, not a Windows install reached across /mnt/c. which node should not return a /mnt/c/... path.
Blocked by policy: mark C4 BLOCKED and move on. The Playwright MCP server (C5) covers most of what training needs, so a blocked C4 is not a reason to stall the room.
F5: Playwright MCP (C5)
Write the config for the tool identified in Step 0. For Claude Code, .mcp.json in the repo root:
If a config file already exists, merge the playwright entry into it. Do not overwrite other servers the attendee already has. Then have them restart the tool and confirm the server shows as connected.
F6: Environment file (C6)
cp .playwright.env.example .playwright.env
Copy-Item .playwright.env.example .playwright.env
Then ask the attendee to paste the values from the session chat. Confirm .playwright.env is matched by .gitignore before moving on: git check-ignore -v .playwright.env should print a matching rule. If it does not, stop and say so, because the next commit would leak credentials.
F7: Smoke test (C7)
Triage in this order:
BASE_URL unreachable. Training environments are review apps and sleep when idle, so the first request can be slow. Open BASE_URL in a browser, wait for it to wake, retry once.
Login assertion fails. Credentials are wrong or belong to a different environment. Re-check against what was posted in chat. Each attendee may have a different assigned build.
Browser launch error. Back to C3, and on WSL to install-deps.
Stale session state.playwright.config.ts reuses storageState from .auth/user.json. Delete the .auth/ directory and re-run so the setup project regenerates it.
Anything beyond that is out of scope for the session. Mark it BLOCKED with the error text and move on.
What done looks like
All seven checks PASS, or a short list of named blocked checks with error text captured. The second outcome is a success too: it turns a laptop problem into a tracked follow-up instead of a surprise at the start of Foundational Training.
Final output
After the last re-run, print exactly one summary line:
Environment check: 7/7 passing. Blocked: none.
Or, when something is genuinely stuck:
Environment check: 5/7 passing. Blocked: C4 (global npm install denied by policy), C5 (MCP server unreachable behind proxy).
See references/os-notes.md for the longer tail of platform-specific failures: proxies and custom registries, Windows PATH and execution policy, WSL filesystem boundaries, and corporate certificate interception.
