Add Playwright debug skill for E2E test debugging (#2671)

.claude/skills/debug-with-playwright/SKILL.md

+---
+name: dyad:debug-with-playwright
+description: Debug E2E tests by taking screenshots at key points to visually inspect application state.
+---
+
+# Debug with Playwright Screenshots
+
+Debug E2E tests by taking screenshots at key points to visually inspect application state.
+
+## Arguments
+
+- `$ARGUMENTS`: (Optional) Specific E2E test file to debug (e.g., `main.spec.ts` or `e2e-tests/main.spec.ts`). If not provided, will ask the user which test to debug.
+
+## Background
+
+Dyad uses Electron + Playwright for E2E tests. Because Playwright's built-in `screenshot: "on"` option does NOT work with Electron (see https://github.com/microsoft/playwright/issues/8208), you must take screenshots manually via `page.screenshot()`.
+
+The test fixtures in `e2e-tests/helpers/fixtures.ts` already auto-capture a screenshot on test failure and attach it to the test report. But for debugging, you often need screenshots at specific points during test execution.
+
+## Instructions
+
+1. **Identify the test to debug:**
+
+   If `$ARGUMENTS` is empty, ask the user which test file they want to debug.
+   - If provided without the `e2e-tests/` prefix, add it
+   - If provided without the `.spec.ts` suffix, add it
+
+2. **Read the test file:**
+
+   Read the test file to understand what it does and where it might be failing.
+
+3. **Add debug screenshots to the test:**
+
+   Add `page.screenshot()` calls at key points in the test to capture visual state. Access the page from the `po` fixture:
+
+   ```typescript
+   // Get the page from the electronApp fixture
+   const page = await electronApp.firstWindow();
+
+   // Or if you only have `po`, access the page directly:
+   // po is a PageObject which has a `page` property
+   ```
+
+   **Screenshot patterns for debugging:**
+
+   ```typescript
+   import * as fs from "fs";
+   import * as path from "path";
+
+   // Create a debug screenshots directory
+   const debugDir = path.join(__dirname, "debug-screenshots");
+   if (!fs.existsSync(debugDir)) {
+     fs.mkdirSync(debugDir, { recursive: true });
+   }
+
+   // Take a full-page screenshot
+   await page.screenshot({
+     path: path.join(debugDir, "01-before-action.png"),
+   });
+
+   // Take a screenshot of a specific element
+   const element = page.locator('[data-testid="chat-input"]');
+   await element.screenshot({
+     path: path.join(debugDir, "02-chat-input.png"),
+   });
+
+   // Take a screenshot after some action
+   await po.sendPrompt("hi");
+   await page.screenshot({
+     path: path.join(debugDir, "03-after-send.png"),
+   });
+   ```
+
+   **Important:** The test fixture signature provides `{ electronApp, po }`. To get the page:
+   - Use `await electronApp.firstWindow()` to get the page
+   - Or use `po.page` if PageObject exposes it
+
+   Add screenshots before and after the failing step to understand what the UI looks like at that point.
+
+4. **Build the app (if needed):**
+
+   E2E tests run against the built binary. If you made any application code changes:
+
+   ```
+   npm run build
+   ```
+
+   If you only changed test files, you can skip this step.
+
+5. **Run the test:**
+
+   ```
+   PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_HTML_OPEN=never npm run e2e -- e2e-tests/<testfile>.spec.ts
+   ```
+
+6. **View the screenshots:**
+
+   Use the Read tool to view the captured PNG screenshots. Claude Code can read and display images directly:
+
+   ```
+   Read the PNG files in e2e-tests/debug-screenshots/
+   ```
+
+   Analyze the screenshots to understand:
+   - Is the expected UI element visible?
+   - Is there an error dialog or unexpected state?
+   - Is a loading spinner still showing?
+   - Is the layout correct?
+
+7. **Check the Playwright trace (for additional context):**
+
+   The Playwright config has `trace: "retain-on-failure"`. If the test failed, a trace file will be in `test-results/`. You can reference this for additional debugging context.
+
+8. **Iterate:**
+
+   Based on what you see in the screenshots:
+   - Add more targeted screenshots if needed
+   - Fix the issue in the test or application code
+   - Re-run to verify
+
+9. **Clean up:**
+
+   After debugging is complete, remove the debug screenshots and any temporary screenshot code you added to the test:
+
+   ```
+   rm -rf e2e-tests/debug-screenshots/
+   ```
+
+   Remove any `page.screenshot()` calls you added for debugging purposes.
+
+10. **Report findings:**
+
+    Tell the user:
+    - What the screenshots revealed about the test failure
+    - What fix was applied (if any)
+    - Whether the test now passes

AGENTS.md

@@ -104,6 +104,8 @@ Use unit testing for pure business logic and util functions.
 
 See [rules/e2e-testing.md](rules/e2e-testing.md) for full E2E testing guidance, including Playwright tips and fixture setup.
 
+**Debugging E2E test failures with screenshots:** When an E2E test fails and you can't determine the cause from the error message alone, use the `/dyad:debug-with-playwright` skill to add screenshots at key points in the test. Playwright's built-in `screenshot: "on"` does NOT work with Electron — you must use manual `page.screenshot()` calls. The skill walks you through adding debug screenshots, running the test, viewing the captured PNGs, and cleaning up afterward.
+
 ## Git workflow
 
 When pushing changes and creating PRs: