Polityka E2E: dowód z przeglądarki dla każdej zmiany widocznej dla użytkownika

Polityka E2E dla oprogramowania budowanego przez agentów określa, jaki dowód musi nieść każda zmiana widoczna dla użytkownika przed merge’em. Agent sprawdza kryteria akceptacji w prawdziwej przeglądarce i zachowuje zrzuty ekranu, trace’y oraz logi konsoli i sieci. Krytyczne ścieżki stają się potem deterministycznymi testami CI, które pilnują każdej kolejnej zmiany. Przebieg w przeglądarce dokłada dowód, ale nigdy nie zastępuje deterministycznej bramki.

Ta strona jest dla CTO odpowiedzialnego za pytanie 12 w CTO Scorecard i dla tech leada, który tę zasadę egzekwuje. Typowa sytuacja: agenci otwierają już większość pull requestów frontendowych, testy jednostkowe są zielone, a opis PR mówi „sprawdzone w przeglądarce”. Potem na produkcję trafia strona cennika, na której przycisk zakupu nic nie robi na telefonie, i nikt nie potrafi pokazać, co sprawdzono, na jakim koncie i przy jakim viewporcie.

Q12 · Bramki jakości: Jakie są wymogi E2E przy zmianach UI?

Odpowiedź na maksymalny wynik: przebieg w przeglądarce oparty na kryteriach akceptacji, z zachowanym dowodem, a krytyczne ścieżki przeniesione do deterministycznych testów CI.

Co daje ci ta polityka E2E

• Tabelę punktacji Q12, która dla każdego poziomu wskazuje jedną kontrolę potrzebną do awansu
• Macierz dowodów według klasy ryzyka, z której każdy agent i recenzent odczyta, co musi udowodnić zmiana UI
• Konfigurację przeglądarki dla Claude Code, Codex i Cursora: izolowane sesje headless, które zapisują dowody na dysk
• Konfigurację Playwright i job CI, które kończą się błędem na niestabilnych testach, zamiast przepuszczać je dzięki ponowieniom
• Plik polityki do zatwierdzenia w repozytorium bez zmian i trzy prompty do skopiowania, które wytwarzają dowody
• Autotesty i cztery liczby do przeglądu, które pokazują, że polityka działa, bez oglądania każdego przebiegu

Ta strona opisuje zasadę organizacyjną. Praktyczną pętlę dewelopera znajdziesz w artykule o weryfikacji w przeglądarce prowadzonej przez agenta, a technikę pisania testów w automatyzacji testów end-to-end.

Jak punktowany jest każdy poziom Q12?

Scorecard przyznaje od 0 do 3 punktów. Każdy krok dodaje kontrolę, nie narzędzie.

Punkty	Co widzi scorecard	Co przenosi cię na kolejny poziom
0	Brak wymogu E2E; zmiany UI sprawdza się ręcznie albo wcale	Wybierz trzy ścieżki, na których firma zarabia lub traci pieniądze, i napisz dla każdej jeden test Playwright
1	Playwright lub Cypress są polecane, ale niewymagane	Ustaw zestaw krytycznych ścieżek jako wymagany status check na gałęzi domyślnej
2	E2E wymagane dla nowych ścieżek, z ręczną bramką	Wymagaj przebiegu w przeglądarce według kryteriów akceptacji z zachowanym dowodem w każdym PR widocznym dla użytkownika i przenoś stabilne krytyczne ścieżki do CI
3	Przebiegi w przeglądarce według kryteriów, z zachowanym dowodem; krytyczne ścieżki to deterministyczne testy CI	Utrzymaj ten poziom dzięki autotestom i przeglądowi opisanym niżej

Jakiego dowodu wymaga każda klasa zmiany UI?

Klasyfikuj zmianę według tego, co się zepsuje, gdy będzie błędna, a nie według liczby zmienionych linii. Klasa wyznacza dowód; szablon PR pyta o klasę.

