fix: deflake E2E tests (setup_flow, chat_history, Navigation) (#2681)

e2e-tests/chat_history.spec.ts

@@ -41,8 +41,10 @@ test("should open, navigate, and select from history menu", async ({ po }) => {
   await expect(firstItem).toContainText("First test message");
 
   // Navigate up again to wrap to last item (newest message)
+  // Wait briefly to ensure the previous navigation state has settled
+  await po.page.waitForTimeout(100);
   await po.page.keyboard.press("ArrowUp");
-  await expect(lastItem).toHaveClass(/bg-accent/);
+  await expect(lastItem).toHaveClass(/bg-accent/, { timeout: Timeout.MEDIUM });
 
   // Select with Enter (selects newest message)
   await po.page.keyboard.press("Enter");

e2e-tests/helpers/page-objects/components/Navigation.ts

@@ -17,7 +17,9 @@ export class Navigation {
   }
 
   async goToAppsTab() {
-    await this.page.getByRole("link", { name: "Apps" }).click();
+    const appsLink = this.page.getByRole("link", { name: "Apps" });
+    await expect(appsLink).toBeVisible({ timeout: 60000 });
+    await appsLink.click();
     await expect(this.page.getByText("Build a new app")).toBeVisible();
   }
 

e2e-tests/setup_flow.spec.ts

@@ -40,6 +40,7 @@ testSetup.describe("Setup Flow", () => {
     // Start with Node.js not installed
     await po.setNodeMock(false);
     await po.page.reload();
+    await po.page.waitForLoadState("domcontentloaded");
 
     // Verify setup banner and install button are visible
     await expect(
@@ -47,7 +48,7 @@ testSetup.describe("Setup Flow", () => {
     ).toBeVisible();
     await expect(
       po.page.getByRole("button", { name: "Install Node.js Runtime" }),
-    ).toBeVisible();
+    ).toBeVisible({ timeout: 10000 });
 
     // Manual configuration link should be visible
     await expect(

rules/e2e-testing.md

@@ -97,6 +97,13 @@ Each parallel Playwright worker gets its own fake LLM server on port `FAKE_LLM_B
 
 When adding new test server URLs, update **both** the test fixtures (`e2e-tests/helpers/fixtures.ts`) and the Electron app source that consumes them. The app reads `process.env.FAKE_LLM_PORT` to build its `TEST_SERVER_BASE` URL — if you hardcode a port in app source, parallel workers will all hit the same server.
 
+## Common flaky test patterns and fixes
+
+- **After `page.reload()`**: Always add `await page.waitForLoadState("domcontentloaded")` before interacting with elements. Without this, the page may not have re-rendered yet.
+- **Keyboard navigation events (ArrowUp/ArrowDown)**: Add `await page.waitForTimeout(100)` between sequential keyboard presses to let the UI state settle. Rapid keypresses can cause race conditions in menu navigation.
+- **Navigation to tabs**: Use `await expect(link).toBeVisible({ timeout: Timeout.EXTRA_LONG })` before clicking tab links (especially in `goToAppsTab()`). Electron sidebar links can take time to render during app initialization.
+- **Confirming flakiness**: Use `PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_HTML_OPEN=never npm run e2e -- e2e-tests/<spec> --repeat-each=10` to reproduce flaky tests. `PLAYWRIGHT_RETRIES=0` is critical — CI defaults to 2 retries, hiding flakiness.
+
 ## E2E test fixtures with .dyad directories
 
 When adding E2E test fixtures that need a `.dyad` directory for testing: