Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

browser-apis/iframes.md

View on GitHub
# 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
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall