Installer la skill Claude Code webapp-testing proprement

Une skill qui pilote Chromium

webapp-testing est une skill officielle d'Anthropic, dans le repo anthropics/skills, qui donne à Claude Code le contrôle d'un vrai navigateur — une instance Chromium pilotée via Playwright pour tester une app en local.

Le concept : au lieu d'écrire des scripts Playwright à la main, on décrit ce qu'on veut tester en langage naturel, et Claude écrit puis exécute le script dans un vrai browser. On peut se logger à la main, puis lui passer la main. Il prend des screenshots, lit le DOM, capture les logs console, debug les flows authentifiés — ce qu'aucune analyse statique ne peut faire.

Problème : aucun des guides disponibles ne donne une méthode d'install propre. Tous proposent quelque chose qui pollue le système ou qui cassera dans deux semaines.

Le problème avec les méthodes habituelles

Pour Playwright en Python, le consensus officiel est clair :

1. Jamais pip install system-wide. PEP 668 bloque ça par défaut sur Ubuntu, Debian, Fedora et la plupart des distros modernes — un error: externally-managed-environment tombe, et c'est tant mieux.
2. Pas pipx. pipx est conçu pour les CLI standalone, or Playwright s'utilise comme librairie importée (from playwright.sync_api import ...). pipx isole si bien qu'on ne peut plus l'importer depuis un script externe.
3. Toujours --with-deps sur Linux à l'installation des browsers. Sinon Chromium crashe avec des erreurs cryptiques sur des .so manquants (libs audio, fonts, rendering). Le flag lance un apt install derrière — donc sudo demandé — mais c'est la bonne route.

La best practice pour un projet Playwright classique, c'est un venv par projet. Mais pour une skill Claude Code globale, ça ne marche pas : Claude appelle la skill depuis n'importe quel répertoire, sans moyen de savoir quel venv activer.

La solution : venv dédié dans le dossier de la skill

Le pattern qui tient : un venv embarqué directement dans le dossier de la skill, plus un patch dans le SKILL.md pour dire à Claude « utilise CE python, pas le système ». La skill devient autonome, le Python système reste vierge, et rm -rf ~/.claude/skills/webapp-testing désinstalle tout proprement, y compris les 600 MB de Chromium.

1. Récupérer la skill

Le repo anthropics/skills contient beaucoup d'autres choses (skills documents PDF/DOCX/PPTX, MCP server generator). Sparse checkout pour ne prendre que ce qu'il faut :

cd /tmp
git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/anthropics/skills.git anthropics-skills-tmp
cd anthropics-skills-tmp
git sparse-checkout set skills/webapp-testing
cp -r skills/webapp-testing ~/.claude/skills/
cd .. && rm -rf anthropics-skills-tmp

Le dossier ~/.claude/skills/webapp-testing/ contient alors :

webapp-testing/
├── SKILL.md         # Instructions principales
├── LICENSE.txt
├── examples/        # console_logging.py, element_discovery.py, static_html_automation.py
└── scripts/         # with_server.py (lifecycle multi-serveurs)

Claude Code détecte la skill au prochain démarrage, mais elle ne marche pas encore : Playwright n'est pas installé.

2. Venv dédié dans la skill

python3 -m venv ~/.claude/skills/webapp-testing/.venv
~/.claude/skills/webapp-testing/.venv/bin/pip install --upgrade pip
~/.claude/skills/webapp-testing/.venv/bin/pip install playwright

Tout reste contenu dans .venv/. Un python3 tapé dans un terminal reste le Python d'OS, vierge. La stack de référence ici : Python 3.12.3, pip 26.1, Playwright 1.59.0.

3. Chromium + dépendances système

~/.claude/skills/webapp-testing/.venv/bin/playwright install --with-deps chromium

Le --with-deps est critique sur Linux : il lance un sudo apt install pour poser les libs partagées dont Chromium a besoin (libnss3, libatk1.0, libxkbcommon, libgbm, et une vingtaine d'autres). Sans ça, le browser crashe au lancement sur error while loading shared libraries: libnss3.so.

Le download fait ~280 MB : Chrome for Testing (170 MB) et Chrome Headless Shell (112 MB), stockés dans ~/.cache/ms-playwright/ et non dans le venv. C'est le défaut Playwright, et c'est bien : un autre projet Playwright réutilisera le même cache de browsers.

4. Patcher SKILL.md

C'est l'étape que personne ne mentionne, et pourtant celle qui rend l'install fonctionnelle. Par défaut, le SKILL.md dit à Claude de lancer les scripts avec python3 — le Python système, qui n'a pas Playwright. Résultat : ModuleNotFoundError: No module named 'playwright', et une demi-session à comprendre pourquoi.

On ajoute en tête du SKILL.md une section pointant le bon interpréteur :

**IMPORTANT — Python interpreter to use**:
This skill ships with its own dedicated venv at
`~/.claude/skills/webapp-testing/.venv` with Playwright + Chromium
pre-installed. **Always invoke scripts with this interpreter**, never
the system `python3` (which won't have Playwright):

\`\`\`bash
~/.claude/skills/webapp-testing/.venv/bin/python scripts/with_server.py --help
~/.claude/skills/webapp-testing/.venv/bin/python /tmp/your_automation.py
\`\`\`

When the helper `with_server.py` invokes child commands, also pass this
interpreter explicitly (e.g. `... -- ~/.claude/skills/webapp-testing/.venv/bin/python your_automation.py`).

Claude lit le SKILL.md à chaque déclenchement : cette note tape direct dans son contexte, et il utilise systématiquement le bon python.

5. Smoke test

~/.claude/skills/webapp-testing/.venv/bin/python -c "
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    b = p.chromium.launch(headless=True)
    page = b.new_page()
    page.set_content('<h1>hello</h1>')
    print('h1:', page.locator('h1').inner_text())
    b.close()
print('OK')
"

Sortie attendue : h1: hello puis OK. Un crash sur des libs partagées signifie que --with-deps n'a pas tourné correctement (sudo refusé ou apt indisponible) — relancer avec sudo explicite.

Pourquoi pas npx skills add

Plusieurs guides proposent npx skills add https://github.com/anthropics/skills --skill webapp-testing, ou le marketplace plugin (/plugin marketplace add anthropics/skills). Ça pose la skill — en gros ce que fait le git clone sparse — mais ça ne gère pas l'install Playwright. On se retrouve avec une skill détectée par Claude Code qui plante à la première utilisation.

Alternative avec uv

uv (par Astral) est devenu la référence pour gérer du Python : plus rapide que pip (10× sur les installs), gestion native des venvs, scripts auto-dépendances via PEP 723.

curl -LsSf https://astral.sh/uv/install.sh | sh   # si pas déjà installé

uv venv ~/.claude/skills/webapp-testing/.venv
uv pip install --python ~/.claude/skills/webapp-testing/.venv/bin/python playwright
~/.claude/skills/webapp-testing/.venv/bin/playwright install --with-deps chromium

Résultat rigoureusement identique, install deux fois plus rapide. Le patch SKILL.md reste à faire.

Utilisation

On interpelle la skill en langage naturel :

"Démarre mon dev server Next.js sur le port 3000 et utilise webapp-testing
pour vérifier que la page d'accueil charge sans erreur console."

"Lance webapp-testing sur localhost:5173, prends un screenshot de la page
de login, puis tente de te connecter avec test@example.com/password et
vérifie qu'on arrive bien sur le dashboard."

"Avec webapp-testing, navigue sur le formulaire de checkout et liste tous
les sélecteurs des champs input - je veux écrire un test E2E."

Claude détecte la skill au démarrage, appelle le bon interpréteur grâce au patch SKILL.md, et écrit puis exécute le script Playwright à la volée.

Le SKILL.md officiel donne un decision tree clair :

• App statique (HTML pur) → lecture directe du fichier HTML pour identifier les sélecteurs, puis script Playwright simple.
• App dynamique, serveur déjà lancé → pattern « recon → action » : page.goto(url), page.wait_for_load_state('networkidle'), screenshot/inspection, identification des sélecteurs, exécution.
• App dynamique, serveur à lancer → helper scripts/with_server.py, qui gère le lifecycle multi-serveurs (frontend + backend en parallèle).

La règle la plus importante : toujours wait_for_load_state('networkidle') avant d'inspecter le DOM sur une app dynamique. Sinon Claude lit un DOM à mi-rendering et écrit un test qui échoue une fois sur trois.

Ce qu'il faut retenir

La doc Playwright recommande venv mais ne couvre pas le cas « skill globale ». Le venv-par-projet est le bon réflexe en dev classique ; pour une skill invocable depuis n'importe où, le venv embarqué dans la skill est le seul moyen propre.

Le patch SKILL.md, c'est 90 % de la stabilité de l'install. Sans cette note, Claude tombe sur le python3 système et crashe. Huit lignes changent tout.

Les binaires Chromium dans ~/.cache/ms-playwright/ sont partagés. On télécharge Chromium une seule fois par machine, quelle que soit la méthode d'install des autres projets.

--with-deps est non négociable. Sauter le sudo pour aller plus vite se paie en vingt minutes de debug sur libnspr4.so.

Cette skill remplace l'essentiel des besoins en MCP Playwright. Un setup @playwright/mcp reste plus puissant pour l'exploration interactive (état browser persistant, accessibility tree dans la réponse), mais plus lourd à mettre en place et plus cher en tokens. Pour « vérifie que ce flow marche », la skill est plus directe.

Les limites

C'est un outil d'aide au développement, pas un framework de test E2E pour la prod. Pour une vraie suite E2E avec CI/CD, sharding, retries et rapports, pytest-playwright dans un projet dédié reste la réponse. La skill, c'est pour le quotidien : « j'ai changé ce composant, vérifie vite que rien n'est cassé sur le flow X ».

Et tout ce que Claude voit dans le browser (DOM, console, données de formulaires) part dans l'API Anthropic. À utiliser sur des environnements de dev avec des données de test, pas sur la prod avec des données client réelles.