Przejdź do głównej zawartości

Playwright MCP kontra Playwright CLI: testy w przeglądarce dla agentów

Playwright MCP (@playwright/mcp) i Playwright CLI (@playwright/cli) to dwa sposoby Microsoftu, żeby agent kodujący sterował prawdziwą przeglądarką przez snapshoty drzewa dostępności Playwrighta. Serwer MCP trzyma żywą przeglądarkę i zwraca stan strony w każdym wyniku narzędzia. CLI ze skillem zużywa mniej kontekstu i to na nie README Microsoftu kieruje agentów kodujących.

Prosisz agenta o naprawę niedziałającego przycisku Subscribe. Agent poprawia handler kliknięcia, uruchamia testy jednostkowe i melduje sukces, a przeglądarki nikt nie otworzył. Albo otworzył, tylko że trzech agentów w trzech worktree biło się o ten sam profil przeglądarki, aż dwóch z nich padło na zablokowanym profilu.

Ta strona jest dla programistów, którzy chcą, żeby agent sam sprawdzał swoją pracę nad UI w prawdziwej przeglądarce, i dla tech leadów, którzy potrzebują, żeby to działało przy kilku agentach naraz.

  • Regułę wyboru między Playwright MCP a Playwright CLI ze skillem, opartą na zmierzonym koszcie kontekstu.
  • Polecenia instalacji w Claude Code, Codex i Cursorze, z flagami dla agentów: --isolated, --headless i --caps.
  • Proces od zgłoszenia błędu do testu regresyjnego razem z bramką w CI: test najpierw nie przechodzi, poprawka sprawia, że przechodzi, a CI go pilnuje.

Czy agent powinien używać Playwright MCP, czy Playwright CLI?

Dział zatytułowany „Czy agent powinien używać Playwright MCP, czy Playwright CLI?”

Oba pakiety napędzają ten sam silnik Playwrighta i używają tych samych referencji do elementów ze snapshotu drzewa dostępności. Różnią się tym, dokąd trafiają dane strony.

  • Playwright MCP to serwer MCP po stdio. Każda akcja (browser_click, browser_navigate) zwraca snapshot strony w wyniku narzędzia, więc strona ląduje w kontekście modelu po każdym kroku.
  • Playwright CLI to polecenie powłoki playwright-cli. Zapisuje snapshot do pliku YAML w .playwright-cli/ i wypisuje link do niego. Agent czyta plik tylko wtedy, gdy go potrzebuje.

README Playwright MCP (0.0.82, odczyt 2026-09-26) mówi to wprost: „If you are using a coding agent, you might benefit from using the CLI+SKILLS instead”. Uzasadnienie: wywołania CLI „avoid loading large tool schemas and verbose accessibility trees into the model context”. MCP zostawia dla „exploratory automation, self-healing tests, or long-running autonomous workflows where maintaining continuous browser context outweighs token cost concerns”.

Playwright MCPPlaywright CLI + skill
Pakiet (npm, 2026-09-26)@playwright/mcp 0.0.82@playwright/cli 0.1.21, plik wykonywalny playwright-cli
Jak wywołuje go agentNarzędzia MCP (browser_navigate, browser_snapshot, …)Polecenia powłoki (playwright-cli goto, playwright-cli snapshot, …)
Stan strony po każdej akcjiW wyniku narzędziaZapisany do pliku; agent czyta go na żądanie
Domyślny profil przeglądarkiTrwały, na dysku, jeden na workspaceW pamięci; --persistent zapisuje go na dysk
Działa wKażdym kliencie MCPKażdym agencie, który uruchamia polecenia powłoki; skill wymaga agenta ładującego skille
Najlepszy doSesji eksploracyjnych, obserwowania widocznej przeglądarki, klientów bez powłokiAgentów kodujących w repozytorium: pisanie testów, weryfikacja, równoległe sesje

Reguła wyboru: w repozytorium, w którym agent może uruchamiać polecenia powłoki, domyślnie używaj CLI ze skillem. Serwer MCP zostaw, gdy agent nie ma powłoki, gdy interaktywnie eksplorujesz nieznaną aplikację albo gdy zespół i tak centralnie zarządza serwerami MCP, a budżet kontekstu nie jest ograniczeniem.

Zainstaluj Playwright MCP w Claude Code, Codex i Cursorze

Dział zatytułowany „Zainstaluj Playwright MCP w Claude Code, Codex i Cursorze”

