playwright-cli: il browser da riga di comando pensato per gli agenti AI

Per far usare un browser a un agente AI, finora la strada più citata è il server MCP di Playwright (ne parliamo nell'articolo Playwright e AI). playwright-cli è l'alternativa di Microsoft: un'interfaccia a riga di comando con comandi brevi, pensata per i coding agent come Claude Code o GitHub Copilot.

Perché una CLI invece di MCP

Secondo il README del progetto, l'approccio CLI abbinato alle skill consuma meno token: non carica nel contesto grandi schemi di strumenti né alberi di accessibilità completi. L'agente lancia un comando, riceve uno snapshot compatto della pagina e prosegue. È più adatto ai coding agent che devono tenere in memoria molto codice e non vogliono sprecare contesto.

Requisiti e installazione

• Node.js 18 o superiore
• Facoltativo ma tipico: Claude Code, GitHub Copilot o un altro coding agent

npm install -g @playwright/cli@latest
playwright-cli --help

Per installare le skill che insegnano all'agente a usare lo strumento:

playwright-cli install --skills

Senza skill funziona comunque: basta dire all'agente di leggere l'output di playwright-cli --help.

Primi comandi

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli check e21
playwright-cli screenshot

Dopo ogni comando la CLI restituisce uno snapshot della pagina con dei riferimenti (e21 nell'esempio) da riusare nei comandi successivi. Si possono usare anche selettori CSS o locator Playwright:

playwright-cli click "#main > button.submit"
playwright-cli click "getByRole('button', { name: 'Submit' })"
playwright-cli click "getByTestId('submit-button')"

I comandi principali

Sessioni e dashboard

Il browser è headless per impostazione predefinita; --headed mostra la finestra. Le sessioni si nominano e si possono rendere persistenti:

playwright-cli -s=example open https://example.com --persistent
playwright-cli list
playwright-cli close-all

• --persistent salva il profilo del browser su disco (utile per restare autenticati).
• Una sessione headless si chiude dopo un'ora senza comandi; si regola con --idle-timeout=<ms>.
• La variabile PLAYWRIGHT_CLI_SESSION assegna una sessione a un agente, per esempio PLAYWRIGHT_CLI_SESSION=todo-app claude .

Con playwright-cli show si apre una dashboard per vedere tutte le sessioni attive con anteprima in tempo reale e, se serve, intervenire a mano.

Le skill per l'agente

Dopo playwright-cli install --skills l'agente dispone di guide su: esecuzione e debug dei test, mocking delle richieste, gestione delle sessioni e dello storage state, generazione di test (plan, generate, heal), tracing, video, e allegati alle pull request con gh.

Configurazione

Il file predefinito è .playwright/cli.config.json, oppure si indica con --config. Accetta opzioni come browser, outputDir, saveVideo, testIdAttribute e network con allowedOrigins / blockedOrigins: quest'ultima è utile per limitare i siti raggiungibili dall'agente.

Un esempio concreto

Verificare come appare una pagina in tema scuro su mobile, da dare a Claude Code come istruzione:

playwright-cli open https://www.egsoft.it --device="iPhone 15"
playwright-cli set-color-scheme dark
playwright-cli screenshot --filename=home-dark-mobile.png
playwright-cli console
playwright-cli close

Sicurezza

• Usa un profilo dedicato (--persistent con una sessione nominata), non il tuo browser personale.
• Limita i domini consentiti con network.allowedOrigins.
• Non inserire password nei prompt: usa state-save / state-load dopo un login manuale.

Il progetto richiede Node.js 18+ ed è distribuito con licenza Apache-2.0.