vitest-dev/vitest · error · Error

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

Error message

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

What it means

page.getByAltText is a throwing stub (packages/browser/src/client/tester/context.ts:448-449). Alt-text queries are only available on Locator instances (getElementLocatorSelectors wires locator.getByAltText at context.ts:514). Calling the stub on page throws.

Source

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

        [{
          name,
          stack: bodyOrOptions?.stack ?? error?.stack,
        }],
        error,
      )
    })
  },
  getByRole() {
    throw new Error(`Method "getByRole" is not supported by the "${provider}" provider.`)
  },
  getByLabelText() {
    throw new Error(`Method "getByLabelText" is not supported by the "${provider}" provider.`)
  },
  getByTestId() {
    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) {

View on GitHub (pinned to d568f8ce37)

Solutions

Use a Locator: page.elementLocator(document.body).getByAltText('logo').
Register page.getByAltText via browser.locators.extend(...) for a top-level shortcut.

Example fix

// before
const img = page.getByAltText('Company logo')
// after
const img = page.elementLocator(document.body).getByAltText('Company logo')

Defensive patterns

Strategy: type-guard

Validate before calling

const root = page.elementLocator(document.body)
const img = root.getByAltText('Company logo')

Prevention

Resolve alt-text queries through a Locator.
Add a page-level extension only if you have many call sites.

When it happens

Trigger: Calling page.getByAltText('logo') directly on the page object without an extension.

Common situations: Image-heavy tests where developers expect a page-level getByAltText mirroring Playwright.

Related errors

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