Serwer wymaga Node.js 18 lub nowszego. Dodaj --isolated od początku, jeśli w tym samym checkoucie może pracować więcej niż jeden agent; sekcja o równoległych agentach wyjaśnia dlaczego.

Zakres projektu, żeby każdy klon i każde worktree dostały ten sam wpis (przetestowane na Claude Code 2.1.283):

Okno terminala
claude mcp add --scope project playwright -- npx @playwright/mcp@0.0.82 --isolated --headless

Polecenie zapisuje ten wpis do .mcp.json, który commitujesz:

{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@0.0.82", "--isolated", "--headless"],
"env": {}
}
}
}

-- jest istotne: bez niego claude mcp add próbuje potraktować --isolated jako własną opcję. Krótsza linia z README, claude mcp add playwright npx @playwright/mcp@latest, działa, gdy nie przekazujesz serwerowi żadnych flag.

Alternatywnie zainstaluj plugin z oficjalnego marketplace’u Anthropic. Jego .mcp.json uruchamia npx @playwright/mcp@latest bez flag, więc korzysta z trwałego profilu:

Okno terminala
claude plugin install playwright@claude-plugins-official

Sprawdź, czy serwer się załadował: uruchom /mcp w Claude Code lub Codex albo codex mcp list w terminalu i upewnij się, że playwright jest połączony. W Cursorze otwórz listę MCP w ustawieniach.

CLI instalujesz raz na maszynę, a skill w każdym repozytorium, żeby podróżował razem z kodem (przetestowane z @playwright/cli 0.1.21):

Okno terminala
npm install -g @playwright/cli@latest
playwright-cli --help
Okno terminala
playwright-cli install --skills

Domyślny cel to claude: polecenie zapisuje .claude/skills/playwright-cli/SKILL.md i folder references/ z przewodnikami o generowaniu testów, uruchamianiu testów, mockowaniu żądań, storage state i tracingu. Zacommituj ten folder. Dodaj --global, żeby zainstalować skill w katalogu domowym.

Frontmatter skilla z góry zatwierdza Bash(playwright-cli:*), Bash(npx:*) i Bash(npm:*) w agentach, które respektują allowed-tools. Przeczytaj tę linię, zanim zacommitujesz skill: npx:* i npm:* to więcej, niż potrzeba do testów w przeglądarce.

Flagi, które mają znaczenie, gdy agent steruje Playwright MCP

Dział zatytułowany „Flagi, które mają znaczenie, gdy agent steruje Playwright MCP”

Wszystkie flagi poniżej pochodzą z playwright-mcp --help i README w wersji 0.0.82. Każda ma też zmienną środowiskową, np. PLAYWRIGHT_MCP_ISOLATED.

FlagaCo robiKiedy ją ustawić
--isolatedTrzyma profil przeglądarki w pamięci i nie zapisuje go na dyskZawsze, gdy może działać więcej niż jeden agent; zawsze w CI
--headlessUruchamia przeglądarkę bez okna (domyślnie okno jest widoczne)Agenci w tle, CI, zdalne kontenery
--caps testingDodaje browser_generate_locator i narzędzia asercji browser_verify_*Gdy agent pisze testy na podstawie tego, co widzi
--caps networkDodaje browser_route, browser_unroute i browser_network_state_set do mockowania i trybu offlineOdtwarzanie błędu zależnego od odpowiedzi API
--caps vision,pdf,devtoolsNarzędzia myszy oparte na współrzędnych, eksport PDF, tracing i wideoInterfejsy oparte na canvasie, wyjście PDF, zapis trace’ów
--storage-state <path>Ładuje ciasteczka i local storage do izolowanego kontekstuTesty za logowaniem bez trwałego profilu
--user-data-dir <path>Używa wskazanego katalogu trwałego profiluGdy potrzebujesz trwałego profilu dla każdego agenta osobno
--console-level errorZwraca tylko komunikaty konsoli od tego poziomu w góręKrótsze wyjście konsoli
--output-dir <path>Dokąd trafiają automatycznie nazwane zrzuty ekranu i plikiZbieranie dowodów do pull requesta

Sprawdź stronę: otwórz cennik, kliknij Subscribe, zgłoś błędy

Dział zatytułowany „Sprawdź stronę: otwórz cennik, kliknij Subscribe, zgłoś błędy”

