vitest-dev/vitest · error · Error

Invalid command name "${name}". Only alphanumeric characters

Error message

Invalid command name "${name}". Only alphanumeric characters, $ and _ are allowed.

What it means

`ProjectBrowser.registerCommand` validates the command name with `/^[a-z_$][\w$]*$/i` (a valid JS identifier). Because commands are exposed in the generated context module as object keys called like functions, hyphens, dots, spaces, or leading digits break the generated code — so registration is rejected up front.

Source

Thrown at packages/browser/src/node/project.ts:71

    }
    this.testerFilepath = testerHtmlPath
    this.testerHtml = readFile(
      this.testerFilepath,
      'utf8',
    ).then(html => (this.testerHtml = html))
  }

  private commands = {} as Record<string, BrowserCommand<any, any>>

  public registerCommand<K extends keyof BrowserCommands>(
    name: K,
    cb: BrowserCommand<
      Parameters<BrowserCommands[K]>,
      ReturnType<BrowserCommands[K]>
    >,
  ): void {
    if (!/^[a-z_$][\w$]*$/i.test(name)) {
      throw new Error(
        `Invalid command name "${name}". Only alphanumeric characters, $ and _ are allowed.`,
      )
    }
    this.commands[name] = cb
  }

  public triggerCommand = (<K extends keyof BrowserCommand>(
    name: K,
    context: BrowserCommandContext,
    ...args: Parameters<BrowserCommands[K]>
  ): ReturnType<BrowserCommands[K]> => {
    if (name in this.commands) {
      return this.commands[name](context, ...args)
    }
    if (name in this.parent.commands) {
      return this.parent.commands[name](context, ...args)
    }
    throw new Error(`Provider ${this.provider.name} does not support command "${name}".`)

View on GitHub (pinned to d568f8ce37)

Solutions

1. Rename the command to a valid identifier — camelCase or snake_case: `'myCommand'` or `'my_command'`.
2. If the name comes from `browser.commands` config keys, change them in the config (also see error 68).
3. Add a unit test for custom commands to catch invalid names before runtime.

Example fix

// before
project.browser.registerCommand('upload-file', fn)

// after
project.browser.registerCommand('uploadFile', fn)

function isValidCommandName(name: string): boolean {
  return /^[a-z_$][\w$]*$/i.test(name)
}

const isValidCommandName = (name: string): name is string =>
  /^[a-z_$][\w$]*$/i.test(name)

When it happens

Trigger: Calling `project.browser.registerCommand('my-command', fn)` or `registerCommand('123name', fn)` with a name that isn't a valid identifier.

Common situations: User-defined commands registered via `browser.commands` in config with kebab-case keys; programmatic registration from a plugin using a dotted or dashed name.

Related errors

• `resolveOptions` has to be used in a test file
• Invalid command name "${command}". Only alphanumeric charact
• Cannot compare screenshots without a test path
• Provider ${this.provider.name} does not support command "${n
• Commands are only available for browser tests.

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