Weryfikacja w przeglądarce przez agenta — udowodnij flow użytkownika

Weryfikacja w przeglądarce przez agenta polega na tym, że agent kodujący wykonuje zmieniony flow użytkownika w prawdziwej, izolowanej przeglądarce, porównuje go z zapisanymi kryteriami akceptacji i rejestruje akcje, asercje, błędy konsoli oraz nieudane żądania sieciowe. Krytyczne flow stają się potem deterministycznymi testami Playwright w CI, bo przebieg agenta dowodzi jednej zmiany, a nie chroni przed regresją.

Ta strona jest dla dewelopera, u którego agent buduje już większość frontendu. Testy jednostkowe przechodzą, pull request mówi „sprawdzone w przeglądarce”, a dwa dni później ktoś odkrywa, że przycisk Save pokazuje komunikat o sukcesie, choć nazwa nigdy nie trafia do bazy. Nikt nie potrafi powiedzieć, co agent kliknął, na jakim koncie i czy w ogóle przeładował stronę.

Scorecard Q16: Jak weryfikujesz działanie interfejsu i testy end-to-end (E2E) w przeglądarce?

Odpowiedź na maksymalny wynik: agent wykonuje flow z kryteriów akceptacji, zbiera powtarzalny dowód i przenosi krytyczne ścieżki do deterministycznych testów CI.

Co zyskasz dzięki weryfikacji w przeglądarce przez agenta

• Wybór między Playwright MCP, Playwright CLI ze skillem i agent-browser, oraz wskazówka, kiedy koszt kontekstu powinien skłonić cię do CLI
• Konfigurację dla Claude Code, Codex i Cursora, w której każdy agent dostaje izolowaną przeglądarkę headless zapisującą dowody na dysk
• Format scenariusza przeglądarkowego, który agent wykonuje i którego nie może po cichu zinterpretować po swojemu
• Trzy prompty do skopiowania: zweryfikuj flow, zamień go w test Playwright i zdiagnozuj porażkę
• Sposób, by udowodnić, że nowy test łapie błąd, bez czytania go linijka po linijce
• Tryby awarii, które zamieniają sprawdzanie w przeglądarce w zielony teatr, i sposób wyjścia z każdego z nich

Reguła dla całej organizacji (jaka zmiana potrzebuje jakiego dowodu, retencja, chronione testy) jest na stronie polityki E2E. Technika pisania testów, czyli page objecty, fixture’y uwierzytelniania i regresja wizualna, jest w automatyzacji testów end-to-end. Ta strona opisuje pętlę dewelopera pomiędzy nimi.

Jak punktowane jest Q16 i co podnosi wynik?

Scorecard przyznaje od zera do trzech punktów. Każdy poziom dokłada kontrolę, nie narzędzie.

Punkty	Twoja odpowiedź dziś	Następny krok
0	Brak testów w przeglądarce; ręczne wyklikiwanie po wdrożeniu	Napisz jeden scenariusz przeglądarkowy dla flow zmienionego w zeszłym tygodniu i każ agentowi uruchomić go lokalnie
1	Ręczne przeklikanie lokalnie po zakończeniu pracy agenta	Daj agentowi własną przeglądarkę, żeby przeklikanie odbyło się z dowodem, zanim ty spojrzysz
2	Zestaw testów Playwright lub Cypress uruchamiany komendami w terminalu	Powiąż każdy przebieg agenta z kryteriami akceptacji i trzymaj dowód w pull requeście
3	Flow z kryteriów akceptacji, powtarzalny dowód, krytyczne ścieżki w deterministycznych testach CI	Pilnuj uczciwości: udowodnij, że każdy nowy test pada bez poprawki, i chroń go przed cichymi zmianami

Którą przeglądarką powinien sterować agent?

Wszystkie trzy opcje poniżej to deterministyczne sterowniki: każde kliknięcie wybiera agent kodujący, a narzędzie raportuje, co się stało. Wybieraj według tego, ile kontekstu możesz wydać i co obsługuje twój klient.

Narzędzie	Forma	Najlepsze do	Na co uważać
Playwright MCP (@playwright/mcp, Microsoft)	Serwer MCP po stdio; snapshoty drzewa dostępności, zrzuty ekranu opcjonalnie	Domyślny wybór we wszystkich trzech narzędziach; wbudowane narzędzia konsoli i sieci	Schematy narzędzi i snapshoty stron zużywają kontekst przy każdym kroku
Playwright CLI (@playwright/cli, Microsoft)	Komendy powłoki plus skill dla agenta	Długie sesje, w których liczy się kontekst; sam README Playwright MCP poleca je agentom kodującym	Wymaga narzędzia powłoki; skill trzeba zainstalować w workspace albo globalnie
agent-browser (Vercel Labs)	CLI w Rust plus cienki skill	Szybkie przejścia QA z krótkimi referencjami elementów (@e2)	Krótkie referencje @eN i cienki skill oszczędzają kontekst, ale to trzecie narzędzie do nauki, jeśli zespół już standaryzuje się na Playwright

