@arcadialdev/arcality 2.4.29 → 2.4.30

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

@@ -1,361 +0,0 @@
-# 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