When the agent opens a PR, CI verifies it with E2E, and if it fails, it blocks the merge and leaves a comment on the PR, and uploads the trace as an artifact. This skill starts from that point of failure and has the agent perform the exact flow a human developer used to do — look at the CI logs → find the cause with the trace → fix it and push again — thereby closing the "self-improvement loop of working and verifying with tests."
This skill workflow and judgment. The Playwright/browser CLI syntax itself is already covered by the playwright-cli skill, so it is not repeated here and is referenced. The new value is "what / why / when," not a command dictionary.
When to stop and take a different path (decide first)
- If the starting point is a CI failure (red PR check / failed Actions run) , then → this skill. Continue.
- If the starting point is "write a new scenario as a test," then → not this skill. Planning is
e2e-flow-planner, code generation ise2e-test-generator로. - If you already have a local trace.zip / failing spec namein hand and do not need to locate the CI coordinates, then → go straight to
e2e-test-healer. The value of this skill is the front and back halves of "bringing a CI failure down to a local trace and closing the PR loop." - If the cause of the failure turns out to be a product code regression rather than the test, then → do not force the test to pass; report that fact clearly. Tests are a signal; do not kill the signal (the core of this judgment is handled by Healer).
- If it is a trivial failure where the logs immediately tell you the cause (a typo in an import, an obvious selector change), then → you do not need to fetch the trace. Jump to step 4.
Workflow (4 steps that tie it all together at once)
The core value lies in connecting these four steps seamlessly . Each step produces the evidenceneeded to move on to the next step.
1. 실패 식별 → 어떤 run·job·테스트가 왜 빨간지 확정 (증거: run-id, 실패 테스트명, 실패 단계 로그)
2. trace 수거 → 그 run의 아티팩트를 로컬로 다운로드 (증거: 로컬 trace.zip 경로)
3. 원인 분석 → trace를 열어 실패 순간의 DOM·네트워크·타이밍 확인 (증거: 한 줄 근본 원인 + 깨진 위치)
4. 픽스 & 재검증 → 테스트(또는 코드)를 고쳐 같은 PR에 push → CI 재실행 관찰 (증거: 초록 체크)
1. Identify the failure — confirm what is red and why
The input is usually one of two things: a PR number/URL or a failed Actions run URL. First, locate the coordinates.
# PR에서 출발: 어떤 체크가 깨졌는지 + 실패한 체크의 run 링크
gh pr checks <PR-번호 또는 URL>
# run URL에서 출발: .../actions/runs/<RUN_ID> 의 RUN_ID 를 기억
# 실패한 단계만 골라 로그 확인 (전체 로그 말고 실패 부분만)
gh run view <RUN_ID> --log-failed
What must be confirmed: run-id, the name of the failing test spec, whether the failure is an assertion, a timeout, or a setup step. Without this, even if you fetch the trace, you will not know where to look.
For a collection of deep diagnostic commands, see references/ci-diagnosis.md — for when you cannot find which workflow/job is E2E in a monorepo, when dealing with a re-run run with multiple attempts, etc.
2. Retrieve trace — artifacts to local
In CI, Playwright uploads the trace of the failing case as a zip artifact (common names: playwright-trace, playwright-report, trace, test-results). If you don't know the name, list them first.
# run의 아티팩트 목록 확인 (이름 모를 때)
gh api repos/{owner}/{repo}/actions/runs/<RUN_ID>/artifacts --jq '.artifacts[].name'
# 이름을 알면 그 아티팩트만 받아 작업 폴더에 푼다
gh run download <RUN_ID> -n playwright-report -D /tmp/e2e-trace/<RUN_ID>
-D로 an isolated folder. This is to avoid polluting the repo working tree with trace files. In the downloaded tree, if you find *.zip or trace.zip, that is the input for step 3.
3. Root cause analysis — open the trace and see the moment of failure
A trace is not a simple log but a DOM snapshot immediately before/after the failure + screenshots + network + console + timing. So you can answer "why is it red" by observation, not guesswork. This is the heart of this workflow.
# 받은 trace.zip 을 Playwright trace viewer 로 연다
npx playwright show-trace /tmp/e2e-trace/<RUN_ID>/**/trace.zip
The trace tool's features and how to read them are covered by playwright-cli의 the tracing reference(action log, network waterfall, step-by-step DOM). In this skill, analysis is triage that narrows things down just enough to hand off to the next step — form a hypothesis and pull only the information from the trace that confirms it:
- In the failed action, does the selector in the DOM snapshot actually exist → if not, UI change / broken selector.
- If the failure is timeout, look at the network tab for pending/failed requestsor slow responses → insufficient wait conditions or backend regression.
- If the screenshot shows a login/error page→ auth, seed data, or environment issue (not test logic).
- If it passes locally but only breaks in CI → timing/environment differences. Reproduce the same selector locally
playwright-clito reproduceto narrow the gap.
The triage checklist and branching by failure type are organized in references/trace-triage.md. The full diagnostic loop that digs to the root cause to the end and fixes until it passes is the responsibility of e2e-test-healer's responsibility, so once triage is done, hand off there with the trace path and the failing spec name (step 4).
The output of this step is the local trace.zip path + a one-line hypothesis. Example: "#submit the button changed to data-testid='submit'so the selector fails to match (stale test)" / "the payment API returns 500 so the success toast doesn't appear and the assertion times out (suspected product regression)".
4. Fix & re-verify — fix it, include it in the same PR, and see CI again
The act of fixing itself is delegated to e2e-test-healerdelegated to. Healer takes the local trace.zip (step 3 output) as input, runs run → debug → root-cause → fix → verify, judges "the test is stale / the product code regressed," fixes the correct side, and then green locallychecks green locally. If a new selector is needed, Healer uses playwright-cli's role-based stable selectors (test-generation). We do not repeat the same thing here.
What this skill additionally owns is things the Healer does not handle at the CI-level loop closinglevel — because local green ≠ CI green:
# 고친 변경을 같은 브랜치/PR에 push → CI가 자동 재실행
git add -A && git commit -m "fix(e2e): <한 줄 원인 요약>" && git push
gh pr checks <PR-번호> --watch # PR 체크가 다시 초록이 될 때까지 관찰
the goal is to close the loop: do not just push and stop. You must verify that the PR's CI re-run actually passes for the self-improvement cycle of "agent works → verified by tests" to be closed. If it fails again, use the new run's trace to repeat from step 2(to avoid infinite pushes for the same cause, re-check the cause with the trace each cycle).
Real-world tips for large Next.js enterprise repos
- E2E job names and artifact names differ from repo to repo. Don't guess, list(the list command in steps 1 and 2). Once you have checked once,
.omc/write it in a memo or PR comment to reduce the cost next time. - In a monorepo, multiple workflows run. Pin to the failed 그 run-id and work there (so you don't receive artifacts from another green run).
- Always download traces
/tmpetc. outside the working tree. In a large repo, if trace/resources dirty git status, reviews get ruined. - Do not copy secrets from trace screenshots/network bodies into code/comments. If it looks like an auth failure, do not guess and insert credentials; report it as an environment issue.
Reference files (open only when needed)
- references/ci-diagnosis.md — command recipes for finding runs, jobs, and artifacts with gh, handling re-runs/attempts. When steps 1 and 2 are stuck.
- references/trace-triage.md — branching by failure type (selector/timeout/environment/flaky) and a trace triage checklist. During step 3 triage.
e2e-test-healerskill — a healing loop that digs to the root cause from the local trace and fixes it all the way to passing. In step 4, delegate the actual fix to this.playwright-cliskill — the single source of truth for browser/trace CLI syntax. This skill builds on top of it and operates without duplicating commands.
Position in the E2E harness pipeline
e2e-flow-planner(what) → e2e-test-generator(with code) → e2e-test-hardener(robustly) → CI runs on the PR → this skill (brings CI failures into trace and closes the PR loop) → e2e-test-healer(actual healing locally). This skill is the bridge connecting the entry point of "CI failure" and the exit point of "PR green".