vitest-dev/vitest · error · Error

Commands are only available for browser tests.

Error message

Commands are only available for browser tests.

What it means

The wdioSwitchContext RPC reads project.browser!.provider and requires it to be defined before checking the provider name. If the project is not a browser project or the provider was not initialized, the non-null assertion on browser is followed by an undefined provider, and the code throws this generic 'Commands are only available for browser tests' message rather than crashing on a deeper call.

Solutions

1. Ensure the command is invoked against a project that has a browser instance with an initialized provider.
2. Guard the call site by checking project.browser?.provider is defined first.
3. Avoid issuing context-switch commands after the test run finishes.

Example fix

// before
await rpc.wdioSwitchContext('iframe') // project has no provider
// after
if (project.browser?.provider) await rpc.wdioSwitchContext('iframe')

function browserProviderReady(browser?: { provider?: unknown }): boolean {
  return !!browser?.provider
}

function isBrowserProject(project: unknown): project is { browser: { provider: { name: string } } } {
  return !!project && typeof project === 'object' && !!(project as any).browser?.provider
}

When it happens

Trigger: Calling the wdioSwitchContext RPC from a project that has no browser instance, or whose provider has not yet been initialized; calling it during teardown after the provider was cleared.

Common situations: Mixing node and browser projects and routing a context-switch command to a node project; invoking the RPC before the browser provider initialized; a stale connection sending commands after the run ended.

Related errors

• Switch context is only available for WebDriverIO provider.
• All browser instances within a project must use the same…
• browser is not initialized
• Browser Mode requires the "provider" to always be specified.
• Browser Mode was enabled, but provider was not specified…

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

Appendix: source

Thrown at packages/browser/src/node/rpc.ts:329

          }
          return result?.map
        },
        cancelCurrentRun(reason) {
          vitest.cancelCurrentRun(reason)
        },
        async resolveId(id, importer) {
          return mockResolver.resolveId(id, importer)
        },
        debug(...args) {
          vitest.logger.console.debug(...args)
        },
        getCountOfFailedTests() {
          return vitest.state.getCountOfFailedTests()
        },
        async wdioSwitchContext(direction) {
          const provider = project.browser!.provider
          if (!provider) {
            throw new Error('Commands are only available for browser tests.')
          }
          if (provider.name !== 'webdriverio') {
            throw new Error('Switch context is only available for WebDriverIO provider.')
          }
          if (direction === 'iframe') {
            await (provider as any).switchToTestFrame()
          }
          else {
            await (provider as any).switchToMainFrame()
          }
        },
        async triggerCommand(sessionId, command, testPath, payload) {
          debug?.('[%s] Triggering command "%s"', sessionId, command)
          const provider = project.browser!.provider
          if (!provider) {
            throw new Error('Commands are only available for browser tests.')
          }
          const context = Object.assign(

View on GitHub (pinned to 1fa9837ec2)