Fix Playwright best practices and command correctness

references/assertions-waiting.md

@@ -111,7 +111,7 @@ expect(object).toHaveProperty("key", "value");
 // Exceptions
 expect(() => fn()).toThrow();
 expect(() => fn()).toThrow("error message");
-expect(async () => await asyncFn()).rejects.toThrow();
+await expect(asyncFn()).rejects.toThrow();
 ```
 
 ## Soft Assertions
@@ -175,14 +175,14 @@ await page.waitForURL(/\/dashboard/);
 
 // Wait for navigation after action
 await Promise.all([
-  page.waitForNavigation(),
+  page.waitForURL("**/dashboard"),
   page.click('a[href="/dashboard"]'),
 ]);
 
-// Or use Promise.all alternative
-const navigationPromise = page.waitForNavigation();
+// Or without Promise.all
+const urlPromise = page.waitForURL("**/dashboard");
 await page.click("a");
-await navigationPromise;
+await urlPromise;
 ```
 
 ### Wait for Network

references/debugging.md

@@ -36,8 +36,21 @@ Features:
 # Run with visible browser
 npx playwright test --headed
 
-# Slow down execution
-npx playwright test --headed --slow-motion=500
+# Interactive debugging (headed, paused, step-through)
+npx playwright test --debug
+```
+
+You can also set `slowMo` to add an `N` ms delay per action, making test execution easier to follow while debugging.
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    launchOptions: {
+      slowMo: 500,
+    },
+  },
+});
 ```
 
 ### UI Mode
@@ -194,7 +207,7 @@ test("find slow requests", async ({ page }) => {
 
 ```bash
 # Run in headless mode like CI
-CI=true npx playwright test --headed=false
+CI=true npx playwright test
 
 # Match CI browser versions
 npx playwright install --with-deps

references/fixtures-hooks.md

@@ -30,7 +30,7 @@ test("example", async ({
 ```typescript
 test("API call", async ({ request }) => {
   const response = await request.get("/api/users");
-  expect(response.ok()).toBeTruthy();
+  await expect(response).toBeOK();
 
   const users = await response.json();
   expect(users).toHaveLength(5);

references/flaky-tests.md

@@ -188,8 +188,14 @@ await page.click("#load-data");
 await expect(page.locator(".data-row")).toHaveCount(10, { timeout: 10000 });
 
 // ✅ BETTER: Wait for network response, then assert
+const responsePromise = page.waitForResponse(
+  (r) =>
+    r.url().includes("/api/data") &&
+    r.request().method() === "GET" &&
+    r.ok(),
+);
 await page.click("#load-data");
-await page.waitForResponse((r) => r.url().includes("/api/data"));
+await responsePromise;
 await expect(page.locator(".data-row")).toHaveCount(10);
 ```
 
@@ -325,7 +331,7 @@ export const test = base.extend<{ tempFile: string }>({
 
 ```bash
 # Run headless with CI environment variable
-CI=true npx playwright test --headed=false
+CI=true npx playwright test
 
 # Limit CPU (Linux/Mac)
 cpulimit -l 50 -- npx playwright test
@@ -346,10 +352,6 @@ export default defineConfig({
   use: {
     viewport: { width: 1280, height: 720 },
     deviceScaleFactor: 1,
-    // Reduce animation-related flakiness
-    launchOptions: {
-      args: ["--disable-animations"],
-    },
   },
 });
 ```

references/locators.md

@@ -27,8 +27,8 @@ Most robust approach - matches how users and assistive technology perceive the p
 
 ```typescript
 // Buttons
-page.getByRole("button", { name: "Submit" });
-page.getByRole("button", { name: /submit/i }); // case-insensitive regex
+page.getByRole("button", { name: "Submit", exact: true }); // exact accessible name
+page.getByRole("button", { name: /submit/i }); // flexible case-insensitive match
 
 // Links
 page.getByRole("link", { name: "Home" });

references/mobile-testing.md

@@ -68,9 +68,9 @@ for (const deviceName of mobileDevices) {
 ### Tap
 
 ```typescript
-test("tap to interact", async ({ page }) => {
-  test.use({ hasTouch: true });
+test.use({ hasTouch: true });
 
+test("tap to interact", async ({ page }) => {
   await page.goto("/gallery");
 
   // Tap is like click but for touch devices

references/projects-dependencies.md

@@ -247,9 +247,6 @@ npx playwright test --project=chromium
 
 # Run multiple projects
 npx playwright test --project=chromium --project=firefox
-
-# Run all except one
-npx playwright test --project=!webkit
 ```
 
 ### Run by Grep