docs: Add synchronization and wait strategies guide for Playwright, covering WaitIUtils and advanced waits.

Author: kavitaj11

doc/sync-wait-strategies-playwright.md

@@ -0,0 +1,104 @@
+# Playwright Synchronization & Wait Strategies
+
+This guide demonstrates synchronization techniques in Playwright, from basic to advanced, and documents the enhanced `WaitIUtils` utility for robust, maintainable tests.
+
+---
+
+## Why Synchronization Matters
+- Web UIs are dynamic: elements may appear/disappear, load asynchronously, or change state.
+- Proper waits prevent flaky tests and ensure reliability.
+
+---
+
+## 1. Static Waits (Not Recommended)
+```js
+await page.waitForTimeout(2000); // Hard wait for 2 seconds
+```
+- Use only for debugging or as a last resort.
+
+---
+
+## 2. Dynamic Waits for Element State
+- **Visible:**
+  ```js
+  await page.waitForSelector('.selector', { state: 'visible' });
+  ```
+- **Attached:**
+  ```js
+  await page.waitForSelector('.selector', { state: 'attached' });
+  ```
+- **Hidden:**
+  ```js
+  await page.waitForSelector('.selector', { state: 'hidden' });
+  ```
+- **Detached:**
+  ```js
+  await page.waitForSelector('.selector', { state: 'detached' });
+  ```
+
+---
+
+## 3. Wait for Text Content
+```js
+await page.waitForFunction(
+  sel => document.querySelector(sel)?.textContent.includes('expected'),
+  '.selector'
+);
+```
+
+---
+
+## 4. Wait for Custom Condition
+```js
+await page.waitForFunction(() => document.querySelectorAll('.item').length >= 2);
+```
+
+---
+
+## 5. Wait for Network Idle
+```js
+await page.waitForLoadState('networkidle');
+```
+
+---
+
+## 6. Using the Enhanced WaitIUtils Utility
+
+`utils/WaitIUtils.js` provides reusable, readable wait helpers:
+
+```js
+const WaitIUtils = require('../utils/WaitIUtils');
+const waitUtil = new WaitIUtils(page);
+
+await waitUtil.wait(1000); // Static wait
+await waitUtil.waitForVisible('.selector');
+await waitUtil.waitForAttached('.selector');
+await waitUtil.waitForHidden('.selector');
+await waitUtil.waitForDetached('.selector');
+await waitUtil.waitForText('.selector', 'expected text');
+await waitUtil.waitForFunction(() => ...); // Custom JS condition
+await waitUtil.waitForNetworkIdle();
+```
+
+---
+
+## 7. Example: SynchronizationTechniques.spec.js
+See `tests/sync/SynchronizationTechniques.spec.js` for:
+- Static waits
+- Waiting for visible/attached/hidden/detached
+- Waiting for text
+- Waiting for custom conditions
+- Waiting for network idle
+- Advanced: hover to reveal hidden elements before interaction
+
+---
+
+## Best Practices
+- Prefer dynamic waits over static waits.
+- Use utility methods for readability and maintainability.
+- Always wait for the expected state before interacting with elements.
+- Use custom conditions for complex scenarios.
+
+---
+
+**For more, see Playwright docs:** https://playwright.dev/docs/waiting

tests/sync/SynchronizationTechniques.spec.js

@@ -0,0 +1,68 @@
+const { test, expect } = require('@playwright/test');
+const WaitIUtils = require('../../utils/WaitIUtils');
+
+// Demo page with dynamic elements (replace with your own if needed)
+const DEMO_URL = 'https://demo.playwright.dev/todomvc';
+
+test.describe('Synchronization Techniques: Basics to Advanced', () => {
+  let waitUtil;
+
+  test.beforeEach(async ({ page }) => {
+    waitUtil = new WaitIUtils(page);
+    await page.goto(DEMO_URL);
+  });
+
+  test('Static wait (not recommended for real tests)', async ({ page }) => {
+    await waitUtil.wait(2000); // Hard wait for 2 seconds
+    expect(await page.title()).toContain('React • TodoMVC');
+  });
+
+  test('Wait for element to be visible', async ({ page }) => {
+    await waitUtil.waitForVisible('.new-todo');
+    await page.fill('.new-todo', 'Learn Playwright');
+    await page.keyboard.press('Enter');
+    await waitUtil.waitForVisible('.todo-list li');
+    expect(await page.isVisible('.todo-list li')).toBe(true);
+  });
+
+  test('Wait for element to be attached to DOM', async ({ page }) => {
+    await waitUtil.waitForAttached('.new-todo');
+    await page.fill('.new-todo', 'Wait for attach');
+    await page.keyboard.press('Enter');
+    await waitUtil.waitForAttached('.todo-list li');
+    expect(await page.isVisible('.todo-list li')).toBe(true);
+  });
+
+  test('Wait for element to be hidden', async ({ page }) => {
+    await waitUtil.waitForVisible('.new-todo');
+    await page.fill('.new-todo', 'Hide me');
+    await page.keyboard.press('Enter');
+    await waitUtil.waitForVisible('.todo-list li');
+    // Hover over the todo item to reveal the .destroy button
+    await page.hover('.todo-list li');
+    await page.click('.destroy');
+    await waitUtil.waitForHidden('.todo-list li');
+    expect(await page.isVisible('.todo-list li')).toBe(false);
+  });
+
+  test('Advanced: Wait for network idle', async ({ page }) => {
+    // Reload and wait for network to be idle
+    await Promise.all([
+      page.waitForLoadState('networkidle'),
+      page.reload(),
+    ]);
+    expect(await page.title()).toContain('React • TodoMVC');
+  });
+
+  test('Advanced: Wait for custom condition', async ({ page }) => {
+    // Wait until there are at least 2 todos
+    await waitUtil.waitForVisible('.new-todo');
+    await page.fill('.new-todo', 'First');
+    await page.keyboard.press('Enter');
+    await page.fill('.new-todo', 'Second');
+    await page.keyboard.press('Enter');
+    await page.waitForFunction(() => document.querySelectorAll('.todo-list li').length >= 2);
+    const count = await page.locator('.todo-list li').count();
+    expect(count).toBeGreaterThanOrEqual(2);
+  });
+});

utils/WaitIUtils.js

@@ -23,6 +23,34 @@ class WaitIUtils {
 	async waitForHidden(selector, timeout = 5000) {
 		await this.page.waitForSelector(selector, { state: 'hidden', timeout });
 	}
+
+	// Wait for selector to be detached from DOM
+	async waitForDetached(selector, timeout = 5000) {
+		await this.page.waitForSelector(selector, { state: 'detached', timeout });
+	}
+
+	// Wait for element to contain specific text
+	async waitForText(selector, text, timeout = 5000) {
+		await this.page.waitForFunction(
+			(sel, txt) => {
+				const el = document.querySelector(sel);
+				return el && el.textContent.includes(txt);
+			},
+			selector,
+			text,
+			{ timeout }
+		);
+	}
+
+	// Wait for a custom function/condition
+	async waitForFunction(fn, arg, timeout = 5000) {
+		await this.page.waitForFunction(fn, arg, { timeout });
+	}
+
+	// Wait for network to be idle
+	async waitForNetworkIdle(timeout = 5000) {
+		await this.page.waitForLoadState('networkidle', { timeout });
+	}
 }
 
 module.exports = WaitIUtils;