@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/core/assertions-waiting.md

@@ -0,0 +1,361 @@
+# Assertions & Waiting
+
+## Table of Contents
+
+1. [Web-First Assertions](#web-first-assertions)
+2. [Generic Assertions](#generic-assertions)
+3. [Soft Assertions](#soft-assertions)
+4. [Waiting Strategies](#waiting-strategies)
+5. [Polling & Retrying](#polling--retrying)
+6. [Custom Matchers](#custom-matchers)
+
+## Web-First Assertions
+
+Auto-retry until condition is met or timeout. Always prefer these over generic assertions.
+
+### Locator Assertions
+
+```typescript
+import { expect } from "@playwright/test";
+
+// Visibility
+await expect(page.getByRole("button")).toBeVisible();
+await expect(page.getByRole("button")).toBeHidden();
+await expect(page.getByRole("button")).not.toBeVisible();
+
+// Enabled/Disabled
+await expect(page.getByRole("button")).toBeEnabled();
+await expect(page.getByRole("button")).toBeDisabled();
+
+// Text content
+await expect(page.getByRole("heading")).toHaveText("Welcome");
+await expect(page.getByRole("heading")).toHaveText(/welcome/i);
+await expect(page.getByRole("heading")).toContainText("Welcome");
+
+// Count
+await expect(page.getByRole("listitem")).toHaveCount(5);
+
+// Attributes
+await expect(page.getByRole("link")).toHaveAttribute("href", "/home");
+await expect(page.getByRole("img")).toHaveAttribute("alt", /logo/i);
+
+// CSS
+await expect(page.getByRole("button")).toHaveClass(/primary/);
+await expect(page.getByRole("button")).toHaveCSS("color", "rgb(0, 0, 255)");
+
+// Input values
+await expect(page.getByLabel("Email")).toHaveValue("user@example.com");
+await expect(page.getByLabel("Email")).toBeEmpty();
+
+// Focus
+await expect(page.getByLabel("Email")).toBeFocused();
+
+// Checked state
+await expect(page.getByRole("checkbox")).toBeChecked();
+await expect(page.getByRole("checkbox")).not.toBeChecked();
+
+// Editable state
+await expect(page.getByLabel("Name")).toBeEditable();
+```
+
+### Page Assertions
+
+```typescript
+// URL
+await expect(page).toHaveURL("/dashboard");
+await expect(page).toHaveURL(/\/dashboard/);
+
+// Title
+await expect(page).toHaveTitle("Dashboard - MyApp");
+await expect(page).toHaveTitle(/dashboard/i);
+```
+
+### Response Assertions
+
+```typescript
+const response = await page.request.get("/api/users");
+await expect(response).toBeOK();
+await expect(response).not.toBeOK();
+```
+
+## Generic Assertions
+
+Use for non-UI values. Do NOT retry - execute immediately.
+
+```typescript
+// Equality
+expect(value).toBe(5);
+expect(object).toEqual({ name: "Test" });
+expect(array).toContain("item");
+
+// Truthiness
+expect(value).toBeTruthy();
+expect(value).toBeFalsy();
+expect(value).toBeNull();
+expect(value).toBeUndefined();
+expect(value).toBeDefined();
+
+// Numbers
+expect(value).toBeGreaterThan(5);
+expect(value).toBeLessThanOrEqual(10);
+expect(value).toBeCloseTo(5.5, 1);
+
+// Strings
+expect(string).toMatch(/pattern/);
+expect(string).toContain("substring");
+
+// Arrays/Objects
+expect(array).toHaveLength(3);
+expect(object).toHaveProperty("key", "value");
+
+// Exceptions
+expect(() => fn()).toThrow();
+expect(() => fn()).toThrow("error message");
+await expect(asyncFn()).rejects.toThrow();
+```
+
+## Soft Assertions
+
+Continue test execution after failure, report all failures at end.
+
+```typescript
+test("check multiple elements", async ({ page }) => {
+  await page.goto("/dashboard");
+
+  // Won't stop on first failure
+  await expect.soft(page.getByRole("heading")).toHaveText("Dashboard");
+  await expect.soft(page.getByRole("button", { name: "Save" })).toBeEnabled();
+  await expect.soft(page.getByText("Welcome")).toBeVisible();
+
+  // Test continues; all failures reported at end
+});
+```
+
+### Soft Assertions with Early Exit
+
+```typescript
+test("check form", async ({ page }) => {
+  await expect.soft(page.getByRole("form")).toBeVisible();
+
+  // Exit early if form not visible (pointless to check fields)
+  if (expect.soft.hasFailures()) {
+    return;
+  }
+
+  await expect.soft(page.getByLabel("Name")).toBeVisible();
+  await expect.soft(page.getByLabel("Email")).toBeVisible();
+});
+```
+
+## Waiting Strategies
+
+### Auto-Waiting (Default)
+
+Actions automatically wait for:
+
+- Element to be attached to DOM
+- Element to be visible
+- Element to be stable (no animations)
+- Element to be enabled
+- Element to receive events
+
+```typescript
+// These auto-wait
+await page.click("button");
+await page.fill("input", "text");
+await page.getByRole("button").click();
+```
+
+### Wait for Navigation
+
+```typescript
+// Wait for URL change
+await page.waitForURL("/dashboard");
+await page.waitForURL(/\/dashboard/);
+
+// Wait for navigation after action
+await Promise.all([
+  page.waitForURL("**/dashboard"),
+  page.click('a[href="/dashboard"]'),
+]);
+
+// Or without Promise.all
+const urlPromise = page.waitForURL("**/dashboard");
+await page.click("a");
+await urlPromise;
+```
+
+### Wait for Network
+
+```typescript
+// Wait for specific response
+const responsePromise = page.waitForResponse("**/api/users");
+await page.click("button");
+const response = await responsePromise;
+expect(response.status()).toBe(200);
+
+// Wait for request
+const requestPromise = page.waitForRequest("**/api/submit");
+await page.click("button");
+const request = await requestPromise;
+
+// Wait for no network activity
+await page.waitForLoadState("networkidle");
+```
+
+### Wait for Element State
+
+```typescript
+// Wait for element to appear
+await page.getByRole("dialog").waitFor({ state: "visible" });
+
+// Wait for element to disappear
+await page.getByText("Loading...").waitFor({ state: "hidden" });
+
+// Wait for element to be attached
+await page.getByTestId("result").waitFor({ state: "attached" });
+
+// Wait for element to be detached
+await page.getByTestId("modal").waitFor({ state: "detached" });
+```
+
+### Wait for Function
+
+```typescript
+// Wait for arbitrary condition
+await page.waitForFunction(() => {
+  return document.querySelector(".loaded") !== null;
+});
+
+// With arguments
+await page.waitForFunction(
+  (selector) => document.querySelector(selector)?.textContent === "Ready",
+  ".status",
+);
+```
+
+## Polling & Retrying
+
+### toPass() for Polling
+
+Retry until block passes or times out:
+
+```typescript
+await expect(async () => {
+  const response = await page.request.get("/api/status");
+  expect(response.status()).toBe(200);
+
+  const data = await response.json();
+  expect(data.ready).toBe(true);
+}).toPass({
+  intervals: [1000, 2000, 5000], // Retry intervals
+  timeout: 30000,
+});
+```
+
+### expect.poll()
+
+Poll a function until assertion passes:
+
+```typescript
+// Poll API until condition met
+await expect
+  .poll(
+    async () => {
+      const response = await page.request.get("/api/job/123");
+      return (await response.json()).status;
+    },
+    {
+      intervals: [1000, 2000, 5000],
+      timeout: 30000,
+    },
+  )
+  .toBe("completed");
+
+// Poll DOM value
+await expect.poll(() => page.getByTestId("counter").textContent()).toBe("10");
+```
+
+## Custom Matchers
+
+```typescript
+// playwright.config.ts or fixtures
+import { expect } from "@playwright/test";
+
+expect.extend({
+  async toHaveDataLoaded(page: Page) {
+    const locator = page.getByTestId("data-container");
+    let pass = false;
+    let message = "";
+
+    try {
+      await expect(locator).toBeVisible();
+      await expect(locator).not.toContainText("Loading");
+      pass = true;
+    } catch (e) {
+      message = `Expected data to be loaded but found loading state`;
+    }
+
+    return { pass, message: () => message };
+  },
+});
+
+// Extend TypeScript types
+declare global {
+  namespace PlaywrightTest {
+    interface Matchers<R> {
+      toHaveDataLoaded(): Promise<R>;
+    }
+  }
+}
+
+// Usage
+await expect(page).toHaveDataLoaded();
+```
+
+## Timeouts
+
+### Configure Timeouts
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  timeout: 30000, // Test timeout
+  expect: {
+    timeout: 5000, // Assertion timeout
+  },
+});
+
+// Per-test timeout
+test("long test", async ({ page }) => {
+  test.setTimeout(60000);
+  // ...
+});
+
+// Per-assertion timeout
+await expect(page.getByRole("button")).toBeVisible({ timeout: 10000 });
+```
+
+## Best Practices
+
+| Do                             | Don't                          |
+| ------------------------------ | ------------------------------ |
+| Use web-first assertions       | Use generic assertions for DOM |
+| Let auto-waiting work          | Add unnecessary explicit waits |
+| Use `toPass()` for polling     | Write manual retry loops       |
+| Configure appropriate timeouts | Use `waitForTimeout()`         |
+| Check specific conditions      | Wait for arbitrary time        |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern                                              | Problem                       | Solution                                     |
+| --------------------------------------------------------- | ----------------------------- | -------------------------------------------- |
+| `await page.waitForTimeout(5000)`                         | Slow, flaky, arbitrary timing | Use auto-waiting or `waitForResponse`        |
+| `await new Promise(resolve => setTimeout(resolve, 1000))` | Same as above                 | Use `waitForResponse` or element state waits |
+| Generic assertions on DOM elements                        | No auto-retry, flaky          | Use web-first assertions with `expect()`     |
+
+## Related References
+
+- **Debugging timeout issues**: See [debugging.md](../debugging/debugging.md) for troubleshooting
+- **Fixing flaky tests**: See [debugging.md](../debugging/debugging.md) for race condition solutions
+- **Network interception**: See [test-suite-structure.md](test-suite-structure.md) for API mocking