@arcadialdev/arcality 2.4.28 → 2.4.30

package/.agents/skills/playwright-best-practices/browser-apis/iframes.md

@@ -1,403 +0,0 @@
-# iFrame Testing
-
-## Table of Contents
-
-1. [Basic iFrame Access](#basic-iframe-access)
-2. [Cross-Origin iFrames](#cross-origin-iframes)
-3. [Nested iFrames](#nested-iframes)
-4. [Dynamic iFrames](#dynamic-iframes)
-5. [iFrame Navigation](#iframe-navigation)
-6. [Common Patterns](#common-patterns)
-
-## Basic iFrame Access
-
-### Using frameLocator
-
-```typescript
-// Access iframe by selector
-const frame = page.frameLocator("iframe#payment");
-await frame.getByRole("button", { name: "Pay" }).click();
-
-// Access by name attribute
-const namedFrame = page.frameLocator('iframe[name="checkout"]');
-await namedFrame.getByLabel("Card number").fill("4242424242424242");
-
-// Access by title
-const titledFrame = page.frameLocator('iframe[title="Payment Form"]');
-
-// Access by src (partial match)
-const srcFrame = page.frameLocator('iframe[src*="stripe.com"]');
-```
-
-### Frame vs FrameLocator
-
-```typescript
-// frameLocator - for locator-based operations (recommended)
-const frameLocator = page.frameLocator("#my-iframe");
-await frameLocator.getByRole("button").click();
-
-// frame() - for Frame object operations (navigation, evaluation)
-const frame = page.frame({ name: "my-frame" });
-if (frame) {
-  await frame.goto("https://example.com");
-  const title = await frame.title();
-}
-
-// Get all frames
-const frames = page.frames();
-for (const f of frames) {
-  console.log("Frame URL:", f.url());
-}
-```
-
-### Waiting for iFrame Content
-
-```typescript
-// Wait for iframe to load
-const frame = page.frameLocator("#dynamic-iframe");
-
-// Wait for element inside iframe
-await expect(frame.getByRole("heading")).toBeVisible({ timeout: 10000 });
-
-// Wait for iframe src to change
-await page.waitForFunction(() => {
-  const iframe = document.querySelector("iframe#my-frame") as HTMLIFrameElement;
-  return iframe?.src.includes("loaded");
-});
-```
-
-## Cross-Origin iFrames
-
-### Accessing Cross-Origin Content
-
-```typescript
-// Cross-origin iframes work seamlessly with frameLocator
-const thirdPartyFrame = page.frameLocator('iframe[src*="third-party.com"]');
-
-// Interact with elements inside cross-origin iframe
-await thirdPartyFrame.getByRole("textbox").fill("test@example.com");
-await thirdPartyFrame.getByRole("button", { name: "Submit" }).click();
-
-// Wait for cross-origin iframe to be ready
-await expect(thirdPartyFrame.locator("body")).toBeVisible();
-```
-
-### Payment Provider iFrames (Stripe, PayPal)
-
-```typescript
-test("Stripe payment iframe", async ({ page }) => {
-  await page.goto("/checkout");
-
-  // Stripe uses multiple iframes for each field
-  const cardFrame = page
-    .frameLocator('iframe[name*="__privateStripeFrame"]')
-    .first();
-
-  // Wait for Stripe to initialize
-  await expect(cardFrame.locator('[placeholder="Card number"]')).toBeVisible({
-    timeout: 15000,
-  });
-
-  // Fill card details
-  await cardFrame
-    .locator('[placeholder="Card number"]')
-    .fill("4242424242424242");
-  await cardFrame.locator('[placeholder="MM / YY"]').fill("12/30");
-  await cardFrame.locator('[placeholder="CVC"]').fill("123");
-});
-```
-
-### Handling OAuth in iFrames
-
-```typescript
-test("OAuth iframe flow", async ({ page }) => {
-  await page.goto("/login");
-  await page.getByRole("button", { name: "Sign in with Google" }).click();
-
-  // If OAuth opens in iframe instead of popup
-  const oauthFrame = page.frameLocator('iframe[src*="accounts.google.com"]');
-
-  // Wait for OAuth form
-  await expect(oauthFrame.getByLabel("Email")).toBeVisible({ timeout: 10000 });
-  await oauthFrame.getByLabel("Email").fill("test@gmail.com");
-});
-```
-
-## Nested iFrames
-
-### Accessing Nested Frames
-
-```typescript
-// Parent iframe contains child iframe
-const parentFrame = page.frameLocator("#outer-frame");
-const childFrame = parentFrame.frameLocator("#inner-frame");
-
-// Interact with deeply nested content
-await childFrame.getByRole("button", { name: "Submit" }).click();
-
-// Multiple levels of nesting
-const level1 = page.frameLocator("#level1");
-const level2 = level1.frameLocator("#level2");
-const level3 = level2.frameLocator("#level3");
-await level3.getByText("Deep content").click();
-```
-
-### Finding Elements Across Frame Hierarchy
-
-```typescript
-// Helper to search all frames for an element
-async function findInAnyFrame(
-  page: Page,
-  selector: string,
-): Promise<Locator | null> {
-  // Check main page first
-  const mainCount = await page.locator(selector).count();
-  if (mainCount > 0) return page.locator(selector);
-
-  // Check all frames
-  for (const frame of page.frames()) {
-    const count = await frame.locator(selector).count();
-    if (count > 0) {
-      return frame.locator(selector);
-    }
-  }
-  return null;
-}
-
-test("find element in any frame", async ({ page }) => {
-  await page.goto("/complex-page");
-  const element = await findInAnyFrame(page, '[data-testid="submit-btn"]');
-  if (element) await element.click();
-});
-```
-
-## Dynamic iFrames
-
-### iFrames Created at Runtime
-
-```typescript
-test("handle dynamically created iframe", async ({ page }) => {
-  await page.goto("/dashboard");
-
-  // Click button that creates iframe
-  await page.getByRole("button", { name: "Open Widget" }).click();
-
-  // Wait for iframe to appear in DOM
-  await page.waitForSelector("iframe#widget-frame");
-
-  // Now access the frame
-  const widgetFrame = page.frameLocator("#widget-frame");
-  await expect(widgetFrame.getByText("Widget Loaded")).toBeVisible();
-});
-```
-
-### iFrames with Changing src
-
-```typescript
-test("iframe src changes", async ({ page }) => {
-  await page.goto("/multi-step");
-
-  const frame = page.frameLocator("#step-frame");
-
-  // Step 1
-  await expect(frame.getByText("Step 1")).toBeVisible();
-  await frame.getByRole("button", { name: "Next" }).click();
-
-  // Wait for iframe to reload with new content
-  await expect(frame.getByText("Step 2")).toBeVisible({ timeout: 10000 });
-  await frame.getByRole("button", { name: "Next" }).click();
-
-  // Step 3
-  await expect(frame.getByText("Step 3")).toBeVisible({ timeout: 10000 });
-});
-```
-
-### Lazy-Loaded iFrames
-
-```typescript
-test("lazy loaded iframe", async ({ page }) => {
-  await page.goto("/page-with-lazy-iframe");
-
-  // Scroll to trigger lazy load
-  await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
-
-  // Wait for iframe to load
-  const lazyFrame = page.frameLocator("#lazy-iframe");
-  await expect(lazyFrame.locator("body")).not.toBeEmpty({ timeout: 15000 });
-
-  // Interact with content
-  await lazyFrame.getByRole("button").click();
-});
-```
-
-## iFrame Navigation
-
-### Navigating Within iFrame
-
-```typescript
-test("iframe internal navigation", async ({ page }) => {
-  await page.goto("/app");
-
-  // Get frame object for navigation control
-  const frame = page.frame({ name: "content-frame" });
-  if (!frame) throw new Error("Frame not found");
-
-  // Navigate within iframe
-  await frame.goto("https://embedded-app.com/page2");
-
-  // Wait for navigation
-  await frame.waitForURL("**/page2");
-
-  // Verify content
-  await expect(frame.getByRole("heading")).toHaveText("Page 2");
-});
-```
-
-### Handling Frame Navigation Events
-
-```typescript
-test("track iframe navigation", async ({ page }) => {
-  const navigations: string[] = [];
-
-  // Listen to frame navigation
-  page.on("framenavigated", (frame) => {
-    if (frame.parentFrame()) {
-      // This is an iframe navigation
-      navigations.push(frame.url());
-    }
-  });
-
-  await page.goto("/with-iframe");
-  await page
-    .frameLocator("#nav-frame")
-    .getByRole("link", { name: "Page 2" })
-    .click();
-
-  // Verify navigation occurred
-  expect(navigations.some((url) => url.includes("page2"))).toBe(true);
-});
-```
-
-## Common Patterns
-
-### iFrame Fixture
-
-```typescript
-// fixtures.ts
-import { test as base, FrameLocator } from "@playwright/test";
-
-export const test = base.extend<{ paymentFrame: FrameLocator }>({
-  paymentFrame: async ({ page }, use) => {
-    await page.goto("/checkout");
-
-    // Wait for payment iframe to be ready
-    const frame = page.frameLocator('iframe[src*="payment"]');
-    await expect(frame.locator("body")).toBeVisible({ timeout: 15000 });
-
-    await use(frame);
-  },
-});
-
-// test file
-test("complete payment", async ({ paymentFrame }) => {
-  await paymentFrame.getByLabel("Card").fill("4242424242424242");
-  await paymentFrame.getByRole("button", { name: "Pay" }).click();
-});
-```
-
-### Debugging iFrame Issues
-
-```typescript
-test("debug iframe content", async ({ page }) => {
-  await page.goto("/page-with-iframes");
-
-  // List all frames
-  console.log("All frames:");
-  for (const frame of page.frames()) {
-    console.log(`  - ${frame.name() || "(unnamed)"}: ${frame.url()}`);
-  }
-
-  // Screenshot specific iframe content
-  const frame = page.frame({ name: "target-frame" });
-  if (frame) {
-    const body = frame.locator("body");
-    await body.screenshot({ path: "iframe-content.png" });
-  }
-
-  // Get iframe HTML for debugging
-  const frameContent = page.frameLocator("#my-frame");
-  const html = await frameContent.locator("body").innerHTML();
-  console.log("iFrame HTML:", html.substring(0, 500));
-});
-```
-
-### Handling iFrame Load Failures
-
-```typescript
-test("handle iframe load failure", async ({ page }) => {
-  await page.goto("/page-with-unreliable-iframe");
-
-  const frame = page.frameLocator("#unreliable-frame");
-
-  try {
-    // Try to interact with iframe content
-    await expect(frame.getByRole("button")).toBeVisible({ timeout: 5000 });
-    await frame.getByRole("button").click();
-  } catch (error) {
-    // Fallback: refresh iframe
-    await page.evaluate(() => {
-      const iframe = document.querySelector(
-        "#unreliable-frame",
-      ) as HTMLIFrameElement;
-      if (iframe) iframe.src = iframe.src;
-    });
-
-    // Retry
-    await expect(frame.getByRole("button")).toBeVisible({ timeout: 10000 });
-    await frame.getByRole("button").click();
-  }
-});
-```
-
-### Mocking iFrame Content
-
-```typescript
-test("mock iframe response", async ({ page }) => {
-  // Intercept iframe src request
-  await page.route("**/embedded-widget**", (route) => {
-    route.fulfill({
-      contentType: "text/html",
-      body: `
-        <!DOCTYPE html>
-        <html>
-          <body>
-            <h1>Mocked Widget</h1>
-            <button>Mocked Button</button>
-          </body>
-        </html>
-      `,
-    });
-  });
-
-  await page.goto("/page-with-widget");
-
-  const frame = page.frameLocator("#widget-frame");
-  await expect(frame.getByRole("heading")).toHaveText("Mocked Widget");
-});
-```
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern                          | Problem                           | Solution                                           |
-| ------------------------------------- | --------------------------------- | -------------------------------------------------- |
-| Using `page.frame()` for interactions | Less reliable than frameLocator   | Use `page.frameLocator()` for element interactions |
-| Hardcoding iframe index               | Fragile if DOM order changes      | Use name, id, or src attribute selectors           |
-| Not waiting for iframe load           | Race conditions                   | Wait for element inside iframe to be visible       |
-| Assuming same-origin                  | Cross-origin has different timing | Always wait for iframe content explicitly          |
-| Ignoring nested iframes               | Element not found                 | Chain frameLocator calls for nested frames         |
-
-## Related References
-
-- **Locators**: See [locators.md](../core/locators.md) for selector strategies
-- **Third-party services**: See [third-party.md](../advanced/third-party.md) for payment iframe patterns
-- **Debugging**: See [debugging.md](../debugging/debugging.md) for troubleshooting iframe issues