To pierwszy test, który warto uruchomić, bo odpowiada na pytanie, na które test jednostkowy nie odpowie: czy strona działa w przeglądarce? Najpierw uruchom serwer deweloperski. Prompt działa tak samo we wszystkich trzech narzędziach; różnią się tylko wywołania narzędzi, które zobaczysz.

Co zobaczysz z Playwright MCP: browser_navigate, browser_snapshot, browser_click (z referencją elementu ze snapshotu, np. e21), potem browser_console_messages z level: "error", browser_network_requests i browser_take_screenshot. browser_network_requests domyślnie pomija udane zasoby statyczne, więc lista jest krótka.

Co zobaczysz z Playwright CLI: te same kroki jako polecenia powłoki.

Okno terminala
playwright-cli open http://localhost:4321/en/pricing
playwright-cli snapshot
playwright-cli click e21
playwright-cli console error
playwright-cli requests
playwright-cli screenshot

Jeśli agent melduje „brak błędów”, a nie wywołał narzędzi konsoli i sieci, to zgadywał. Poproś go o pokazanie wyniku narzędzi.

Zamień zgłoszenie błędu w test regresyjny z Playwright

Dział zatytułowany „Zamień zgłoszenie błędu w test regresyjny z Playwright”

Test dymny dowodzi, że strona działa dziś. Test dowodzi, że będzie działać dalej. Poniższy proces warto przyjąć jako standard: agent odtwarza błąd w przeglądarce, pisze test Playwright, który nie przechodzi z właściwego powodu, poprawia kod i dowodzi, że ten sam test przechodzi. Runnerem jest @playwright/test (1.63.0 w npm, 2026-09-26), niezależnie od tego, którym sterownikiem agent eksploruje stronę.

  1. Daj agentowi zgłoszenie błędu i zabroń poprawki. Pierwszym rezultatem ma być test, który nie przechodzi, a nie łatka.

  2. Sprawdź, czy test nie przechodzi z właściwego powodu. Porażka musi wynikać z błędu ze zgłoszenia (brak żądania checkoutu albo TypeError), a nie z timeoutu na złym lokatorze czy z niedziałającego serwera. Test, który pada z niewłaściwego powodu, niczego nie dowodzi, gdy później przejdzie. Gdy test pada z właściwego powodu, zacommituj go osobno (test: reproduce pricing subscribe bug), żeby stan czerwony miał własny commit.

  3. Pozwól agentowi poprawić kod, a nie test.

    --repeat-each=5 uruchamia test pięć razy. Test, który przechodzi cztery razy na pięć, jest niestabilny, a nie naprawiony.

  4. Zostaw test w CI. Pull request zawiera dwa commity: najpierw czerwony test, potem poprawkę. Job CI uruchamia zestaw E2E z --fail-on-flaky-tests, więc test, który przechodzi dopiero przy ponowieniu, oblewa build, i sprawdza, czy plik testu nie zmienił się po czerwonym commicie:

    # .github/workflows/e2e.yml (kroki joba; checkout potrzebuje fetch-depth: 0)
    - run: npx playwright install --with-deps chromium
    # --retries=2 pozwala Playwrightowi wykryć niestabilny test; --fail-on-flaky-tests wtedy oblewa build
    - run: npx playwright test --retries=2 --fail-on-flaky-tests
    - name: Spec unchanged since the red commit
    run: |
    RED_SHA=$(git log --format=%H --grep='^test: reproduce pricing subscribe bug' -n 1)
    git diff --exit-code "$RED_SHA" HEAD -- tests/e2e/pricing-subscribe.spec.ts

    Krok z diffem oblewa build, jeśli commit z poprawką dotknął testu.

  5. Dołącz dowody. Pull request zawiera wynik czerwonego przebiegu z kroku 1, zielone przebiegi z kroku 3, trace i zrzut ekranu. Strona o pakiecie dowodów ma szablon, który robi z tych pól wymóg.

Z Playwright CLI skill skraca krok 1: każda akcja playwright-cli wypisuje odpowiadający jej kod Playwright w TypeScripcie (await page.getByRole('button', { name: 'Subscribe' }).click();), więc agent składa test z akcji, które już wykonał. Plik references/test-generation.md w skillu nazywa to cyklem plan, generate i heal. Z Playwright MCP to samo daje agentowi browser_generate_locator po włączeniu --caps testing.

Uruchom jednego agenta na worktree bez kolizji przeglądarek

Dział zatytułowany „Uruchom jednego agenta na worktree bez kolizji przeglądarek”

README Playwright MCP mówi wprost: „A persistent profile can only be used by one browser instance at a time, so concurrent MCP clients sharing the same workspace will conflict”. Rozwiązanie, które podaje: uruchom każdego kolejnego klienta z --isolated albo z osobnym --user-data-dir.

Domyślna ścieżka profilu kończy się na {workspace-hash}, wyliczonym z katalogu głównego workspace’u klienta, więc dwa worktree zwykle i tak dostają osobne profile. Dwóch agentów w tym samym checkoucie już nie, a hash zależy od tego, co klient zgłasza jako swój katalog główny. --isolated usuwa ten problem: każda sesja startuje z czystym profilem w pamięci, a od takiego profilu i tak powinien zaczynać test.

Profile przeglądarki to tylko połowa. Drugi współdzielony zasób to port serwera deweloperskiego:

Współdzielony zasóbCo idzie nie takUstawienie, które temu zapobiega
Profil Playwright MCPDruga przeglądarka nie startuje albo przejmuje logowanie innego agenta--isolated w commitowanym wpisie MCP
Sesja Playwright CLIDwóch agentów steruje tą samą nazwaną przeglądarkąUruchom każdego agenta z własnym PLAYWRIGHT_CLI_SESSION albo dodawaj -s=<nazwa> do każdego polecenia
Port serwera deweloperskiegoAstro, Vite i Next.js bez błędu przechodzą na kolejny wolny port; agent testuje serwer innego worktreeStała pula portów dla każdego worktree
reuseExistingServer w playwright.config.tsPlaywright podłącza się do tego, co już nasłuchuje na porcie, i raportuje zielony wynik dla kodu, którego w ogóle nie testowałWyliczaj baseURL, webServer.url i port serwera z jednej wartości per worktree

Dla Playwright CLI README proponuje zmienną środowiskową ustawianą przy starcie agenta. W worktree nazwij sesję od katalogu:

Okno terminala
PLAYWRIGHT_CLI_SESSION="$(basename "$PWD")" claude

playwright-cli list pokazuje wszystkie otwarte sesje, a playwright-cli show otwiera panel z podglądem na żywo każdej z nich. Pełną konfigurację worktree, z pulami portów, opisuje strona o wielu agentach naraz.

Jak udowodnić, że sprawdzenie w przeglądarce coś znaczy

Dział zatytułowany „Jak udowodnić, że sprawdzenie w przeglądarce coś znaczy”

Dzięki sprawdzeniu w przeglądarce deklarację agenta da się zweryfikować. Poprawność zmiany potwierdza ono jednak tylko wtedy, gdy mogło się nie powieść i gdy działa w miejscu, w którym agent nie osłabi go po cichu (w CI).

SprawdzenieCzego dowodziKto za nie odpowiada
Czerwony przebieg przed poprawką, z komunikatem błęduTest wykrywa ten błądAutor (agent); reviewer czyta komunikat
Zielone przebiegi z --repeat-each=5 --retries=0Poprawka działa, a test nie jest niestabilnyAutor (agent); CI uruchamia go ponownie
Plik testu bez zmian między commitem czerwonym a zielonymAgent poprawił kod, a nie testSprawdzenie diffu w CI; zobacz ochronę wyroczni
Zestaw E2E w CI z --fail-on-flaky-tests albo bez ponowieńZachowanie zostaje naprawione przy każdej kolejnej zmianieCI, blokująco
Trace i zrzut ekranu w pull requeścieReviewer może odtworzyć, co robiła przeglądarka, bez ponownego uruchamianiaAutor (agent)

Tech lead zatwierdza na podstawie tych dowodów. Drugą stronę tej pętli, czyli review, opisuje przegląd pull requesta od agenta.

Ile kontekstu kosztują Playwright MCP i Playwright CLI

Dział zatytułowany „Ile kontekstu kosztują Playwright MCP i Playwright CLI”

Zmierzone 2026-09-26 przez wylistowanie narzędzi @playwright/mcp 0.0.82 po stdio:

KonfiguracjaNarzędziaJSON schematów narzędzi
Domyślna25ok. 20 100 znaków
--caps testing,network34ok. 25 700 znaków
Wszystkie siedem grup możliwości72ok. 45 400 znaków
Skill Playwright CLI0 (polecenia powłoki)treść SKILL.md to 15 179 znaków, ładowana, gdy skill się uruchamia

