What is the difference between frame and frameLocator?

The Answer

`frameLocator` is a Playwright locator that scopes element queries inside an iframe — it's lazy and re-queries on every action. `frame` (via `page.frame()`) returns a `Frame` object — an eager reference to an iframe that can go stale.

Deep Dive Explanation

The key difference: `frameLocator` is a locator — it participates in auto-waiting and strict mode. `frame` is an eager handle that becomes invalid if the iframe navigates or is replaced. For modern tests, always use `frameLocator`.

example.spec.ts

// frameLocator - PREFERRED (lazy, works with auto-waiting)
const frameLocator = page.frameLocator('iframe#chat');
await frameLocator.getByRole('textbox').fill('Hello');

// frame() - LEGACY (eager, can be stale)
const frame = page.frame('chat-frame'); // by name attribute
if (frame) {
  await frame.fill('#message-input', 'Hello'); // Can fail if frame reloads
}

// frame by URL pattern
const paymentFrame = page.frame({ url: /payment/ });

// Get all frames
const frames = page.frames();
frames.forEach(f => console.log(f.url()));