1 files changed, 24 insertions, 5 deletions

diff --git a/playwright-js/API_REFERENCE.md b/playwright-js/API_REFERENCE.md
index 9ee2975..7307cd2 100644
--- a/playwright-js/API_REFERENCE.md
+++ b/playwright-js/API_REFERENCE.md
@@ -95,11 +95,15 @@ const { chromium } = require('playwright');
 
   const page = await context.newPage();
 
-  // Navigate
+  // Navigate. 'load' (or 'domcontentloaded') is the default-safe wait; prefer
+  // asserting on a visible landmark afterward for readiness (see below).
   await page.goto('https://example.com', {
-    waitUntil: 'networkidle'  // Wait for network to be idle
+    waitUntil: 'load'
   });
 
+  // Wait for a real app landmark instead of network state:
+  // await expect(page.getByRole('main')).toBeVisible();
+
   // Your automation here
 
   await browser.close();
@@ -259,6 +263,18 @@ await page.keyboard.press('ArrowDown');
 
 ### Smart Waiting
 
+**Prefer web assertions and locator waits for readiness.** Web assertions
+(`expect(locator).toBeVisible()`, `toHaveText()`, etc.) and `locator.waitFor()`
+auto-wait for a user-visible, app-specific condition — which is what "the page is
+ready" actually means. Lead with these:
+
+```javascript
+// PREFERRED: assert on a visible landmark (auto-waits)
+await expect(page.getByRole('main')).toBeVisible();
+await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+await page.getByText('Welcome back').waitFor();
+```
+
 ```javascript
 // Wait for element states
 await page.locator('button').waitFor({ state: 'visible' });
@@ -270,8 +286,11 @@ await page.locator('button').waitFor({ state: 'detached' });
 await page.waitForURL('**/success');
 await page.waitForURL(url => url.pathname === '/dashboard');
 
-// Wait for network
-await page.waitForLoadState('networkidle');
+// Load-state waits. 'load' / 'domcontentloaded' are fine for "page navigated".
+// AVOID 'networkidle' as a readiness signal — Playwright discourages it; a page
+// can be interactive long before the network quiets (or never quiet at all).
+// Wait on a visible landmark instead (see PREFERRED block above).
+await page.waitForLoadState('load');
 await page.waitForLoadState('domcontentloaded');
 
 // Wait for function
@@ -576,7 +595,7 @@ jobs:
 
 1. **Test Organization** - Use descriptive test names, group related tests
 2. **Selector Strategy** - Prefer data-testid attributes, use role-based selectors
-3. **Waiting** - Use Playwright's auto-waiting, avoid hard-coded delays
+3. **Waiting** - Lead with web assertions (`expect(locator).toBeVisible()`) and locator waits; they auto-wait for a real, visible condition. Avoid `networkidle` as a readiness signal (Playwright discourages it) and avoid hard-coded delays.
 4. **Error Handling** - Add proper error messages, take screenshots on failure
 5. **Performance** - Run tests in parallel, reuse authentication state