Common Pitfalls (Top 10)

1. waitForTimeout

Symptom: Slow, flaky tests.

// BAD
await page.waitForTimeout(3000);

// GOOD
await expect(page.getByTestId('result')).toBeVisible();

2. Non-Web-First Assertions

Symptom: Assertions fail on dynamic content.

// BAD — checks once, no retry
const text = await page.textContent('.msg');
expect(text).toBe('Done');

// GOOD — retries until timeout
await expect(page.getByText('Done')).toBeVisible();

3. Missing await

Symptom: Random passes/failures, tests seem to skip steps.

// BAD
page.goto('/dashboard');
expect(page.getByText('Welcome')).toBeVisible();

// GOOD
await page.goto('/dashboard');
await expect(page.getByText('Welcome')).toBeVisible();

4. Hardcoded URLs

Symptom: Tests break in different environments.

// BAD
await page.goto('http://localhost:3000/login');

// GOOD — uses baseURL from config
await page.goto('/login');

5. CSS Selectors Instead of Roles

Symptom: Tests break after CSS refactors.

// BAD
await page.click('#submit-btn');

// GOOD
await page.getByRole('button', { name: 'Submit' }).click();

6. Shared State Between Tests

Symptom: Tests pass alone, fail in suite.

// BAD — test B depends on test A
let userId: string;
test('create user', async () => { userId = '123'; });
test('edit user', async () => { /* uses userId */ });

// GOOD — each test is independent
test('edit user', async ({ request }) => {
  const res = await request.post('/api/users', { data: { name: 'Test' } });
  const { id } = await res.json();
  // ...
});

7. Using networkidle

Symptom: Tests hang or timeout unpredictably.

// BAD — waits for all network activity to stop
await page.goto('/dashboard', { waitUntil: 'networkidle' });

// GOOD — wait for specific content
await page.goto('/dashboard');
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();

Symptom: Assertions run on wrong page.

// BAD — click navigates but we don't wait
await page.getByRole('link', { name: 'Settings' }).click();
await expect(page.getByRole('heading')).toHaveText('Settings');

// GOOD — wait for URL change
await page.getByRole('link', { name: 'Settings' }).click();
await expect(page).toHaveURL('/settings');
await expect(page.getByRole('heading')).toHaveText('Settings');

9. Testing Implementation, Not Behavior

Symptom: Tests break on every refactor.

// BAD — tests CSS class (implementation detail)
await expect(page.locator('.btn')).toHaveClass('btn-primary active');

// GOOD — tests what the user sees
await expect(page.getByRole('button', { name: 'Save' })).toBeEnabled();

10. No Error Case Tests

Symptom: App breaks on errors but all tests pass.

// Missing: what happens when the API fails?
test('should handle API error', async ({ page }) => {
  await page.route('**/api/data', (route) =>
    route.fulfill({ status: 500 })
  );
  await page.goto('/dashboard');
  await expect(page.getByText(/error|try again/i)).toBeVisible();
});

3.1 KiB Raw Blame History