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.
Co znajdziesz na tej stronie
Dział zatytułowany „Co znajdziesz na tej stronie”- 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,--headlessi--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 MCP | Playwright 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 agent | Narzędzia MCP (browser_navigate, browser_snapshot, …) | Polecenia powłoki (playwright-cli goto, playwright-cli snapshot, …) |
| Stan strony po każdej akcji | W wyniku narzędzia | Zapisany do pliku; agent czyta go na żądanie |
| Domyślny profil przeglądarki | Trwały, na dysku, jeden na workspace | W pamięci; --persistent zapisuje go na dysk |
| Działa w | Każdym kliencie MCP | Każdym agencie, który uruchamia polecenia powłoki; skill wymaga agenta ładującego skille |
| Najlepszy do | Sesji eksploracyjnych, obserwowania widocznej przeglądarki, klientów bez powłoki | Agentó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):
claude mcp add --scope project playwright -- npx @playwright/mcp@0.0.82 --isolated --headlessPolecenie 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:
claude plugin install playwright@claude-plugins-officialPrzetestowane na codex-cli 0.157.1:
codex mcp add playwright -- npx @playwright/mcp@0.0.82 --isolated --headlessPolecenie zapisuje globalny wpis w ~/.codex/config.toml:
[mcp_servers.playwright]command = "npx"args = ["@playwright/mcp@0.0.82", "--isolated", "--headless"]Wpis jest globalny, więc dotyczy każdej sesji w Codex na tej maszynie, także sesji uruchomionych z codex --worktree. To powód, żeby --isolated w nim było. Linia z README to codex mcp add playwright npx "@playwright/mcp@latest".
Dodaj serwer w Cursor Settings > MCP > Add new MCP Server jako typ command z poleceniem npx @playwright/mcp@latest albo wpisz standardową konfigurację do .cursor/mcp.json (kształt z README Playwright MCP; nie testowano w binarce Cursora):
{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@0.0.82", "--isolated", "--headless"] } }}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.
Zainstaluj Playwright CLI i jego skill
Dział zatytułowany „Zainstaluj Playwright CLI i jego skill”CLI instalujesz raz na maszynę, a skill w każdym repozytorium, żeby podróżował razem z kodem (przetestowane z @playwright/cli 0.1.21):
npm install -g @playwright/cli@latestplaywright-cli --helpplaywright-cli install --skillsDomyś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.
playwright-cli install --skills agentsPolecenie zapisuje ten sam skill do .agents/skills/playwright-cli/, czyli folderu repozytorium, który Codex przeszukuje w poszukiwaniu współdzielonych skilli (zobacz workflow zespołowe w Codex). Uruchom /skills w sesji w Codex, żeby sprawdzić, czy skill jest na liście.
playwright-cli install --skills agentsPolecenie zapisuje skill do .agents/skills/playwright-cli/. Folderów skilli Cursora nie dało się 2026-09-26 sprawdzić na cursor.com, więc potwierdź w Cursorze, że skill się pojawił. Jeśli nie, użyj ścieżki bez skilli z README: każ agentowi uruchomić playwright-cli --help i pracować na liście poleceń.
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.
| Flaga | Co robi | Kiedy ją ustawić |
|---|---|---|
--isolated | Trzyma profil przeglądarki w pamięci i nie zapisuje go na dysk | Zawsze, gdy może działać więcej niż jeden agent; zawsze w CI |
--headless | Uruchamia przeglądarkę bez okna (domyślnie okno jest widoczne) | Agenci w tle, CI, zdalne kontenery |
--caps testing | Dodaje browser_generate_locator i narzędzia asercji browser_verify_* | Gdy agent pisze testy na podstawie tego, co widzi |
--caps network | Dodaje browser_route, browser_unroute i browser_network_state_set do mockowania i trybu offline | Odtwarzanie błędu zależnego od odpowiedzi API |
--caps vision,pdf,devtools | Narzędzia myszy oparte na współrzędnych, eksport PDF, tracing i wideo | Interfejsy oparte na canvasie, wyjście PDF, zapis trace’ów |
--storage-state <path> | Ładuje ciasteczka i local storage do izolowanego kontekstu | Testy za logowaniem bez trwałego profilu |
--user-data-dir <path> | Używa wskazanego katalogu trwałego profilu | Gdy potrzebujesz trwałego profilu dla każdego agenta osobno |
--console-level error | Zwraca 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 pliki | Zbieranie 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.
playwright-cli open http://localhost:4321/en/pricingplaywright-cli snapshotplaywright-cli click e21playwright-cli console errorplaywright-cli requestsplaywright-cli screenshotJeś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ę.
-
Daj agentowi zgłoszenie błędu i zabroń poprawki. Pierwszym rezultatem ma być test, który nie przechodzi, a nie łatka.
-
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. -
Pozwól agentowi poprawić kod, a nie test.
--repeat-each=5uruchamia test pięć razy. Test, który przechodzi cztery razy na pięć, jest niestabilny, a nie naprawiony. -
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 commitrun: |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.tsKrok z diffem oblewa build, jeśli commit z poprawką dotknął testu.
-
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ób | Co idzie nie tak | Ustawienie, które temu zapobiega |
|---|---|---|
| Profil Playwright MCP | Druga przeglądarka nie startuje albo przejmuje logowanie innego agenta | --isolated w commitowanym wpisie MCP |
| Sesja Playwright CLI | Dwó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 deweloperskiego | Astro, Vite i Next.js bez błędu przechodzą na kolejny wolny port; agent testuje serwer innego worktree | Stała pula portów dla każdego worktree |
reuseExistingServer w playwright.config.ts | Playwright 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:
PLAYWRIGHT_CLI_SESSION="$(basename "$PWD")" claudeplaywright-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).
| Sprawdzenie | Czego dowodzi | Kto za nie odpowiada |
|---|---|---|
| Czerwony przebieg przed poprawką, z komunikatem błędu | Test wykrywa ten błąd | Autor (agent); reviewer czyta komunikat |
Zielone przebiegi z --repeat-each=5 --retries=0 | Poprawka działa, a test nie jest niestabilny | Autor (agent); CI uruchamia go ponownie |
| Plik testu bez zmian między commitem czerwonym a zielonym | Agent poprawił kod, a nie test | Sprawdzenie 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 zmianie | CI, blokująco |
| Trace i zrzut ekranu w pull requeście | Reviewer może odtworzyć, co robiła przeglądarka, bez ponownego uruchamiania | Autor (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:
| Konfiguracja | Narzędzia | JSON schematów narzędzi |
|---|---|---|
| Domyślna | 25 | ok. 20 100 znaków |
--caps testing,network | 34 | ok. 25 700 znaków |
| Wszystkie siedem grup możliwości | 72 | ok. 45 400 znaków |
| Skill Playwright CLI | 0 (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_snapshotzdepthalbo z elementemtarget, albo zfilename, ż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.
Jak popularne są Playwright MCP i Playwright CLI?
Dział zatytułowany „Jak popularne są Playwright MCP i Playwright CLI?”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ć).
Kiedy Playwright MCP albo Playwright CLI zawodzi
Dział zatytułowany „Kiedy Playwright MCP albo Playwright CLI zawodzi”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.