Fix flaky E2E tests - improve waitHelpers and readiness logic

Author: webstackdev

test/e2e/helpers/pageObjectModels/BasePage.ts

@@ -13,6 +13,7 @@ import {
 } from '@playwright/test'
 import { navigationItems } from '@components/Navigation/server'
 import { clearConsentCookies } from '@test/e2e/helpers'
+import { waitForHeaderComponents as waitForHeaderComponentsHelper } from '@test/e2e/helpers/waitHelpers'
 
 const DEFAULT_NAVIGATION_TIMEOUT = 5000
 const EXTENDED_NAVIGATION_TIMEOUT = 15000
@@ -451,6 +452,14 @@ export class BasePage {
     this.lastAstroPageLoadCount = await this._page.evaluate(() => window.__astroPageLoadCounter ?? 0)
   }
 
+  /**
+   * Wait for navigation header components (theme picker + nav) to hydrate
+   * Ensures client-side navigation helpers can safely interact with header UI
+   */
+  async waitForHeaderComponents(options?: { timeout?: number }): Promise<void> {
+    await waitForHeaderComponentsHelper(this._page, options?.timeout)
+  }
+
   /**
    * Navigate to a page using Astro View Transitions
    * Clicks a link with the given href to trigger client-side navigation
@@ -464,6 +473,7 @@ export class BasePage {
    * ```
    */
   async navigateToPage(href: string): Promise<void> {
+    await this.waitForHeaderComponents()
     const navLink = this._page.locator(`site-navigation a[href="${href}"]`).first()
     const linkCount = await navLink.count()
 

test/e2e/helpers/waitHelpers.ts

@@ -4,14 +4,58 @@
  */
 import type { Page } from '@playwright/test'
 
+const THEME_PICKER_READY_ATTR = 'data-theme-picker-ready'
+const NAVIGATION_READY_ATTR = 'data-nav-ready'
+const DEFAULT_COMPONENT_READY_TIMEOUT = 5000
+
+const isContextDestroyedError = (error: unknown) => {
+  if (!(error instanceof Error)) return false
+  const message = error.message ?? ''
+  return message.includes('Execution context was destroyed') || message.includes('Target closed')
+}
+
 /**
  * Wait for the browser to render a specific number of animation frames
  * Uses requestAnimationFrame so it synchronizes with real layout/paint updates
  */
 export async function waitForAnimationFrames(page: Page, frameCount: number = 2): Promise<void> {
-  await page.evaluate(async (count) => {
-    for (let index = 0; index < count; index++) {
-      await new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+  let remaining = frameCount
+
+  while (remaining > 0) {
+    try {
+      await page.evaluate(async () => {
+        await new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+      })
+      remaining -= 1
+    } catch (error) {
+      if (isContextDestroyedError(error)) {
+        await page.waitForLoadState('domcontentloaded')
+        continue
+      }
+      throw error
     }
-  }, frameCount)
+  }
+}
+
+export async function waitForThemePickerReady(page: Page, timeout = DEFAULT_COMPONENT_READY_TIMEOUT): Promise<void> {
+  await page.waitForFunction(
+    attr => document.querySelector('theme-picker')?.getAttribute(attr) === 'true',
+    THEME_PICKER_READY_ATTR,
+    { timeout }
+  )
+}
+
+export async function waitForNavigationReady(page: Page, timeout = DEFAULT_COMPONENT_READY_TIMEOUT): Promise<void> {
+  await page.waitForFunction(
+    attr => document.querySelector('site-navigation')?.getAttribute(attr) === 'true',
+    NAVIGATION_READY_ATTR,
+    { timeout }
+  )
+}
+
+export async function waitForHeaderComponents(page: Page, timeout = DEFAULT_COMPONENT_READY_TIMEOUT): Promise<void> {
+  await Promise.all([
+    waitForThemePickerReady(page, timeout),
+    waitForNavigationReady(page, timeout),
+  ])
 }

test/e2e/specs/04-components/theme-picker.spec.ts

@@ -13,29 +13,6 @@ import {
   test,
 } from '@test/e2e/helpers'
 
-type PlaywrightPage = import('@playwright/test').Page
-
-const THEME_PICKER_READY_ATTR = 'data-theme-picker-ready'
-const NAVIGATION_READY_ATTR = 'data-nav-ready'
-
-const waitForThemePickerReady = async (page: PlaywrightPage) => {
-  await page.waitForFunction((attr) => {
-    const host = document.querySelector('theme-picker')
-    return host?.getAttribute(attr) === 'true'
-  }, THEME_PICKER_READY_ATTR)
-}
-
-const waitForNavigationReady = async (page: PlaywrightPage) => {
-  await page.waitForFunction((attr) => {
-    const nav = document.querySelector('site-navigation')
-    return nav?.getAttribute(attr) === 'true'
-  }, NAVIGATION_READY_ATTR)
-}
-
-const waitForHeaderComponents = async (page: PlaywrightPage) => {
-  await Promise.all([waitForThemePickerReady(page), waitForNavigationReady(page)])
-}
-
 const getDefaultNavigationHref = (basePage: BasePage) => basePage.navigationItems[0]?.url ?? '/about'
 
 /**
@@ -61,7 +38,7 @@ async function navigateWithMobileSupport(basePage: BasePage, href: string = getD
   await basePage.waitForPageLoad()
   // Header components rehydrate asynchronously after View Transitions; make sure
   // the theme picker + navigation are ready before interacting again.
-  await waitForHeaderComponents(page)
+  await basePage.waitForHeaderComponents()
 
   // On mobile, the menu should automatically close after navigation
   // But let's ensure it's closed by checking and closing if needed
@@ -85,7 +62,6 @@ test.describe('Theme Picker Component', () => {
      * - Performs hard reload to bypass View Transitions cache
      * - Dismisses cookie consent modal so it doesn't interfere with theme picker interactions
      * - Ensures consistent starting state for theme testing (no persisted theme preferences)
-     *
      * Without this setup, tests would fail due to:
      * - Leftover theme preferences from previous tests affecting assertions
      * - Cookie modal blocking theme picker UI interactions
@@ -94,7 +70,7 @@ test.describe('Theme Picker Component', () => {
     test.beforeEach(async ({ page: playwrightPage }) => {
       const page = await BasePage.init(playwrightPage)
       await setupCleanTestPage(page.page)
-      await waitForHeaderComponents(page.page)
+      await page.waitForHeaderComponents()
     })
 
     test('@ready theme picker is visible', async ({ page: playwrightPage }) => {
@@ -194,14 +170,14 @@ test.describe('Theme Picker Component', () => {
      * - Dismisses cookie modal to prevent UI interference
      * - Ensures clean state needed to properly test theme persistence behavior
      *
-     * Without this setup, persistence tests would be unreliable due to:
+      await page.waitForHeaderComponents()
      * - Pre-existing theme preferences making it impossible to verify persistence from scratch
      * - Cached state from previous tests affecting reload behavior
      */
     test.beforeEach(async ({ page: playwrightPage }) => {
       const page = await BasePage.init(playwrightPage)
       await setupCleanTestPage(page.page)
-      await waitForHeaderComponents(page.page)
+      await page.waitForHeaderComponents()
     })
 
     test('@ready theme preference persists across page reloads', async ({ page: playwrightPage }) => {
@@ -228,7 +204,7 @@ test.describe('Theme Picker Component', () => {
 
       // This test needs its own setup without localStorage clearing
       await setupTestPage(page.page)
-      await waitForHeaderComponents(page.page)
+      await page.waitForHeaderComponents()
 
       // Select dark theme using helper
       await selectTheme(page.page, 'dark')
@@ -325,7 +301,7 @@ test.describe('Theme Picker Component', () => {
       await setupTestPage(page.page, '/')
       await page.evaluate(() => localStorage.clear())
       await page.reload()
-      await waitForHeaderComponents(page.page)
+      await page.waitForHeaderComponents()
     })
 
     test('theme picker button works after View Transition navigation', async ({ page: playwrightPage }) => {
@@ -334,7 +310,7 @@ test.describe('Theme Picker Component', () => {
       // Root Cause: Scripts didn't properly reinitialize on View Transitions
       // Fix: Migrated to Web Component pattern with connectedCallback/disconnectedCallback lifecycle
 
-      // 1. Verify theme picker works on initial page load
+      await page.waitForHeaderComponents()
       const themeToggleBtn = page.locator('.theme-toggle-btn').first()
       await expect(themeToggleBtn).toBeVisible()
 
@@ -432,7 +408,7 @@ test.describe('Theme Picker Component', () => {
       await setupTestPage(page.page, '/')
       await page.evaluate(() => localStorage.clear())
       await page.reload()
-      await waitForHeaderComponents(page.page)
+      await page.waitForHeaderComponents()
     })
 
     test('preserves lang attribute across navigation', async ({ page: playwrightPage }) => {

test/e2e/specs/11-regression/hero-animation-mobile-menu-pause.spec.ts

@@ -36,6 +36,7 @@ test.describe('Hero Animation - Mobile Menu Pause Regression', () => {
   test.beforeEach(async ({ page: playwrightPage }) => {
     const page = await BasePage.init(playwrightPage)
     await setupTestPage(page.page, '/')
+    await page.waitForHeaderComponents()
     // Wait for hero animation to load
     await page.waitForSelector('#heroAnimation', { timeout: 5000 })
   })
@@ -238,6 +239,7 @@ test.describe('Hero Animation - Mobile Menu Pause Regression', () => {
 
     // Wait for navigation
     await page.waitForLoadState('networkidle')
+    await page.waitForHeaderComponents()
 
     // Menu should close after navigation
     const hamburgerAfterNav = page.locator('.nav-toggle-btn').first()

test/e2e/specs/12-component-persistence/body-visibility.spec.ts

@@ -18,11 +18,13 @@ test.describe('View Transitions - body visibility reset', () => {
 
     await page.goto('/')
     await page.waitForLoadState('networkidle')
+    await page.waitForHeaderComponents()
 
     const astroBeforeSwapLog = page.consoleMssgPromise('Theme init on "astro:before-swap" executed')
 
     await page.navigateToPage('/about')
     await page.waitForPageLoad()
+    await page.waitForHeaderComponents()
 
     const logMessage = await astroBeforeSwapLog
     expect(logMessage.text()).toContain('Theme init on "astro:before-swap" executed')

test/e2e/specs/12-component-persistence/head.spec.ts

@@ -13,13 +13,26 @@
 
 import { ComponentPersistencePage, test, describe, expect } from '@test/e2e/helpers'
 
+const navigateAndAwaitHydration = async (
+  page: ComponentPersistencePage,
+  href: string,
+  urlPattern: string | RegExp,
+  timeout = 5000
+) => {
+  await page.navigateToPage(href)
+  await page.waitForPageLoad()
+  await page.waitForHeaderComponents()
+  await page.waitForURL(urlPattern, { timeout })
+}
+
 describe('View Transitions - transition:persist on meta theme-color', () => {
   test('should persist meta theme-color element across navigation', async ({
     page: playwrightPage,
   }) => {
     const page = await ComponentPersistencePage.init(playwrightPage)
 
     await page.goto('/')
+    await page.waitForHeaderComponents()
 
     // Set up test data on the meta theme-color element
     const initialData = await page.setupPersistenceTest('meta[name="theme-color"]')
@@ -33,8 +46,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
     expect(initialContent).toMatch(/^#[0-9a-fA-F]{6}$/)
 
     // Navigate to a different page using Astro's View Transitions
-    await page.navigateToPage('/articles')
-    await page.waitForURL('**/articles', { timeout: 5000 })
+    await navigateAndAwaitHydration(page, '/articles', '**/articles')
 
     // Verify the element persisted with the same DOM identity
     const afterNavigationData = await page.verifyPersistence('meta[name="theme-color"]')
@@ -56,6 +68,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
   }) => {
     const page = await ComponentPersistencePage.init(playwrightPage)
     await page.goto('/')
+    await page.waitForHeaderComponents()
 
     // Mark the <head> element to verify it persists (Astro behavior)
     const headData = await page.evaluate(() => {
@@ -89,8 +102,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
     expect(metaData.content).toMatch(/^#[0-9a-fA-F]{6}$/)
 
     // Navigate using View Transitions
-    await page.navigateToPage('/articles')
-    await page.waitForURL('**/articles', { timeout: 5000 })
+    await navigateAndAwaitHydration(page, '/articles', '**/articles')
 
     // Check if head element persisted (Astro keeps the same head element)
     const afterNavigationHead = await page.evaluate(() => {
@@ -128,6 +140,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
   }) => {
     const page = await ComponentPersistencePage.init(playwrightPage)
     await page.goto('/')
+    await page.waitForHeaderComponents()
 
     // Get initial theme-color value
     const initialColor = await page.evaluate(() => {
@@ -138,8 +151,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
     expect(initialColor).toMatch(/^#[0-9a-fA-F]{6}$/)
 
     // Navigate to another page
-    await page.navigateToPage('/services')
-    await page.waitForURL('**/services', { timeout: 5000 })
+    await navigateAndAwaitHydration(page, '/services', '**/services')
 
     // Get theme-color value after navigation
     const afterNavigationColor = await page.evaluate(() => {
@@ -154,6 +166,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
     // Home is not listed in the navigation menu, so reload the page to return
     await page.goto('/')
     await page.waitForURL(/\/$/, { timeout: 5000 })
+    await page.waitForHeaderComponents()
 
     // Verify theme-color is still the same
     const finalColor = await page.evaluate(() => {
@@ -170,6 +183,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
   }) => {
     const page = await ComponentPersistencePage.init(playwrightPage)
     await page.goto('/')
+    await page.waitForHeaderComponents()
 
     // Mark the canonical link element to check if it's replaced or just updated
     const initialData = await page.evaluate(() => {
@@ -190,8 +204,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
     expect(initialData.href).toMatch(/\/$/)
 
     // Navigate to articles page
-    await page.navigateToPage('/articles')
-    await page.waitForURL('**/articles', { timeout: 5000 })
+    await navigateAndAwaitHydration(page, '/articles', '**/articles')
 
     // Check if element was replaced or just updated
     const afterNavigationData = await page.evaluate(() => {
@@ -225,6 +238,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
   }) => {
     const page = await ComponentPersistencePage.init(playwrightPage)
     await page.goto('/')
+    await page.waitForHeaderComponents()
 
     // Get initial sitemap URL
     const initialSitemap = await page.evaluate(() => {
@@ -235,8 +249,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
     expect(initialSitemap).toBe('/sitemap-index.xml')
 
     // Navigate to services page
-    await page.navigateToPage('/services')
-    await page.waitForURL('**/services', { timeout: 5000 })
+    await navigateAndAwaitHydration(page, '/services', '**/services')
 
     // Get sitemap URL after navigation
     const afterNavigationSitemap = await page.evaluate(() => {
@@ -254,6 +267,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
   }) => {
     const page = await ComponentPersistencePage.init(playwrightPage)
     await page.goto('/')
+    await page.waitForHeaderComponents()
 
     // Get initial mobile-web-app-capable value
     const initialValue = await page.evaluate(() => {
@@ -264,8 +278,7 @@ describe('View Transitions - transition:persist on meta theme-color', () => {
     expect(initialValue).toBe('yes')
 
     // Navigate to case studies page
-    await page.navigateToPage('/case-studies')
-    await page.waitForURL('**/case-studies', { timeout: 5000 })
+    await navigateAndAwaitHydration(page, '/case-studies', '**/case-studies')
 
     // Get mobile-web-app-capable value after navigation
     const afterNavigationValue = await page.evaluate(() => {