Claude Code i Codex mają też wbudowane przeglądarki: flaga --chrome w Claude Code włącza integrację Claude in Chrome (claude --help, v2.1.283), a Codex 0.157.1 ma włączone browser_use i in_app_browser (codex features list). Obie sterują przeglądarką, która może nieść twoje zalogowane sesje. Używaj ich do eksploracji, a dowód dołączany do pull requestu zbieraj w izolowanej przeglądarce.

Do trace’ów wydajności i audytów Lighthouse użyj Chrome DevTools MCP; porównanie jest na stronie o serwerach MCP do przeglądarki, a kompromis MCP kontra CLI na stronie Playwright MCP.

Podłącz izolowaną przeglądarkę do Claude Code, Codex i Cursora

Uruchom te komendy w katalogu głównym repozytorium. Flagi pochodzą z npx @playwright/mcp@0.0.83 --help: --isolated trzyma profil w pamięci, --headless nie potrzebuje ekranu, a --output-dir zapisuje zrzuty tam, gdzie pull request może je podlinkować. Trwały profil obsługuje naraz tylko jedną przeglądarkę, więc równoległe agenty w osobnych worktree potrzebują --isolated.

Claude Code

--scope project zapisuje .mcp.json, więc zespół przegląda i współdzieli jeden przypięty serwer.

claude mcp add --scope project playwright -- npx @playwright/mcp@0.0.83 \
  --isolated --headless --output-dir .evidence/browser
claude mcp list   # sprawdź, czy serwer się łączy

Codex

codex mcp add zapisuje serwer w ~/.codex/config.toml. To wpis na poziomie użytkownika, więc każdy deweloper uruchamia go raz; względny --output-dir liczy się od katalogu, w którym startuje Codex.

codex mcp add playwright -- npx @playwright/mcp@0.0.83 \
  --isolated --headless --output-dir .evidence/browser
codex mcp list    # sprawdź wpis

Cursor

Dodaj projektowy .cursor/mcp.json w kształcie, który README Playwright MCP opisuje dla Cursora, a potem włącz serwer w ustawieniach MCP Cursora.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@0.0.83", "--isolated", "--headless", "--output-dir", ".evidence/browser"]
    }
  }
}

Jeśli wolisz ścieżkę przez CLI, zainstaluj je raz i dodaj skill do workspace. install --skills przyjmuje claude (domyślnie) albo agents, które zapisuje do .agents/skills/.

npm install -g @playwright/cli@0.1.22     # sprawdzone z 0.1.22; nie przestarzały pakiet "playwright-cli" bez scope
playwright-cli install --skills claude    # zapisuje .claude/skills/playwright-cli/; albo: --skills agents

Dodaj .evidence/ do .gitignore; zrzuty ekranu należą do artefaktów CI albo do pull requestu, nie do historii repozytorium.

Uruchom zmieniony flow na podstawie kryteriów akceptacji

Agent weryfikuje tylko to, co zapisałeś. Mglisty warunek w rodzaju „ustawienia działają” pozwala mu ogłosić sukces po samym otwarciu strony. Napisz scenariusz, zanim agent zacznie budować, obok reszty specyfikacji.

1. Dodaj scenariusz przeglądarkowy do spec.md. Nazwij stan początkowy, akcje, obserwowalny wynik i oczekiwany dowód:

   Scenario: an authenticated user renames the workspace
   Given: a disposable local account "qa+rename@example.test" with workspace "Acme"
   When: the user opens /settings, enters "Northstar" in "Workspace name", and clicks Save
   Then: a "Saved" status appears, and "Northstar" is still shown after a full reload
   Evidence: numbered actions, accessibility snapshot after reload, screenshot,
             console errors, status of the save request

2. Przygotuj czyste środowisko lokalne albo testowe. Nigdy nie kieruj agenta działającego bez nadzoru na dane produkcyjne, prawdziwe płatności ani konta w usługach zewnętrznych.

3. Poproś agenta o dokładne wykonanie scenariusza pierwszym promptem poniżej. Zwraca PASS, FAIL albo BLOCKED oraz blok dowodów.

4. Jeśli wynik to FAIL, przejdź do diagnozy trzecim promptem. Nie pozwól, żeby ten sam przebieg edytował kod.

5. Jeśli flow jest krytyczny dla biznesu (logowanie, płatność, uprawnienia, akcje destrukcyjne), zamień go w test Playwright drugim promptem.

Prompt do skopiowania: zweryfikuj zmieniony flow w przeglądarce

Read the browser scenario "an authenticated user renames the workspace" in spec.md.
Start the dev server with the command documented in AGENTS.md and wait until it responds.
Using the Playwright browser tools, execute exactly the scenario's actions, in order.
After the save, reload the page and take an accessibility snapshot and a screenshot.
Collect console errors and the HTTP status of every non-GET request.

Return:
- RESULT: PASS, FAIL or BLOCKED
- a numbered list of the actions you performed
- each "Then" clause with observed evidence next to it
- console errors and failed requests (or "none")
- paths of the files you saved

Do not edit code, do not change the scenario, and do not report PASS for a clause
you did not observe in the browser. If the environment will not start, return BLOCKED.

Dobry wynik wygląda tak i trafia do pull requestu bez zmian:

Browser verification: PASS
Environment: local dev server, fresh seed
Actions: 1 open /settings · 2 fill "Workspace name" = "Northstar" · 3 click Save · 4 reload
Then: "Saved" status seen after step 3 · "Northstar" in the field after step 4
Console/network: no errors · PATCH /api/workspace 200
Files: .evidence/browser/settings-after-reload.png

Zamień stabilny flow w test Playwright

Przebieg agenta w przeglądarce dowodzi zmiany raz, na jednej maszynie. Krytyczne flow potrzebują testu, który uruchamia się przy każdej kolejnej zmianie, także tej zrobionej przez agenta, który nigdy nie czytał tego scenariusza. Trzymaj test mały i sprawdzaj wynik ważny dla użytkownika, a nie szczegóły implementacji:

tests/e2e/settings-rename.spec.ts

import { test, expect } from '@playwright/test';

test('workspace rename persists after reload', async ({ page }) => {
  await page.goto('/settings');
  await page.getByLabel('Workspace name').fill('Northstar');
  await page.getByRole('button', { name: 'Save' }).click();
  await expect(page.getByRole('status')).toHaveText(/saved/i);
  await page.reload();
  await expect(page.getByLabel('Workspace name')).toHaveValue('Northstar');
});

Prompt do skopiowania: zamień scenariusz w test Playwright

Convert the passing scenario "an authenticated user renames the workspace" from spec.md
into one Playwright test in tests/e2e/settings-rename.spec.ts.

Rules:
- use getByRole, getByLabel or getByTestId locators; no CSS classes, no XPath
- assert the persisted outcome after a reload, not only the toast
- no waitForTimeout; rely on web-first assertions
- reuse the existing auth fixture instead of logging in through the UI

Then run: npx playwright test tests/e2e/settings-rename.spec.ts --repeat-each=5 --retries=0 --trace=on
Report the command and the pass count. If any run fails, fix the test or report the
product bug; do not add retries, sleeps or test.skip to make it pass.

Playwright ma też Test Agents: planera, generatora i healera. npx playwright init-agents --loop=claude (z @playwright/test 1.63.0) zapisuje trzy subagenty w .claude/agents/, wpis serwera playwright-test w .mcp.json, plik seed.spec.ts i katalog specs/ na plany. --loop=codex zapisuje agenty w .codex/agents/. Wersja 1.63.0 nie ma pętli dla Cursora (dostępne są claude, codex, copilot, opencode, vscode i vscode-legacy), więc w Cursorze użyj serwera MCP z góry i tych samych promptów.

Healer potrafi zazielenić czerwony test, zmieniając to, co test sprawdza

Wygenerowane instrukcje healera pozwalają na „fixing assertions and expected values”, a gdy jest pewny, że test jest poprawny, na oznaczenie go test.fixme(), czyli pominięcie. Oba ruchy zamieniają prawdziwą regresję w zielony przebieg. Przeglądaj każdy diff healera, który dotyka linii z expect albo dodaje fixme, i zobacz, jak chronić wyrocznię testową przed edycjami agenta.

Skąd wiesz, że sprawdzenie w przeglądarce czegoś dowiodło, jeśli go nie oglądasz?

Nie musisz czytać transkryptu agenta ani każdej linijki testu. Potrzebujesz czterech faktów, które da się sprawdzić maszynowo.

1. Test pada bez zmiany. Zatwierdź zmianę, pobierz gałąź bazową do osobnego worktree, uruchom tam nowy test i potwierdź, że jest czerwony; twój własny checkout zostaje nietknięty. Test, który przechodzi na starym kodzie, nie chroni flow. Szczegóły tego sprawdzenia są na stronie o sile wyroczni testowej.
2. Test jest stabilny. --repeat-each=5 --retries=0 przechodzi pięć razy na pięć. W CI dodaj --fail-on-flaky-tests, żeby ponowienie nigdy nie zazieleniło niestabilnego testu.
3. Dowód prowadzi do kryterium. Przy każdej klauzuli „Then” w bloku dowodów stoi obserwacja, a ścieżki plików istnieją w artefaktach CI.
4. CI uruchamia test tam, gdzie agent nie może go edytować. Job Playwright działa przy każdym pull requeście, a zmiany w tests/e2e/ wymagają wskazanego recenzenta przez CODEOWNERS.

Prompt do skopiowania: udowodnij, że nowy test łapie błąd

Prove that tests/e2e/settings-rename.spec.ts detects the bug it was written for.
The change is committed on this branch; the base branch is origin/main.
1. Run: git worktree add ../base origin/main   (a clean checkout of the old code)
2. Copy tests/e2e/settings-rename.spec.ts into ../base/tests/e2e/, install
   dependencies in ../base, and run the test there once. It must FAIL.
   Record the failing assertion.
3. Run: git worktree remove --force ../base   (this checkout was never touched)
4. In this checkout, run the test with --repeat-each=5 --retries=0. It must pass 5/5.
Report both outputs. If step 2 passes, the test does not cover the change:
say which assertion is missing and stop.

Zatwierdzenie zostaje przy ludziach i CI: job CI jest bramką merge’a, a recenzent sprawdza blok dowodów i dowód „czerwony, potem zielony”, zamiast ręcznie powtarzać flow. Pełny kontrakt pull requestu opisuje paczka dowodów.

Prompt do skopiowania: zdiagnozuj nieudany scenariusz

The scenario "an authenticated user renames the workspace" returned FAIL.
Reset to a fresh seed and reproduce it once more with the Playwright browser tools.
Compare expected and observed behavior clause by clause. Inspect console messages and
the request and response of the save call. Identify the owning code path (file and
function). Stop after diagnosis: do not edit code until I confirm the cause.

Co się psuje, gdy agent weryfikuje flow w przeglądarce?

Awaria	Co widzisz	Jak wyjść
Zielony teatr	PASS po samym otwarciu strony albo zrzut ekranu bez listy akcji	Odrzucaj dowód bez ponumerowanych akcji i obserwacji przy każdej klauzuli „Then”; pierwszy prompt to wymusza
Asercja tylko na komunikat	Komunikat o sukcesie się pojawia, ale dane nie zostały zapisane	Dodaj do scenariusza przeładowanie albo drugą stronę i sprawdź wartość tam
Współdzielony profil przeglądarki	Równoległe agenty nie mogą uruchomić przeglądarki albo jeden widzi logowanie drugiego	Uruchamiaj każdy serwer z --isolated albo daj każdemu worktree własny --user-data-dir
Nie ten serwer deweloperski	Przebieg przechodzi na serwerze innego worktree na domyślnym porcie	Przypnij port każdego worktree i podaj w prompcie dokładny URL do otwarcia
Healer osłabia test	Czerwony test robi się zielony po zmianie expect albo po test.fixme()	Wymagaj review każdego diffu, który dotyka asercji w tests/e2e/; uruchom ponownie prompt „czerwony, potem zielony”
Niestabilny lokator albo timing	Przechodzi trzy razy, pada w CI	Zastąp selektory CSS i uśpienia lokatorami ról i asercjami web-first; uruchom --repeat-each przed merge’em
Wyczerpany kontekst	Długie sesje zwalniają albo gubią wcześniejsze instrukcje	Przenieś długie flow na Playwright CLI albo dziel je na jeden scenariusz na sesję
Niezaufana treść strony	Tekst na stronie każe agentowi zrobić coś spoza scenariusza	Testuj tylko środowiska lokalne albo jednorazowe; --allowed-origins zawęża żądania, ale według własnego opisu „does not serve as a security boundary”

Dokąd dalej z weryfikacją w przeglądarce

Test: daj sesji pętlę informacji zwrotnej Etap cyklu życia, do którego należy ta strona: checki, definicja ukończenia i weryfikator w świeżym kontekście.

Automatyzacja testów end-to-end Page objecty, fixture’y uwierzytelniania, regresja wizualna i konfiguracja wielu przeglądarek.

Polityka E2E dla UI budowanego przez agentów Reguła zespołu: dowód według klasy ryzyka, retencja i chronione testy.

agent-browser CLI i skill Vercel Labs do szybkich przejść QA w przeglądarce.

Q17 · Ciągłe ewaluacje Zamień zaobserwowane błędy agenta w powtarzalne przypadki ewaluacji.

Q18 · Warstwowy review PR Sprawdź zachowanie, bezpieczeństwo i dowody przed merge’em.