vitest-dev/vitest · error · Error

Method "getByAltText" is not supported by the

Error message

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

What it means

page.getByAltText is a locator method available only with a full browser provider. The default page stub throws, interpolating the active provider name. Images/inputs with alt text are queried via provider-specific selector engines that preview does not implement.

Solutions

Configure test.browser.provider to 'playwright' or 'webdriverio'.
Under preview, query with CSS: document.querySelector('[alt="logo"]').
Register the method via page.extend if you author a custom provider.

Example fix

// before
const logo = page.getByAltText('logo')
// after (preview provider)
const logo = document.querySelector('img[alt="logo"]')!

Defensive patterns

Strategy: validation

Validate before calling

if (getBrowserState().provider === 'preview') {
  document.querySelector('[alt="logo"]')
} else {
  page.getByAltText('logo')
}

Type guard

function supportsLocators(): boolean {
  return ['playwright', 'webdriverio'].includes(getBrowserState().provider ?? '')
}

Prevention

Use a full provider for alt-text-based location.
Map getByAltText to [alt="..."] under preview.
Document provider capabilities for contributors.

When it happens

Trigger: Calling page.getByAltText('logo') while provider is 'preview' or any provider that did not register the method.

Common situations: Accessibility-focused tests copied from Playwright/RTL docs; default provider config; missing provider registration in a custom provider.

Related errors

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/2295b9141bf448aa. Report an issue: GitHub.

Appendix: 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 1fa9837ec2)