@arcadialdev/arcality 2.4.29 → 2.4.30

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

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

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