Schematy to mniejszy koszt. Claude Code 2.1.283 i codex-cli 0.157.1 ładują schematy narzędzi MCP na żądanie, przez tool search. Większy koszt to snapshot drzewa dostępności, który Playwright MCP zwraca po każdej akcji: rośnie z wielkością strony i powtarza się przy każdym kliknięciu, więc dziesięciokrokowy przepływ na rozbudowanej stronie płaci za dziesięć snapshotów.

Jak to ograniczyć, od najtańszego sposobu:

  • Użyj Playwright CLI, które zapisuje snapshoty do plików.
  • W Playwright MCP proś o browser_snapshot z depth albo z elementem target, albo z filename, żeby zapisać snapshot zamiast go zwracać.
  • Uruchom serwer z --snapshot-mode none, gdy agent przechodzi znany przepływ i nie potrzebuje strony po każdym kroku.
  • Włączaj tylko te grupy --caps, których wymaga zadanie.
  • Długie sesje w przeglądarce przenieś do subagenta, żeby do głównej sesji wróciło tylko podsumowanie.

Zmierz to, zamiast ufać tabeli. W Claude Code uruchom /context przed testem dymnym strony cennika i po nim, raz z każdym sterownikiem. Ogólny wzorzec opisuje strona o obniżaniu kosztu tokenów MCP.

Stan na 2026-09-26: microsoft/playwright-mcp ma 37,6 tys. gwiazdek na GitHubie i figuruje w oficjalnym rejestrze MCP jako io.github.microsoft/playwright-mcp 0.0.82; plugin playwright ma 319 887 instalacji w katalogu pluginów Claude (claude.com/plugins). microsoft/playwright-cli ma 13,6 tys. gwiazdek na GitHubie, a jego skill 165 672 instalacje od początku według zewnętrznego zrzutu skills.sh (LinklyAI/best-skills, z 2026-09-26; dane z drugiej ręki, bo samego skills.sh nie dało się odczytać).

Przeglądarka nie startuje albo zgłasza zablokowany profil. Trwały profil trzyma inny agent albo wcześniejsza sesja. Wyjście: dodaj --isolated do wpisu MCP albo daj każdemu agentowi osobny --user-data-dir. Przy zawieszonej sesji CLI uruchom playwright-cli list, potem playwright-cli close-all, a jeśli procesy zostały, playwright-cli kill-all.

Nie ma zainstalowanej przeglądarki. Świeża maszyna albo kontener CI nie ma binarek przeglądarek i pierwsza nawigacja pada. Wyjście: uruchom npx playwright install chromium (na obrazach CI z Linuksem dodaj --with-deps) albo playwright-cli install-browser dla CLI. Kanał wybierzesz jawnie przez --browser chrome|firefox|webkit|msedge.

Test przeszedł na niewłaściwym serwerze. Serwer deweloperski przeszedł na kolejny wolny port, a agent albo reuseExistingServer trafił na serwer innego worktree. Wyjście: przypnij port dla każdego worktree, wyliczaj z niego baseURL i webServer.url i każ agentowi udowodnić, który serwer testował, tak jak robi to prompt dla worktree.

Agent zmienia test, aż przejdzie. Czerwony przebieg był prawdziwy, a zielony wziął się ze słabszej asercji. Wyjście: zrób z „plik testu bez zmian” sprawdzenie w CI i obejmij tests/e2e/ regułą deny albo CODEOWNERS, jak opisuje ochrona wyroczni.

Test jest niestabilny. Przechodzi lokalnie i pada w CI, często przez stały waitForTimeout albo selektor CSS. Wyjście: uruchom go ponownie z --repeat-each=10 --retries=0 i --trace=on, otwórz trace i poproś agenta o zastąpienie uśpień asercjami web-first, a selektorów CSS lokatorami opartymi na rolach.

Stan logowania znika. --isolated odrzuca ciasteczka po zamknięciu przeglądarki. Wyjście: zapisz storage state raz, przez projekt setup w konfiguracji Playwrighta (setup project) albo playwright-cli state-save auth.json. W Playwright MCP przekaż go przez --storage-state auth.json, a w Playwright CLI uruchom playwright-cli state-load auth.json. Trzymaj ten plik poza Gitem, bo zawiera ciasteczka sesji.

Okno kontekstu zapełnia się po kilku kliknięciach. Każda akcja MCP zwróciła pełny snapshot dużej strony. Wyjście: przełącz to zadanie na Playwright CLI albo użyj limitów snapshotu z poprzedniej sekcji.