fix-pw-spec

name	fix-pw-spec
description	Fix a failing Playwright spec by analyzing error output, identifying the root cause in the test code, and applying corrections. Use when a Playwright test fails due to wrong selectors, bad waits, incorrect assertions, or code errors. Trigger phrases: "fix this playwright test", "this spec is failing", "playwright test broken", "fix the flaky test".

Fix Failing Playwright Spec

When to Use

This skill fixes test code bugs — not product bugs. Use it when:

• A spec you wrote (or someone else wrote) fails due to selectors, waits, or assertion logic
• The product behavior is correct but the test doesn't match it
• Playwright reports timeouts, strict mode violations, or wrong expected values

If the product itself is broken, use diagnose-pw-failure instead.

Step 1 — Gather Failure Context

Read these three things:

1. The Playwright error output from the terminal (the test run output)
2. The spec file that failed
3. The trace or screenshot if available:
   • Traces: app/client/playwright/results/<test-path>/trace.zip
   • Screenshots: app/client/playwright/results/<test-path>/*.png

Step 2 — Classify the Error

Error pattern	Root cause	Fix
Timeout waiting for locator("...")	Selector doesn't match any element	Inspect the actual page; update selector
strict mode violation: locator resolved to N elements	Locator too broad	Add .first(), .nth(), or refine with chained locators
expect(received).toHaveText("X") received "Y"	Wrong expected value OR wrong element	Verify which element you're targeting; update expected value if test data changed
Target closed / page.goto: Navigation failed	Page navigated away before action completed	Add waitForResponse or waitForURL before the action
locator.click: Element is not visible	Element exists but hidden (behind modal, off-screen)	Wait for the right state, scroll into view, or close blocking elements
Cannot find module / TypeScript error	Import path wrong or missing export	Fix the import path; check that POM/helper exports the symbol
ECONNREFUSED / net::ERR_*	Not a spec bug — deployment issue	Stop. This is not fixable in the spec.

Step 3 — Fix Using Conventions

When fixing, follow the project conventions (from .cursor/rules/playwright.mdc):

Selector fixes

Prefer this priority order when replacing a broken selector:

1. page.getByRole("button", { name: /submit/i }) — best
2. page.getByPlaceholder("Search...") — for inputs without proper label association
3. page.getByTestId("my-element") — explicit contract
4. page.locator(SELECTORS.widgetInDeployed("text")) — Appsmith widget selectors from constants
5. CSS selector with comment — last resort only

Do not: Guess selectors. If unsure what's on the page, add a temporary await page.pause() or read the component source to find the actual DOM structure.

Wait fixes

Replace any hard waits or networkidle with specific conditions:

// Instead of waitForTimeout or networkidle, wait for the element:
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();

// For mutations, wait for the API response:
const response = page.waitForResponse(r => r.url().includes(API.actionsExecute));
await page.getByRole("button", { name: "Save" }).click();
await response;

Assertion fixes

Ensure all assertions use the auto-retrying form:

// WRONG — non-retrying
expect(await locator.textContent()).toBe("value");

// RIGHT — auto-retrying
await expect(locator).toHaveText("value");

Step 4 — Re-run and Verify

After fixing, re-run the specific test:

cd app/client && npx playwright test <spec-file> --project=<project>

If it still fails, go back to Step 2 with the new error output.

Budget: Max 3 fix attempts per failure. After 3, either:

• The spec is fundamentally wrong (rewrite from scratch)
• The product has a bug (switch to diagnose-pw-failure)

Step 5 — Validate Fix Quality

Before declaring the fix done, check:

• No networkidle introduced
• No waitForTimeout introduced
• No hardcoded API URLs or CSS selectors
• Assertions use auto-retrying expect
• No unused imports left behind
• Run npx eslint <file> --ext .ts clean

Output

Summarize what was wrong and what was fixed:

## Spec Fix Summary

**File**: playwright/tests/sanity/widgets/table-filter.spec.ts
**Attempts**: 2

### Fix 1
- **Error**: Timeout waiting for locator `getByRole("button", { name: "Filter" })`
- **Cause**: Button text is "Add Filter", not "Filter"
- **Fix**: Updated to `getByRole("button", { name: /add filter/i })`

### Fix 2
- **Error**: strict mode violation on `.first()` table row
- **Cause**: Filter hadn't applied yet when assertion ran
- **Fix**: Added `waitForResponse` on the execute API before asserting row content

**Result**: PASS