菜单
Fix broken regression tests after codebase changes. Analyzes failures, determines root cause (broken test vs broken code), and applies targeted fixes. Supports both E2E mock-auth and Keycloak dev stacks. Usage - /fix-tests [spec-file-or-domain] [--kc]
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/rakheen-dama/b2b-strawman --skill fix-tests命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Implement a specific epic end-to-end — worktree, code, test, PR, review, merge. Supports auto-merge for automated phase execution. Pass the epic number as an argument (e.g. /epic_v2 7).
Generate detailed acceptance test specs for a Kazi feature area. Takes a feature ID from qa/acceptance/INDEX.md, reads phase requirements + architecture, and produces a structured acceptance criteria document with test cases ready for Playwright automation. Usage - /acceptance-spec <feature-id> [--update]
Implement a specific epic end-to-end — worktree, code, test, PR, review, merge. Pass the epic number as an argument (e.g. /epic 7).
基于 SOC 职业分类
正在显示 SKILL.md
| name | fix-tests |
| description | Fix broken regression tests after codebase changes. Analyzes failures, determines root cause (broken test vs broken code), and applies targeted fixes. Supports both E2E mock-auth and Keycloak dev stacks. Usage - /fix-tests [spec-file-or-domain] [--kc] |
Analyze and fix failing regression tests after codebase changes. Determines whether failures are broken tests (wrong selectors/stale assumptions) or broken features (actual regressions), then applies the appropriate fix.
<spec-file>: Fix a specific spec file (e.g., /fix-tests invoices/invoice-lifecycle.spec.ts)<domain>: Fix all specs in a domain (e.g., /fix-tests customers, /fix-tests keycloak)--kc: Run against the Keycloak dev stack (ports 3000/8080/8443/8180)| Aspect | E2E Mock-Auth (default) | Keycloak Dev (--kc) |
|---|---|---|
| Frontend | http://localhost:3001 | http://localhost:3000 |
| Backend | http://localhost:8081 | http://localhost:8080 |
| Auth | Mock IDP :8090 | Keycloak :8180 via Gateway :8443 |
| Auth fixture | e2e/fixtures/auth.ts | e2e/fixtures/keycloak-auth.ts |
| Playwright env |
PLAYWRIGHT_BASE_URL=http://localhost:3001 |
E2E_AUTH_MODE=keycloak PLAYWRIGHT_BASE_URL=http://localhost:3000 |
| Test scope | e2e/tests/* (excludes keycloak/) | e2e/tests/keycloak/* + standard tests |
| Selectors | e2e/fixtures/keycloak-selectors.ts (KC login/register forms) |
| Email helper | N/A | e2e/helpers/mailpit.ts (OTP, invite links) |
Run the relevant tests to get the current failure list:
cd frontend
# If no args: run all tests
NODE_OPTIONS="" PLAYWRIGHT_BASE_URL=http://localhost:3001 \
/opt/homebrew/bin/pnpm exec playwright test \
--reporter=json --config=e2e/playwright.config.ts 2>/dev/null \
| jq -r '.suites[].suites[]?.specs[]? | select(.tests[0].results[0].status == "failed" or .tests[0].results[0].status == "timedOut") | .file + " :: " + .title + " :: " + (.tests[0].results[0].errors[0].message // "no message" | split("\n")[0])' 2>/dev/null
# If specific file/domain: run just those
NODE_OPTIONS="" PLAYWRIGHT_BASE_URL=http://localhost:3001 \
/opt/homebrew/bin/pnpm exec playwright test e2e/tests/{ARG} \
--reporter=json --config=e2e/playwright.config.ts 2>/dev/null \
| jq -r '...'
--kc)cd frontend
# KC-specific tests
NODE_OPTIONS="" E2E_AUTH_MODE=keycloak PLAYWRIGHT_BASE_URL=http://localhost:3000 \
/opt/homebrew/bin/pnpm exec playwright test e2e/tests/keycloak/ \
--reporter=json --config=e2e/playwright.config.ts 2>/dev/null \
| jq -r '.suites[].suites[]?.specs[]? | select(.tests[0].results[0].status == "failed" or .tests[0].results[0].status == "timedOut") | .file + " :: " + .title + " :: " + (.tests[0].results[0].errors[0].message // "no message" | split("\n")[0])' 2>/dev/null
# If specific file: run just that
NODE_OPTIONS="" E2E_AUTH_MODE=keycloak PLAYWRIGHT_BASE_URL=http://localhost:3000 \
/opt/homebrew/bin/pnpm exec playwright test {ARG} \
--reporter=json --config=e2e/playwright.config.ts 2>/dev/null \
| jq -r '...'
Also check API tests if relevant (E2E mode only):
bash scripts/regression-test.sh 2>&1 | grep FAIL
For each failing test, classify it by reading the test file and the component it tests:
Symptoms:
toBeVisible failed — element exists but selector doesn't matchtoContainText failed — text changed (e.g., "Customers" → "Clients" from terminology)toHaveURL failed — route changedgetByRole finds 0 or multiple elements — component structure changedFix approach: Update the test to match the current codebase.
Symptoms:
Fix approach: Fix the code, not the test.
Known baselines (E2E mock-auth):
lifecycle.spec.ts — depends on lifecycle-test.sh seed data, drifts after QA cycleslifecycle-interactive.spec.ts — same (hardcoded UUIDs, seed-dependent names)lifecycle-portal.spec.ts — same (portal data from lifecycle seed)Known baselines (Keycloak):
Fix approach: Skip or ignore. These are not regressions.
Symptoms:
test.skip() but someone unskipped itFix approach: Re-add test.skip(true, 'Feature not implemented').
Symptoms:
keycloak/) fails at loginAs(page, 'alice') in KC modeFix approach: Not a regression. Standard tests use mock auth fixture. Only keycloak/* tests are designed for KC auth.
For each broken test, dispatch a subagent:
You are fixing a broken test after codebase changes.
## Failing Test
- File: {spec_file}
- Test: {test_name}
- Error: {error_message}
- Stack: {e2e-mock | keycloak}
## Instructions
1. Read the test file to understand what it's asserting
2. Read the ACTUAL component/page it tests to find the correct selectors:
- For page tests: read `frontend/app/(app)/org/[slug]/{path}/page.tsx`
- For component tests: check `frontend/components/{domain}/`
- For KC auth tests: check `frontend/e2e/fixtures/keycloak-auth.ts` and `keycloak-selectors.ts`
3. Determine what changed:
- Button text changed? → update `getByRole('button', { name: /.../ })`
- Heading changed? → update heading selector
- Dialog structure changed? → update dialog locators
- API response shape changed? → update assertions
- Keycloak form changed? → update `keycloak-selectors.ts` (ONE file for all KC selectors)
- Mailpit API changed? → update `e2e/helpers/mailpit.ts`
4. Fix the test with the MINIMUM change needed
5. Verify by running the single test:
### E2E Mock-Auth
```bash
NODE_OPTIONS="" PLAYWRIGHT_BASE_URL=http://localhost:3001 \
/opt/homebrew/bin/pnpm exec playwright test {spec_file} \
--reporter=list --config=e2e/playwright.config.ts
NODE_OPTIONS="" E2E_AUTH_MODE=keycloak PLAYWRIGHT_BASE_URL=http://localhost:3000 \
/opt/homebrew/bin/pnpm exec playwright test {spec_file} \
--reporter=list --config=e2e/playwright.config.ts
getByRole with regex names: getByRole('button', { name: /Save/i })page.locator('h1').first() instead of getByRole('heading', { name: 'Exact Match' })const dialog = page.getByRole('dialog'); dialog.getByLabel('Name')page.locator('[data-slot="select-trigger"]')page.locator('[cmdk-item]')/New (Customer|Client)/ie2e/fixtures/keycloak-selectors.ts
## Step 3 — Fix Category B Failures (Broken Code)
For each broken feature, dispatch a subagent with `isolation: "worktree"`:
You are fixing a regression bug found by a failing test.
If the bug is in the auth flow:
lib/auth/providers/keycloak-bff.ts for BFF token handlingproxy.ts for middleware auth routingbash compose/scripts/svc.sh restart backend (or gateway)
## Step 4 — Update API Regression Script
If API test failures exist in `scripts/regression-test.sh` (E2E mode only):
1. Read the failing section
2. Check the actual API endpoint via curl
3. Fix the endpoint path, payload, or assertion
4. Re-run: `bash scripts/regression-test.sh --only {section} 2>&1`
Common API test fixes:
- Endpoint path changed → update the `api_get`/`api_post` call
- Request body changed → update the JSON payload
- Response field renamed → update the `jq` filter
- Status code changed → update `assert_http` expected code
## Step 5 — Verify and Commit
After all fixes:
1. Run the full suite for the relevant stack:
### E2E Mock-Auth
```bash
bash scripts/run-regression-test.sh 2>&1
cd frontend
NODE_OPTIONS="" E2E_AUTH_MODE=keycloak PLAYWRIGHT_BASE_URL=http://localhost:3000 \
/opt/homebrew/bin/pnpm exec playwright test e2e/tests/keycloak/ \
--reporter=list --config=e2e/playwright.config.ts 2>&1
Confirm:
Commit all test fixes in one commit:
git add scripts/regression-test.sh frontend/e2e/tests/ frontend/e2e/fixtures/ frontend/e2e/helpers/
git commit -m "test: update regression tests for codebase changes
Updated selectors/assertions to match current UI after [describe changes].
N tests fixed, M tests remain skipped (features not yet built)."
Present:
This is not advice — these rules are mandatory. Loopholes are forbidden. If a rule blocks you, raise it; don't bypass.
Test discipline:
/Save/i not 'Save Changes'getByRole('button') not .btn-primarydialog.getByLabel() not page.getByLabel()e2e/fixtures/keycloak-selectors.ts — all KC tests reference thisCode-fix discipline (Category B fixes — the broken-feature path):
./mvnw verify and write .claude/markers/verify-backend.json (per .claude/markers/README.md). If it touches frontend, run pnpm lint && pnpm build && pnpm test and write verify-frontend.json. Same for portal. Write the marker into the main repo's .claude/markers/ (where gh pr merge will read it), not a worktree's. The pre-PR-merge-gate hook will block merge without these markers.superpowers:code-reviewer subagent, or human eyeball. Self-review is not enough.--admin or by editing the hook out of settings.json. If it blocks, fix the verify and write the marker.Stack hygiene:
bash compose/scripts/svc.sh restart backend (or gateway) — no hot-reload for JVM servicesbash compose/scripts/e2e-rebuild.sh frontendpage.context().clearCookies()This skill should be invoked AFTER any of these events:
keycloak-selectors.ts)When invoked proactively, focus on the specific domain affected by the change rather than running the full suite.