Klasa ryzyka	Typowa zmiana	Przebieg agenta w przeglądarce	Deterministyczne CI	Akceptacja człowieka
Niska	Teksty, treść statyczna, style w obrębie jednego komponentu	Strona się ładuje; zrzuty ekranu przy viewportach z polityki; brak nowych błędów konsoli	Istniejący zestaw pozostaje zielony; automatyczne sprawdzenie linków i dostępności	Recenzent ogląda zrzuty ekranu
Średnia	Zachowanie komponentu, walidacja formularza, stan po stronie klienta	Jeden przebieg na kryterium akceptacji, z trace’em	Test komponentu lub integracyjny dla nowego zachowania	Code owner
Wysoka	Nowa ścieżka użytkownika, zmiana nawigacji, wszystko, co zapisuje dane	Przebieg na kryterium, łącznie z przypadkami negatywnymi	Test E2E ścieżki szczęśliwej i głównej ścieżki błędu, oznaczony @critical, jeśli chroni przychód lub dostęp	Code owner i właściciel produktu akceptują dowody
Krytyczna	Uwierzytelnianie, płatności, akcje destrukcyjne lub dotykające prywatności	Przebieg eksploracyjny wyłącznie na kontach syntetycznych	E2E z przypadkami negatywnymi, napisany lub zrecenzowany przez człowieka, nigdy nie edytowany przez agenta w tym samym PR	Imiennie wskazana osoba zatwierdzająca zgodnie z polityką bramek i barier

Dwie zasady obowiązują w każdej klasie. Agent przeglądarkowy nigdy nie dotyka danych produkcyjnych. A ocena wizualna agenta („układ wygląda poprawnie”) to dowód dla człowieka, nie zaliczenie.

Jak wdrożyć politykę?

1. Zapisz kryteria akceptacji jako obserwowalne zachowanie. Każde kryterium określa stan początkowy, rolę, viewport, akcje, oczekiwany interfejs, efekt w backendzie i jeden wynik, który nie może wystąpić. Format opisuje strona o wykonywalnych kryteriach akceptacji.

2. Daj agentom kontrolowane środowisko. Konta testowe przygotowane skryptem (seed), dane syntetyczne, lokalny lub efemeryczny stack i jawne sprzątanie. Poświadczenia produkcyjne nigdy nie trafiają do środowiska agenta; zobacz środowiska efemeryczne i zarządzanie danymi testowymi.

3. Zainstaluj każdemu agentowi izolowaną przeglądarkę. Przypięta wersja, przeglądarka headless, profil w pamięci i katalog na dowody. Polecenia są w następnej sekcji.

4. Zachowuj dowód dla każdego kryterium. PR zawiera tabelę: kryterium, wynik i ścieżkę do zrzutu ekranu lub trace’a, a do tego błędy konsoli i nieudane żądania sieciowe. Tabela trafia do pakietu dowodów, którego kompletność sprawdza CI.

5. Przenoś krytyczne ścieżki do testów. Gdy ścieżka jest stabilna i chroni przychód, dostęp lub dane, agent szkicuje test Playwright oznaczony @critical, a człowiek recenzuje asercje, nie selektory. Każda odtworzona regresja UI dostaje test w tym samym PR co poprawka.

6. Ustaw krytyczny zestaw jako wymagany check. Ochrona gałęzi wymaga go na gałęzi domyślnej. Przy pull_request CI uruchamia workflow, playwright.config.ts i testy z samego PR, więc PR może osłabić własną bramkę. Objęcie e2e/, playwright.config.ts i .github/workflows/ plikiem CODEOWNERS z wymaganą recenzją właściciela kodu sprawia, że agent nie zmieni testów @critical ani bramki w PR, w którym implementuje funkcję, bez zgody człowieka; zobacz ochronę wyroczni testowej.

Daj każdemu agentowi izolowaną przeglądarkę

Oficjalny serwer Playwright MCP (@playwright/mcp 0.0.82 w npm, sprawdzone 2026-09-26) działa we wszystkich trzech narzędziach. Flaga --isolated trzyma profil w pamięci, czego potrzebują agenci działający równolegle, bo trwały profil obsługuje naraz tylko jedną przeglądarkę. --output-dir zapisuje zrzuty ekranu tam, skąd tabela dowodów może do nich linkować. Flagi poniżej pochodzą z npx @playwright/mcp@0.0.82 --help.

Claude Code

Uruchom w katalogu głównym repozytorium. --scope project zapisuje .mcp.json, więc cały zespół dostaje ten sam przypięty serwer przez review.

claude mcp add --scope project playwright -- npx @playwright/mcp@0.0.82 \
  --isolated --headless --viewport-size 1280x720 --output-dir .evidence/browser

