feat(browser): add commands to communicate betweens server and the browser

[sheremet-va]

Description

Fixes #4918

This PR adds a @vitest/browser/context module that you can import commands and other utilities from. By default, Vitest provides these commands based on Web Test Runner:

function readFile(path: string, options?: BufferEncoding | FsOptions): Promise<string>
function writeFile(path: string, content: string, options?: BufferEncoding | FsOptions & { mode?: number | string }): Promise<void>
function removeFile(path: string): Promise<void>
function sendKeys(payload: SendKeysPayload): Promise<void>

The @vitest/browser/context module also exposes other variables:

export const server: {
  /**
   * Platform the Vitest server is running on.
   * The same as calling `process.platform` on the server.
   */
  platform: Platform
  /**
   * The name of the current browser provide.
   */
  provider: string
  /**
   * Runtime version of the Vitest server.
   * The same as calling `process.version` on the server.
   */
  version: string
  /**
   * Available commands for the browser.
   * @see {@link https://vitest.dev/guide/browser#commands}
   */
  commands: BrowserCommands
}

/**
 * Available commands for the browser.
 * A shortcut to `server.commands`.
 * @see {@link https://vitest.dev/guide/browser#commands}
 */
export const commands: BrowserCommands

export const page: {
  /**
   * Serialized test config.
   */
  config: ResolvedConfig
}

Example of using a built-in command:

import { commands } from '@vitest/browser/context'
import { test } from 'vitest'

test('keys are sent', async () => {
  await commands.sendKeys({ press: 'Tab' })
})

Note

All fs related operations require the file to be inside the root. This option is controlled by server.fs

You can add your own commands by adding them to browser.commands option:

export default defineConfig({
  test: {
    browser: {
      commands: {
        myCustomCommand({ provider }, arg1, arg2) {
          console.log('myCustomCommand called', arg1, arg2)
          return { someValue: true } // serialized and returned
        }
      }
    }
  }
})

Using inside a test:

import { commands } from '@vitest/browser/context'
import { test, expect } from 'vitest'

test('keys are sent', async () => {
  const result = await commands.myCustomCommand('test1', 'test2')
  expect(result).toEqual({ someValue: true })
})

declare module '@vitest/browser/context' {
  interface BrowserCommands {
    myCustomCommand: (arg1: string, arg2: string) => Promise<{ someValue: true }>
  }
}

TODO:

• Tests
• Docs

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
• Ideally, include a test that fails without this PR but passes with it.
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.

Tests

• Run the tests with pnpm test:ci.

Documentation

• If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

• Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

[netlify]

✅ Deploy Preview for fastidious-cascaron-4ded94 canceled.

Name	Link
🔨 Latest commit	015216e
🔍 Latest deploy log	https://app.netlify.com/sites/fastidious-cascaron-4ded94/deploys/65bb7776927f060008569e2e

[omridevk]

Oh crap this is cool! big like 🚀

[manzt]

it seems like all file paths are resolved relative to each test file for writeFile and readFile commands. Is it possible to have the paths resolve to the root of the project instead?

[sheremet-va]

it seems like all file paths are resolved relative to each test file for writeFile and readFile commands. Is it possible to have the paths resolve to the root of the project instead?

It is a documented behaviour. If you have feature requests, open a new issue. Comments to one year old PRs are not a good place to discuss this.