Multiple Setups

Since Vitest 3, you can specify several different browser setups using the new browser.instances option.

The main advantage of using the browser.instances over the test projects is improved caching. Every project will use the same Vite server meaning the file transform and dependency pre-bundling has to happen only once.

Several Browsers

You can use the browser.instances field to specify options for different browsers. For example, if you want to run the same tests in different browsers, the minimal configuration will look like this:

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      headless: true,
      instances: [
        { browser: 'chromium' },
        { browser: 'firefox' },
        { browser: 'webkit' },
      ],
    },
  },
});

Different Setups

You can also specify different config options independently from the browser (although, the instances can also have browser fields):

vitest.config.ts

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      headless: true,
      instances: [
        {
          browser: 'chromium',
          name: 'chromium-1',
          setupFiles: ['./ratio-setup.ts'],
          provide: {
            ratio: 1,
          },
        },
        {
          browser: 'chromium',
          name: 'chromium-2',
          provide: {
            ratio: 2,
          },
        },
      ],
    },
  },
});

example.test.ts

import { expect, inject, test } from 'vitest';
import { globalSetupModifier } from './example.js';

test('ratio works', () => {
  expect(inject('ratio') * globalSetupModifier).toBe(14);
});

In this example Vitest will run all tests in chromium browser, but execute a './ratio-setup.ts' file only in the first configuration and inject a different ratio value depending on the provide field.

WARNING

Note that you need to define the custom name value if you are using the same browser name because Vitest will assign the browser as the project name otherwise.

Filtering

You can filter what projects to run with the --project flag. Vitest will automatically assign the browser name as a project name if it is not assigned manually. If the root config already has a name, Vitest will merge them: custom -> custom (browser).

$ vitest --project=chromium

default

export default defineConfig({
  test: {
    browser: {
      instances: [
        // name: chromium
        { browser: 'chromium' },
        // name: custom
        { browser: 'firefox', name: 'custom' },
      ]
    }
  }
})

custom

export default defineConfig({
  test: {
    name: 'custom',
    browser: {
      instances: [
        // name: custom (chromium)
        { browser: 'chromium' },
        // name: manual
        { browser: 'firefox', name: 'manual' },
      ]
    }
  }
})

WARNING

Vitest cannot run multiple instances that have headless mode set to false (the default behaviour). During development, you can select what project to run in your terminal:

? Found multiple projects that run browser tests in headed mode: "chromium", "firefox".
Vitest cannot run multiple headed browsers at the same time. Select a single project
to run or cancel and run tests with "headless: true" option. Note that you can also
start tests with --browser=name or --project=name flag. › - Use arrow-keys. Return to submit.
❯   chromium
    firefox

If you have several non-headless projects in CI (i.e. the headless: false is set manually in the config and not overridden in CI env), Vitest will fail the run and won't start any tests.

The ability to run tests in headless mode is not affected by this. You can still run all instances in parallel as long as they don't have headless: false.