Claude Code ma też flagę --chrome dla integracji Claude in Chrome (claude --help, v2.1.283). Steruje ona twoją własną przeglądarką z twoimi sesjami, więc zostaw ją do eksploracji, a dowody na potrzeby polityki zbieraj przez izolowany serwer.

Codex

Uruchom w terminalu. codex mcp add zapisuje serwer w ~/.codex/config.toml; kopię projektową zatwierdzaj tylko wtedy, gdy zespół zarządza tak konfiguracją Codex.

codex mcp add playwright -- npx @playwright/mcp@0.0.82 \
  --isolated --headless --viewport-size 1280x720 --output-dir .evidence/browser

Codex 0.157.1 ma też wbudowane sterowanie przeglądarką i przeglądarkę w aplikacji, obie włączone domyślnie (codex features list). Przydają się do szybkiego podglądu; dowody na potrzeby polityki zbieraj przez przypięty serwer, aby każdy przebieg zapisywał pliki w tym samym miejscu.

Cursor

Dodaj serwer do .cursor/mcp.json w repozytorium. To standardowa konfiguracja mcpServers z README Playwright MCP (0.0.82); ten sam serwer dodasz też w Cursorze przez Cursor Settings → MCP → Add new MCP Server.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@0.0.82", "--isolated", "--headless",
               "--viewport-size", "1280x720", "--output-dir", ".evidence/browser"]
    }
  }
}

Dodaj .evidence/ do .gitignore i przesyłaj ten katalog jako artefakt CI. Gdy liczy się koszt kontekstu MCP, lżejszą alternatywą jest CLI agent-browser z własnym skillem (npm agent-browser 0.38.1); kompromisy opisują strony agent-browser i serwery MCP do automatyzacji przeglądarki.

Skonfiguruj warstwę deterministyczną

Przebieg w przeglądarce pokazuje, że zmiana zadziałała raz. Zestaw w CI dowodzi, że działa nadal. Cztery ustawienia sprawiają, że zestaw jest na tyle wiarygodny, by blokować merge. Każda opcja poniżej występuje w definicjach typów @playwright/test 1.63.0.

playwright.config.ts

import { defineConfig, devices } from '@playwright/test';

const baseURL = process.env.E2E_BASE_URL ?? 'http://localhost:3000';

export default defineConfig({
  testDir: './e2e',
  forbidOnly: !!process.env.CI,          // a stray test.only fails CI
  retries: process.env.CI ? 1 : 0,
  failOnFlakyTests: !!process.env.CI,    // pass-on-retry fails the run
  reporter: [['html', { open: 'never' }], ['list']],
  use: {
    baseURL,
    trace: 'retain-on-failure',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'desktop', use: { ...devices['Desktop Chrome'] } },
    { name: 'mobile', use: { ...devices['Pixel 7'] } },
  ],
  webServer: {
    command: 'npm run start:test',
    url: baseURL,
    reuseExistingServer: !process.env.CI, // CI always starts its own app
  },
});

Ustawieniem, które realizuje politykę, jest failOnFlakyTests. Ponowienie nadal się wykonuje, więc trace pokazuje różnicę między próbami, ale test, który za pierwszym razem zakończył się błędem, a potem przeszedł, sprawia, że cały job kończy się niepowodzeniem, zamiast zrobić się zielony. reuseExistingServer: !process.env.CI nie pozwala CI podłączyć się do obcego serwera, który już zajmuje port, i raportować zieleni dla kodu, którego nikt nie testował.

.github/workflows/e2e.yml

name: e2e
on:
  pull_request:
permissions: {}
jobs:
  e2e:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
      - uses: actions/upload-artifact@v7
        if: ${{ !cancelled() }}
        with:
          name: e2e-evidence
          path: |
            playwright-report/
            test-results/
          retention-days: 30

Job nie potrzebuje sekretów: testuje aplikację, którą sam uruchomił, na przygotowanych danych testowych. Oznacz e2e jako wymagany status check. Aby wymagana bramka pozostała szybka, gdy zestaw rośnie, jako wymagany job uruchamiaj npx playwright test --grep @critical, a pełny zestaw według harmonogramu.

Przyjmij politykę E2E

Zatwierdź politykę obok szablonu PR i scal ją przez code ownera platformy.

docs/policies/e2e.md

# E2E policy for user-visible changes

Owner: VP Engineering. Enforced by: tech leads. Reviewed: quarterly. Version: 1.

## Scope
Every pull request that changes what a user sees or does, whoever wrote it.

## Evidence by risk class
Low: screenshots at 1280x720 and 390x844, no new console errors.
Medium: browser run per acceptance criterion with trace, plus a
component or integration test.
High: as medium, plus E2E happy path and main failure path in CI.
Critical (auth, payment, destructive, privacy): E2E with negative cases,
written or reviewed by a person; named approver before merge.

## Environment
Seeded test accounts and synthetic data only. The browser agent never
holds production credentials or writes to production.

## Retention
Evidence table in the PR; screenshots, traces and logs as CI artifacts
for 30 days. No secrets or customer data in any artifact.

## Flaky tests
A flaky test fails CI. Quarantine only with an owner, an issue and a
fix-by date; quarantined @critical tests block release until fixed.

## Protected tests
@critical tests change only in a PR whose purpose is that change,
approved by the flow's code owner. Agents do not edit them while
implementing a feature.

## Review
Quarterly: escaped UI defects, flaky and quarantined tests, share of
user-visible PRs with complete evidence, and critical flows without a test.

Plik polityki zostawiamy po angielsku, bo prompty poniżej odwołują się do niego po nazwie i treści. Jeśli zespół pracuje po polsku, przetłumacz go, ale zachowaj nazwy klas ryzyka i tag @critical.

Prompty do skopiowania: dowody z przeglądarki

Wklej je do Claude Code, Codex lub Cursora ze skonfigurowanym serwerem Playwright. Pierwszy uruchamiasz przed implementacją, drugi po niej, a trzeci wtedy, gdy ścieżka jest gotowa, by stać się testem.

Prompt do skopiowania: zamiana kryteriów akceptacji w checklistę przeglądarkową

Read the acceptance criteria in the spec for this change. For each criterion, write a browser check with: starting state, test account role, viewport (1280x720 and 390x844), the exact actions, the expected visible result, the expected backend effect you can observe (a network request, a stored record, an email in the test inbox), and one outcome that must not happen. Add at least one negative case per criterion. Assign the change a risk class (low, medium, high, critical) using docs/policies/e2e.md and list the evidence that class requires. Do not start implementing.

Prompt do skopiowania: przebieg zmienionej ścieżki z zachowaniem dowodów

Start the app with npm run start:test and seed the test accounts. Using the Playwright MCP server, run only the browser checks for this change, at both viewports. For every check, save a screenshot to .evidence/browser with the criterion ID in the file name, and record console errors and failed network requests. Use synthetic data only and never connect to a production URL. Finish with a markdown table for the PR: criterion, pass or fail, evidence file, console errors, failed requests. Mark anything you judged visually as "needs human review" rather than pass.

Prompt do skopiowania: zamiana stabilnej ścieżki w deterministyczny test

From the passing browser checks for this change, pick the flows that guard revenue, access, or stored data. For each, write the smallest Playwright test in e2e/ that asserts the visible result and the backend effect, using getByRole or getByLabel locators and web-first assertions, with no fixed waits. Tag revenue and access flows @critical. Run npx playwright test --repeat-each 5 on the new tests and report any flaky result instead of adding retries. List what still needs human visual judgment. Do not modify any existing @critical test.

--repeat-each to opcja npx playwright test; pięć zielonych powtórzeń lokalnie to tani filtr niestabilności, zanim test stanie się wymaganą bramką.

Jak sprawdzić, że polityka działa, bez oglądania każdego przebiegu?

Testujesz samą politykę, a potem obserwujesz cztery liczby. Uruchom poniższe sprawdzenia przy wprowadzeniu polityki i po każdej zmianie joba CI lub konfiguracji Playwright.

Autotest	Jak go wykonać	Oczekiwany wynik
Wykrywanie niestabilności	Dodaj test, który nie przechodzi tylko przy pierwszej próbie	Job kończy się niepowodzeniem, a raport oznacza test jako niestabilny (flaky)
Zabłąkany test.only	Zatwierdź test.only na gałęzi	CI kończy się błędem, zanim uruchomi zestaw
Obcy serwer	Uruchom inną aplikację na porcie testowym, a potem CI lokalnie z CI=1	Playwright odmawia użycia zajętego portu, zamiast testować obcą aplikację
Chronione testy	Poproś agenta o funkcję sprzeczną z asercją @critical	Agent zgłasza konflikt; każda zmiana testu wymaga zatwierdzenia code ownera e2e/ przed merge’em (CODEOWNERS + wymagana recenzja code ownera)
Kompletność dowodów	Otwórz PR widoczny dla użytkownika bez tabeli dowodów	Sprawdzenie pakietu dowodów kończy się błędem
Brak dostępu do produkcji	Przeszukaj środowisko agenta i konfigurację MCP pod kątem hostów i kluczy produkcyjnych	Nic nie znaleziono

Co kwartał przeglądaj cztery liczby: defekty UI, które trafiły na produkcję, liczbę i wiek testów w kwarantannie, odsetek PR widocznych dla użytkownika z kompletnym dowodem oraz krytyczne ścieżki, które wciąż nie mają testu. Zdefiniuj je raz w panelu metryk AI. Rosnąca liczba defektów wykrytych dopiero na produkcji przy kompletnych dowodach oznacza zbyt słabe kryteria; rosnący wiek kwarantanny oznacza, że niestabilne testy są odkładane, a nie naprawiane.

Co psuje się w polityce E2E dla UI budowanego przez agentów?

Zrzuty ekranu bez kontraktu. Zrzut wygląda dobrze, choć akcja się nie powiodła, użyto złego konta albo backend niczego nie zmienił. Wyjście: każde kryterium musi nazywać efekt w backendzie, a dowód będący samym obrazkiem jest odrzucany.

Ponowienia zamieniają niestabilne testy w zieleń. Zestaw z retries: 2 i bez bramki na niestabilność przepuszcza testy, które oblewają co trzeci raz, a agenci uczą się, że czerwień jest przejściowa. Wyjście: ustaw failOnFlakyTests, kwarantannę prowadź z właścicielem i terminem, a test @critical w kwarantannie traktuj jako blokadę wydania.

Agent zmienia test, żeby pasował do błędu. Poproszony, by „E2E przeszło”, agent luzuje asercję albo aktualizuje wizualny baseline. Wyjście: CODEOWNERS na e2e/ i baseline’ach, zasada chronionych testów w polityce oraz revert każdej zmiany baseline’u, która przyszła w PR z funkcją.

Agent przeglądarkowy sięga po prawdziwe dane. Zapisany profil albo skopiowany .env daje agentowi zalogowaną sesję produkcyjną. Wyjście: --isolated na każdym serwerze, wyłącznie przygotowane konta testowe i brak poświadczeń produkcyjnych w środowisku agenta. Jeśli do tego doszło, zrotuj poświadczenia i poprowadź sprawę według runbooka incydentów z agentami.

Agenci działający równolegle dzielą jeden profil przeglądarki. Dwa worktree korzystające z trwałego profilu wchodzą sobie w drogę, a przebiegi padają w sposób, który wygląda jak błąd produktu. Wyjście: --isolated albo osobny --user-data-dir dla każdego worktree i osobny port aplikacji dla każdego worktree.

Ocena wizualna uchodzi za zaliczenie. Agent, który mówi „układ wygląda poprawnie”, wyraził opinię. Wyjście: kieruj jakość układu i zgodność z marką do recenzenta-człowieka ze zrzutami ekranu albo do skalibrowanego sędziego z rubryką, jak w kontrolach ocenianych przez model, a dostępność zostaw automatycznym kontrolom semantycznym z testowania dostępności.

Dokąd dalej z dowodami E2E

Umieść tę zasadę w etapie testów, a potem przenieś jej dowody do review.

Etap testów Macierz dowodów dla każdego rodzaju zmiany.

Weryfikacja w przeglądarce przez agenta Pętla dewelopera stojąca za tą polityką.

Pakiet dowodów Gdzie w PR trafiają dowody z przeglądarki.

Q9 · Automatyzacja review Przenieś dowody z przeglądarki do decyzji o merge’u.

Q13 · AI w CI/CD Agenci w potoku bez oddawania im bramki.

Klucz odpowiedzi CTO Scorecard Każde pytanie scorecardu i jego kanoniczna strona.