vitest-dev/vitest · error · Error

Method "frameLocator" is not supported by the "${provider}"

Error message

Method "frameLocator" is not supported by the "${provider}" provider.

What it means

page.frameLocator is a throwing stub (packages/browser/src/client/tester/context.ts:463-464). Vitest Browser runs each test file inside its own iframe managed by the orchestrator, so cross-iframe locator chaining via a page-level frameLocator is not implemented for the active provider. Calling it throws.

Source

Thrown at packages/browser/src/client/tester/context.ts:464

    throw new Error(`Method "getByTestId" is not supported by the "${provider}" provider.`)
  },
  getByAltText() {
    throw new Error(`Method "getByAltText" is not supported by the "${provider}" provider.`)
  },
  getByPlaceholder() {
    throw new Error(`Method "getByPlaceholder" is not supported by the "${provider}" provider.`)
  },
  getByText() {
    throw new Error(`Method "getByText" is not supported by the "${provider}" provider.`)
  },
  getByTitle() {
    throw new Error(`Method "getByTitle" is not supported by the "${provider}" provider.`)
  },
  elementLocator() {
    throw new Error(`Method "elementLocator" is not supported by the "${provider}" provider.`)
  },
  frameLocator() {
    throw new Error(`Method "frameLocator" is not supported by the "${provider}" provider.`)
  },
  extend(methods) {
    for (const key in methods) {
      (page as any)[key] = (methods as any)[key].bind(page)
    }
    return page
  },
}

function convertToLocator(element: Element | Locator): Locator {
  if (element instanceof Element) {
    return page.elementLocator(element)
  }
  return element
}

function getTaskFullName(task: RunnerTask): string {
  return task.suite ? `${getTaskFullName(task.suite)} ${task.name}` : task.name

View on GitHub (pinned to d568f8ce37)

Solutions

  1. Query the iframe element directly and operate on its contentDocument/contentWindow instead of using a frameLocator.
  2. Restructure the test to load the nested content in the main test iframe (avoid cross-frame interaction).
  3. Use the orchestrator's multi-iframe APIs only if you control both frames; otherwise file a feature request — frameLocator is not supported in the current provider.

Example fix

// before
const btn = page.frameLocator('iframe.widget').getByRole('button')
// after
const iframe = document.querySelector('iframe.widget') as HTMLIFrameElement
const btn = iframe.contentDocument!.querySelector('button')!
Defensive patterns

Strategy: validation

Validate before calling

// frameLocator is unsupported; reach into the iframe element directly.
const iframe = document.querySelector<HTMLIFrameElement>('iframe.widget')
if (iframe?.contentDocument) {
  const btn = iframe.contentDocument.querySelector('button')
  // assert on btn
}

Prevention

When it happens

Trigger: Calling page.frameLocator('iframe#ads') to interact with a nested iframe's content from within a browser test.

Common situations: Porting Playwright page.frameLocator(...) usage into Vitest Browser; tests for widgets rendered in nested iframes (embeds, ads, third-party components).

Related errors

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/ad3838006860c315.json. Report an issue: GitHub.