@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/advanced/mobile-testing.md

@@ -0,0 +1,409 @@
+# Mobile & Responsive Testing
+
+## Table of Contents
+
+1. [Device Emulation](#device-emulation)
+2. [Touch Gestures](#touch-gestures)
+3. [Viewport Testing](#viewport-testing)
+4. [Mobile-Specific UI](#mobile-specific-ui)
+5. [Responsive Breakpoints](#responsive-breakpoints)
+
+## Device Emulation
+
+### Use Built-in Devices
+
+```typescript
+import { test, devices } from "@playwright/test";
+
+// Configure in playwright.config.ts
+export default defineConfig({
+  projects: [
+    { name: "Desktop Chrome", use: { ...devices["Desktop Chrome"] } },
+    { name: "Mobile Safari", use: { ...devices["iPhone 14"] } },
+    { name: "Mobile Chrome", use: { ...devices["Pixel 7"] } },
+    { name: "Tablet", use: { ...devices["iPad Pro 11"] } },
+  ],
+});
+```
+
+### Custom Device Configuration
+
+```typescript
+test.use({
+  viewport: { width: 390, height: 844 },
+  deviceScaleFactor: 3,
+  isMobile: true,
+  hasTouch: true,
+  userAgent:
+    "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15",
+});
+
+test("custom mobile device", async ({ page }) => {
+  await page.goto("/");
+  // Test runs with custom device settings
+});
+```
+
+### Test Across Multiple Devices
+
+```typescript
+const mobileDevices = ["iPhone 14", "Pixel 7", "Galaxy S21"];
+
+for (const deviceName of mobileDevices) {
+  test(`checkout on ${deviceName}`, async ({ browser }) => {
+    const device = devices[deviceName];
+    const context = await browser.newContext({ ...device });
+    const page = await context.newPage();
+
+    await page.goto("/checkout");
+    await expect(page.getByRole("button", { name: "Pay" })).toBeVisible();
+
+    await context.close();
+  });
+}
+```
+
+## Touch Gestures
+
+### Tap
+
+```typescript
+test.use({ hasTouch: true });
+
+test("tap to interact", async ({ page }) => {
+  await page.goto("/gallery");
+
+  // Tap is like click but for touch devices
+  await page.getByRole("img", { name: "Photo 1" }).tap();
+
+  await expect(page.getByRole("dialog")).toBeVisible();
+});
+```
+
+### Swipe
+
+```typescript
+test("swipe carousel", async ({ page }) => {
+  await page.goto("/carousel");
+
+  const carousel = page.getByTestId("carousel");
+  const box = await carousel.boundingBox();
+
+  if (box) {
+    // Swipe left
+    await page.touchscreen.tap(box.x + box.width - 50, box.y + box.height / 2);
+    await page.mouse.move(box.x + 50, box.y + box.height / 2);
+
+    // Or use drag
+    await carousel.dragTo(carousel, {
+      sourcePosition: { x: box.width - 50, y: box.height / 2 },
+      targetPosition: { x: 50, y: box.height / 2 },
+    });
+  }
+
+  await expect(page.getByText("Slide 2")).toBeVisible();
+});
+```
+
+### Swipe Fixture
+
+```typescript
+// fixtures/touch.fixture.ts
+import { test as base, Page } from "@playwright/test";
+
+type TouchFixtures = {
+  swipe: (
+    element: Locator,
+    direction: "left" | "right" | "up" | "down",
+  ) => Promise<void>;
+};
+
+export const test = base.extend<TouchFixtures>({
+  swipe: async ({ page }, use) => {
+    await use(async (element, direction) => {
+      const box = await element.boundingBox();
+      if (!box) throw new Error("Element not visible");
+
+      const centerX = box.x + box.width / 2;
+      const centerY = box.y + box.height / 2;
+      const distance = 100;
+
+      const moves = {
+        left: {
+          startX: centerX + distance,
+          endX: centerX - distance,
+          y: centerY,
+        },
+        right: {
+          startX: centerX - distance,
+          endX: centerX + distance,
+          y: centerY,
+        },
+        up: {
+          startX: centerX,
+          endX: centerX,
+          startY: centerY + distance,
+          endY: centerY - distance,
+        },
+        down: {
+          startX: centerX,
+          endX: centerX,
+          startY: centerY - distance,
+          endY: centerY + distance,
+        },
+      };
+
+      const move = moves[direction];
+      await page.touchscreen.tap(move.startX, move.startY ?? move.y);
+      await page.mouse.move(move.endX, move.endY ?? move.y, { steps: 10 });
+      await page.mouse.up();
+    });
+  },
+});
+
+// Usage
+test("swipe to delete", async ({ page, swipe }) => {
+  await page.goto("/inbox");
+
+  const message = page.getByTestId("message-1");
+  await swipe(message, "left");
+
+  await expect(page.getByRole("button", { name: "Delete" })).toBeVisible();
+});
+```
+
+### Long Press
+
+```typescript
+test("long press for context menu", async ({ page }) => {
+  await page.goto("/files");
+
+  const file = page.getByText("document.pdf");
+  const box = await file.boundingBox();
+
+  if (box) {
+    // Touch down
+    await page.touchscreen.tap(box.x + box.width / 2, box.y + box.height / 2);
+
+    // Hold for 500ms
+    await page.waitForTimeout(500);
+
+    // Context menu should appear
+    await expect(page.getByRole("menu")).toBeVisible();
+  }
+});
+```
+
+### Pinch Zoom
+
+```typescript
+test("pinch to zoom image", async ({ page }) => {
+  await page.goto("/map");
+
+  // Pinch zoom requires two touch points
+  // Playwright doesn't have native pinch support, so we simulate via evaluate
+  await page.evaluate(() => {
+    const element = document.querySelector("#map");
+    if (element) {
+      // Simulate wheel event as fallback for zoom
+      element.dispatchEvent(
+        new WheelEvent("wheel", {
+          deltaY: -100, // Negative = zoom in
+          ctrlKey: true, // Ctrl+wheel = pinch on many apps
+        }),
+      );
+    }
+  });
+
+  // Or trigger the app's zoom function directly
+  await page.evaluate(() => {
+    (window as any).mapInstance?.setZoom(15);
+  });
+});
+```
+
+## Viewport Testing
+
+### Test Different Sizes
+
+```typescript
+const viewports = [
+  { name: "mobile", width: 375, height: 667 },
+  { name: "tablet", width: 768, height: 1024 },
+  { name: "desktop", width: 1920, height: 1080 },
+];
+
+for (const { name, width, height } of viewports) {
+  test(`navigation on ${name}`, async ({ page }) => {
+    await page.setViewportSize({ width, height });
+    await page.goto("/");
+
+    if (width < 768) {
+      // Mobile: should have hamburger menu
+      await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+    } else {
+      // Desktop: should have visible nav links
+      await expect(page.getByRole("link", { name: "Products" })).toBeVisible();
+    }
+  });
+}
+```
+
+### Dynamic Viewport Changes
+
+```typescript
+test("responsive layout change", async ({ page }) => {
+  await page.setViewportSize({ width: 1200, height: 800 });
+  await page.goto("/dashboard");
+
+  // Desktop: sidebar visible
+  await expect(page.getByRole("complementary")).toBeVisible();
+
+  // Resize to mobile
+  await page.setViewportSize({ width: 375, height: 667 });
+
+  // Mobile: sidebar hidden, hamburger visible
+  await expect(page.getByRole("complementary")).toBeHidden();
+  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+});
+```
+
+## Mobile-Specific UI
+
+### Hamburger Menu
+
+```typescript
+test("mobile navigation", async ({ page }) => {
+  await page.setViewportSize({ width: 375, height: 667 });
+  await page.goto("/");
+
+  // Open hamburger menu
+  await page.getByRole("button", { name: "Menu" }).click();
+
+  // Navigation drawer should appear
+  const nav = page.getByRole("navigation");
+  await expect(nav).toBeVisible();
+
+  // Navigate via mobile menu
+  await nav.getByRole("link", { name: "Products" }).click();
+
+  await expect(page).toHaveURL("/products");
+  // Menu should close after navigation
+  await expect(nav).toBeHidden();
+});
+```
+
+### Bottom Sheet
+
+```typescript
+test("bottom sheet interaction", async ({ page }) => {
+  await page.setViewportSize({ width: 375, height: 667 });
+  await page.goto("/product/123");
+
+  await page.getByRole("button", { name: "Add to Cart" }).click();
+
+  // Bottom sheet appears
+  const sheet = page.getByRole("dialog");
+  await expect(sheet).toBeVisible();
+
+  // Select options
+  await sheet.getByRole("combobox", { name: "Size" }).selectOption("Large");
+  await sheet.getByRole("button", { name: "Confirm" }).click();
+
+  await expect(page.getByText("Added to cart")).toBeVisible();
+});
+```
+
+### Pull to Refresh
+
+```typescript
+test("pull to refresh", async ({ page }) => {
+  await page.goto("/feed");
+
+  const feed = page.getByTestId("feed");
+  const initialFirstItem = await feed.locator("> *").first().textContent();
+
+  // Simulate pull down
+  const box = await feed.boundingBox();
+  if (box) {
+    await page.touchscreen.tap(box.x + box.width / 2, box.y + 50);
+    await page.mouse.move(box.x + box.width / 2, box.y + 200, { steps: 20 });
+    await page.mouse.up();
+  }
+
+  // Wait for refresh
+  await expect(page.getByTestId("loading")).toBeVisible();
+  await expect(page.getByTestId("loading")).toBeHidden();
+
+  // Content should be updated (in a real app)
+});
+```
+
+## Responsive Breakpoints
+
+### Test All Breakpoints
+
+```typescript
+const breakpoints = {
+  xs: 320,
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  "2xl": 1536,
+};
+
+test.describe("responsive header", () => {
+  for (const [name, width] of Object.entries(breakpoints)) {
+    test(`header at ${name} (${width}px)`, async ({ page }) => {
+      await page.setViewportSize({ width, height: 800 });
+      await page.goto("/");
+
+      if (width < 768) {
+        await expect(page.getByTestId("mobile-menu-button")).toBeVisible();
+        await expect(page.getByTestId("desktop-nav")).toBeHidden();
+      } else {
+        await expect(page.getByTestId("mobile-menu-button")).toBeHidden();
+        await expect(page.getByTestId("desktop-nav")).toBeVisible();
+      }
+    });
+  }
+});
+```
+
+### Visual Regression at Breakpoints
+
+```typescript
+test.describe("visual regression", () => {
+  const sizes = [
+    { width: 375, height: 667, name: "mobile" },
+    { width: 768, height: 1024, name: "tablet" },
+    { width: 1440, height: 900, name: "desktop" },
+  ];
+
+  for (const { width, height, name } of sizes) {
+    test(`homepage at ${name}`, async ({ page }) => {
+      await page.setViewportSize({ width, height });
+      await page.goto("/");
+
+      await expect(page).toHaveScreenshot(`homepage-${name}.png`);
+    });
+  }
+});
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern                | Problem                   | Solution                         |
+| --------------------------- | ------------------------- | -------------------------------- |
+| Only testing one viewport   | Misses responsive bugs    | Test multiple breakpoints        |
+| Ignoring touch events       | Features broken on mobile | Test tap, swipe, long press      |
+| Hardcoded viewport in tests | Can't test multiple sizes | Use `page.setViewportSize()`     |
+| Not testing orientation     | Landscape bugs missed     | Test both portrait and landscape |
+
+## Related References
+
+- **Visual Testing**: See [test-suite-structure.md](../core/test-suite-structure.md) for screenshot testing
+- **Locators**: See [locators.md](../core/locators.md) for mobile-friendly selectors
+- **Browser APIs**: See [browser-apis.md](../browser-apis/browser-apis.md) for permissions (camera, geolocation, notifications)
+- **Canvas/Touch**: See [canvas-webgl.md](../testing-patterns/canvas-webgl.md) for touch gestures on canvas elements

package/.agents/skills/playwright-best-practices/advanced/multi-context.md

@@ -0,0 +1,288 @@
+# Multi-Tab, Window & Popup Testing
+
+This file covers **single-user scenarios** with multiple browser tabs, windows, and popups. For **multi-user collaboration testing** (multiple users interacting simultaneously), see [multi-user.md](multi-user.md).
+
+## Table of Contents
+
+1. [Popup Handling](#popup-handling)
+2. [New Tab Navigation](#new-tab-navigation)
+3. [OAuth Flows](#oauth-flows)
+4. [Multiple Windows](#multiple-windows)
+5. [Tab Coordination](#tab-coordination)
+
+## Popup Handling
+
+### Basic Popup
+
+```typescript
+test("handle popup window", async ({ page }) => {
+  await page.goto("/");
+
+  // Start waiting for popup before triggering it
+  const popupPromise = page.waitForEvent("popup");
+  await page.getByRole("button", { name: "Open Support Chat" }).click();
+  const popup = await popupPromise;
+
+  // Wait for popup to load
+  await popup.waitForLoadState();
+
+  // Interact with popup
+  await popup.getByLabel("Message").fill("Need help");
+  await popup.getByRole("button", { name: "Send" }).click();
+
+  await expect(popup.getByText("Message sent")).toBeVisible();
+
+  // Close popup
+  await popup.close();
+});
+```
+
+### Popup with Authentication
+
+```typescript
+test("popup login flow", async ({ page }) => {
+  await page.goto("/dashboard");
+
+  const popupPromise = page.waitForEvent("popup");
+  await page.getByRole("button", { name: "Connect Account" }).click();
+  const popup = await popupPromise;
+
+  await popup.waitForLoadState();
+
+  // Complete login in popup
+  await popup.getByLabel("Email").fill("user@example.com");
+  await popup.getByLabel("Password").fill("password123");
+  await popup.getByRole("button", { name: "Log In" }).click();
+
+  // Popup should close automatically after auth
+  await popup.waitForEvent("close");
+
+  // Main page should reflect connected state
+  await expect(page.getByText("Account connected")).toBeVisible();
+});
+```
+
+### Handle Blocked Popups
+
+```typescript
+test("handle popup blocker", async ({ page }) => {
+  await page.goto("/share");
+
+  // Listen for console messages about blocked popup
+  page.on("console", (msg) => {
+    if (msg.text().includes("popup blocked")) {
+      console.log("Popup was blocked");
+    }
+  });
+
+  const popupPromise = page.waitForEvent("popup").catch(() => null);
+  await page.getByRole("button", { name: "Share to Twitter" }).click();
+  const popup = await popupPromise;
+
+  if (!popup) {
+    // Popup blocked - app should show fallback
+    await expect(page.getByText("Copy share link instead")).toBeVisible();
+  }
+});
+```
+
+## New Tab Navigation
+
+### Link Opens in New Tab
+
+```typescript
+test("external link opens in new tab", async ({ page, context }) => {
+  await page.goto("/resources");
+
+  // Wait for new page in context
+  const pagePromise = context.waitForEvent("page");
+  await page.getByRole("link", { name: "Documentation" }).click();
+  const newPage = await pagePromise;
+
+  await newPage.waitForLoadState();
+
+  expect(newPage.url()).toContain("docs.example.com");
+  await expect(newPage.getByRole("heading", { level: 1 })).toBeVisible();
+
+  // Original page still there
+  expect(page.url()).toContain("/resources");
+
+  await newPage.close();
+});
+```
+
+### Intercept New Tab
+
+```typescript
+test("prevent new tab for testing", async ({ page }) => {
+  await page.goto("/links");
+
+  // Remove target="_blank" to keep navigation in same tab
+  await page.evaluate(() => {
+    document.querySelectorAll('a[target="_blank"]').forEach((a) => {
+      a.removeAttribute("target");
+    });
+  });
+
+  // Now link opens in same tab
+  await page.getByRole("link", { name: "External Site" }).click();
+
+  // Can test the destination page
+  await expect(page).toHaveURL(/external-site\.com/);
+});
+```
+
+## OAuth Flows
+
+### Google OAuth Popup
+
+```typescript
+test("Google OAuth login", async ({ page }) => {
+  await page.goto("/login");
+
+  const popupPromise = page.waitForEvent("popup");
+  await page.getByRole("button", { name: "Sign in with Google" }).click();
+  const popup = await popupPromise;
+
+  await popup.waitForLoadState();
+
+  // Handle Google's OAuth flow
+  await popup.getByLabel("Email or phone").fill("test@gmail.com");
+  await popup.getByRole("button", { name: "Next" }).click();
+
+  await popup.getByLabel("Enter your password").fill("password");
+  await popup.getByRole("button", { name: "Next" }).click();
+
+  // Wait for redirect back and popup close
+  await popup.waitForEvent("close");
+
+  // Verify logged in on main page
+  await expect(page.getByText("Welcome, Test User")).toBeVisible();
+});
+```
+
+### Mock OAuth (Recommended)
+
+```typescript
+test("mock OAuth flow", async ({ page, context }) => {
+  // Mock the OAuth callback instead of real flow
+  await page.route("**/auth/callback**", async (route) => {
+    // Simulate successful OAuth
+    const url = new URL(route.request().url());
+    url.searchParams.set("code", "mock-auth-code");
+    await route.fulfill({
+      status: 302,
+      headers: { Location: "/dashboard" },
+    });
+  });
+
+  // Mock token exchange
+  await page.route("**/api/auth/token", (route) =>
+    route.fulfill({
+      json: {
+        access_token: "mock-token",
+        user: { name: "Test User", email: "test@example.com" },
+      },
+    }),
+  );
+
+  await page.goto("/login");
+  await page.getByRole("button", { name: "Sign in with Google" }).click();
+
+  // Should redirect to dashboard without actual OAuth
+  await expect(page).toHaveURL("/dashboard");
+  await expect(page.getByText("Welcome, Test User")).toBeVisible();
+});
+```
+
+### OAuth Fixture
+
+> **For comprehensive OAuth mocking patterns** (fixtures, multiple providers, SAML SSO), see [third-party.md](third-party.md#oauthsso-mocking). This section focuses on popup window handling mechanics for OAuth flows.
+
+## Multiple Windows
+
+### Test Across Multiple Windows
+
+```typescript
+test("sync between windows", async ({ context }) => {
+  // Open two pages
+  const page1 = await context.newPage();
+  const page2 = await context.newPage();
+
+  await page1.goto("/dashboard");
+  await page2.goto("/dashboard");
+
+  // Make change in first window
+  await page1.getByRole("button", { name: "Add Item" }).click();
+  await page1.getByLabel("Name").fill("New Item");
+  await page1.getByRole("button", { name: "Save" }).click();
+
+  // Should sync to second window (if app supports real-time sync)
+  await expect(page2.getByText("New Item")).toBeVisible({ timeout: 10000 });
+});
+```
+
+### Different Users in Different Windows
+
+> **For multi-user collaboration patterns** (admin/user interactions, real-time collaboration, role-based testing, concurrent actions), see [multi-user.md](multi-user.md). This file focuses on single-user scenarios with multiple tabs/windows/popups.
+
+## Tab Coordination
+
+### Switch Between Tabs
+
+```typescript
+test("manage multiple tabs", async ({ context }) => {
+  const page1 = await context.newPage();
+  await page1.goto("/editor");
+
+  const page2 = await context.newPage();
+  await page2.goto("/preview");
+
+  // Edit in first tab
+  await page1.bringToFront();
+  await page1.getByLabel("Content").fill("Hello World");
+
+  // Check preview in second tab
+  await page2.bringToFront();
+  await page2.reload(); // If preview needs refresh
+  await expect(page2.getByText("Hello World")).toBeVisible();
+});
+```
+
+### Close All Tabs Except One
+
+```typescript
+test("cleanup tabs after test", async ({ context }) => {
+  const mainPage = await context.newPage();
+  await mainPage.goto("/");
+
+  // Open several popups during test
+  for (let i = 0; i < 3; i++) {
+    const popup = await context.newPage();
+    await popup.goto(`/popup/${i}`);
+  }
+
+  // Close all except main page
+  for (const page of context.pages()) {
+    if (page !== mainPage) {
+      await page.close();
+    }
+  }
+
+  expect(context.pages()).toHaveLength(1);
+});
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern            | Problem                        | Solution                                   |
+| ----------------------- | ------------------------------ | ------------------------------------------ |
+| Not waiting for popup   | Race condition                 | Use `waitForEvent("popup")` before trigger |
+| Testing real OAuth      | Slow, flaky, needs credentials | Mock OAuth endpoints                       |
+| Assuming popup opens    | May be blocked                 | Handle both open and blocked cases         |
+| Not closing extra pages | Resource leak                  | Close pages in cleanup                     |
+
+## Related References
+
+- **Authentication**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for auth patterns
+- **Network**: See [network-advanced.md](network-advanced.md) for mocking OAuth