vitest-dev/vitest · error · Error

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

Error message

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

What it means

page.elementLocator is a throwing stub (packages/browser/src/client/tester/context.ts:460-461). It is meant to be implemented per provider/locator setup; getElementLocatorSelectors (context.ts:511-512) and convertToLocator (context.ts:474-478) both call page.elementLocator, so it must be wired up before locators work. If no locator provider registered an implementation, calling it throws.

Source

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

    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) {
      (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
}

View on GitHub (pinned to d568f8ce37)

Solutions

  1. Ensure the standard locators module is imported (it registers elementLocator via the provider) — use the default vitest/browser entry, not a stripped custom one.
  2. If using a custom provider, implement elementLocator on page (return a Locator wrapping the element) before any locator calls.
  3. Register via browser.locators.extend or set page.elementLocator explicitly in setup.

Example fix

// before — custom provider never wires elementLocator
const loc = page.elementLocator(document.body)
// after — register the implementation (default providers do this for you)
browser.locators.extend({
  elementLocator: (el: Element) => page.locator(convertElementToCssSelector(el)),
})
Defensive patterns

Strategy: validation

Validate before calling

// Ensure the standard locators module is loaded (default vitest/browser entry).
// If using a custom provider, register elementLocator once during setup:
import { browser, page } from 'vitest/browser'
import { convertElementToCssSelector } from 'vitest/browser'
if (typeof (page as any).elementLocator !== 'function' || (page as any).elementLocator.__stub) {
  browser.locators.extend({
    elementLocator: (el: Element) => page.locator(convertElementToCssSelector(el)),
  })
}

Prevention

When it happens

Trigger: Calling page.elementLocator(element) when the locator provider has not initialized elementLocator (e.g. a custom/minimal provider setup, or calling before locators module has loaded).

Common situations: Custom browser provider that doesn't implement the locator protocol; calling page.elementLocator during very early module init before the locators module (locators.ts) has patched page.

Related errors

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