feat: introduce separate packages for browser mode providers (#8629)

Author: sheremet-va

docs/.vitepress/config.ts

@@ -253,6 +253,11 @@ export default ({ mode }: { mode: string }) => {
                 link: '/guide/browser/webdriverio',
                 docFooterText: 'Configuring WebdriverIO | Browser Mode',
               },
+              {
+                text: 'Configuring Preview',
+                link: '/guide/browser/preview',
+                docFooterText: 'Configuring Preview | Browser Mode',
+              },
             ],
           },
           {

docs/guide/browser/assertion-api.md

@@ -7,18 +7,18 @@ title: Assertion API | Browser Mode
 Vitest provides a wide range of DOM assertions out of the box forked from [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom) library with the added support for locators and built-in retry-ability.
 
 ::: tip TypeScript Support
-If you are using [TypeScript](/guide/browser/#typescript) or want to have correct type hints in `expect`, make sure you have `@vitest/browser/context` referenced somewhere. If you never imported from there, you can add a `reference` comment in any file that's covered by your `tsconfig.json`:
+If you are using [TypeScript](/guide/browser/#typescript) or want to have correct type hints in `expect`, make sure you have `vitest/browser` referenced somewhere. If you never imported from there, you can add a `reference` comment in any file that's covered by your `tsconfig.json`:
 
 ```ts
-/// <reference types="@vitest/browser/context" />
+/// <reference types="vitest/browser" />
 ```
 :::
 
 Tests in the browser might fail inconsistently due to their asynchronous nature. Because of this, it is important to have a way to guarantee that assertions succeed even if the condition is delayed (by a timeout, network request, or animation, for example). For this purpose, Vitest provides retriable assertions out of the box via the [`expect.poll`](/api/expect#poll) and `expect.element` APIs:
 
 ```ts
 import { expect, test } from 'vitest'
-import { page } from '@vitest/browser/context'
+import { page } from 'vitest/browser'
 
 test('error banner is rendered', async () => {
   triggerError()

docs/guide/browser/commands.md

@@ -20,7 +20,7 @@ This API follows [`server.fs`](https://vitejs.dev/config/server-options.html#ser
 :::
 
 ```ts
-import { server } from '@vitest/browser/context'
+import { server } from 'vitest/browser'
 
 const { readFile, writeFile, removeFile } = server.commands
 
@@ -38,10 +38,10 @@ it('handles files', async () => {
 
 ## CDP Session
 
-Vitest exposes access to raw Chrome Devtools Protocol via the `cdp` method exported from `@vitest/browser/context`. It is mostly useful to library authors to build tools on top of it.
+Vitest exposes access to raw Chrome Devtools Protocol via the `cdp` method exported from `vitest/browser`. It is mostly useful to library authors to build tools on top of it.
 
 ```ts
-import { cdp } from '@vitest/browser/context'
+import { cdp } from 'vitest/browser'
 
 const input = document.createElement('input')
 document.body.appendChild(input)
@@ -97,10 +97,10 @@ export default function BrowserCommands(): Plugin {
 }
 ```
 
-Then you can call it inside your test by importing it from `@vitest/browser/context`:
+Then you can call it inside your test by importing it from `vitest/browser`:
 
 ```ts
-import { commands } from '@vitest/browser/context'
+import { commands } from 'vitest/browser'
 import { expect, test } from 'vitest'
 
 test('custom command works correctly', async () => {
@@ -109,7 +109,7 @@ test('custom command works correctly', async () => {
 })
 
 // if you are using TypeScript, you can augment the module
-declare module '@vitest/browser/context' {
+declare module 'vitest/browser' {
   interface BrowserCommands {
     myCustomCommand: (arg1: string, arg2: string) => Promise<{
       someValue: true

docs/guide/browser/component-testing.md

@@ -138,7 +138,7 @@ The key is using `page.elementLocator()` to bridge Testing Library's DOM output
 ```jsx
 // For Solid.js components
 import { render } from '@testing-library/solid'
-import { page } from '@vitest/browser/context'
+import { page } from 'vitest/browser'
 
 test('Solid component handles user interaction', async () => {
   // Use Testing Library to render the component
@@ -564,7 +564,7 @@ import { render } from 'vitest-browser-react' // [!code ++]
 ### Key Differences
 
 - Use `await expect.element()` instead of `expect()` for DOM assertions
-- Use `@vitest/browser/context` for user interactions instead of `@testing-library/user-event`
+- Use `vitest/browser` for user interactions instead of `@testing-library/user-event`
 - Browser Mode provides real browser environment for accurate testing
 
 ## Learn More

docs/guide/browser/config.md

@@ -4,7 +4,7 @@ You can change the browser configuration by updating the `test.browser` field in
 
 ```ts [vitest.config.ts]
 import { defineConfig } from 'vitest/config'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   test: {
@@ -47,14 +47,11 @@ Run all tests inside a browser by default. Note that `--browser` only works if y
 ## browser.instances
 
 - **Type:** `BrowserConfig`
-- **Default:** `[{ browser: name }]`
-
-Defines multiple browser setups. Every config has to have at least a `browser` field. The config supports your providers configurations:
+- **Default:** `[]`
 
-- [Configuring Playwright](/guide/browser/playwright)
-- [Configuring WebdriverIO](/guide/browser/webdriverio)
+Defines multiple browser setups. Every config has to have at least a `browser` field.
 
-In addition to that, you can also specify most of the [project options](/config/) (not marked with a <NonProjectOption /> icon) and some of the `browser` options like `browser.testerHtmlPath`.
+You can specify most of the [project options](/config/) (not marked with a <NonProjectOption /> icon) and some of the `browser` options like `browser.testerHtmlPath`.
 
 ::: warning
 Every browser config inherits options from the root config:
@@ -79,8 +76,6 @@ export default defineConfig({
 })
 ```
 
-During development, Vitest supports only one [non-headless](#browser-headless) configuration. You can limit the headed project yourself by specifying `headless: false` in the config, or by providing the `--browser.headless=false` flag, or by filtering projects with `--project=chromium` flag.
-
 For more examples, refer to the ["Multiple Setups" guide](/guide/browser/multiple-setups).
 :::
 
@@ -94,8 +89,6 @@ List of available `browser` options:
 - [`browser.screenshotFailures`](#browser-screenshotfailures)
 - [`browser.provider`](#browser-provider)
 
-By default, Vitest creates an array with a single element which uses the [`browser.name`](#browser-name) field as a `browser`. Note that this behaviour will be removed with Vitest 4.
-
 Under the hood, Vitest transforms these instances into separate [test projects](/advanced/api/test-project) sharing a single Vite server for better caching performance.
 
 ## browser.headless
@@ -134,12 +127,12 @@ Configure options for Vite server that serves code in the browser. Does not affe
 - **Default:** `'preview'`
 - **CLI:** `--browser.provider=playwright`
 
-The return value of the provider factory. You can import the factory from `@vitest/browser/providers/<provider-name>` or make your own provider:
+The return value of the provider factory. You can import the factory from `@vitest/browser-<provider-name>` or make your own provider:
 
 ```ts{8-10}
-import { playwright } from '@vitest/browser/providers/playwright'
-import { webdriverio } from '@vitest/browser/providers/webdriverio'
-import { preview } from '@vitest/browser/providers/preview'
+import { playwright } from '@vitest/browser-playwright'
+import { webdriverio } from '@vitest/browser-webdriverio'
+import { preview } from '@vitest/browser-preview'
 
 export default defineConfig({
   test: {
@@ -155,7 +148,7 @@ export default defineConfig({
 To configure how provider initializes the browser, you can pass down options to the factory function:
 
 ```ts{7-13,20-26}
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   test: {
@@ -294,7 +287,7 @@ export interface BrowserScript {
 - **Type:** `Record<string, BrowserCommand>`
 - **Default:** `{ readFile, writeFile, ... }`
 
-Custom [commands](/guide/browser/commands) that can be imported during browser tests from `@vitest/browser/commands`.
+Custom [commands](/guide/browser/commands) that can be imported during browser tests from `vitest/browser`.
 
 ## browser.connectTimeout
 

docs/guide/browser/context.md

@@ -4,7 +4,7 @@ title: Context API | Browser Mode
 
 # Context API
 
-Vitest exposes a context module via `@vitest/browser/context` entry point. As of 2.0, it exposes a small set of utilities that might be useful to you in tests.
+Vitest exposes a context module via `vitest/browser` entry point. As of 2.0, it exposes a small set of utilities that might be useful to you in tests.
 
 ## `userEvent`
 

docs/guide/browser/index.md

@@ -99,7 +99,7 @@ To activate browser mode in your Vitest configuration, set the `browser.enabled`
 
 ```ts [vitest.config.ts]
 import { defineConfig } from 'vitest/config'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   test: {
@@ -127,7 +127,7 @@ If you have not used Vite before, make sure you have your framework's plugin ins
 ```ts [react]
 import { defineConfig } from 'vitest/config'
 import react from '@vitejs/plugin-react'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   plugins: [react()],
@@ -144,7 +144,7 @@ export default defineConfig({
 ```
 ```ts [vue]
 import { defineConfig } from 'vitest/config'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 import vue from '@vitejs/plugin-vue'
 
 export default defineConfig({
@@ -163,7 +163,7 @@ export default defineConfig({
 ```ts [svelte]
 import { defineConfig } from 'vitest/config'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   plugins: [svelte()],
@@ -181,7 +181,7 @@ export default defineConfig({
 ```ts [solid]
 import { defineConfig } from 'vitest/config'
 import solidPlugin from 'vite-plugin-solid'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   plugins: [solidPlugin()],
@@ -199,7 +199,7 @@ export default defineConfig({
 ```ts [marko]
 import { defineConfig } from 'vitest/config'
 import marko from '@marko/vite'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   plugins: [marko()],
@@ -217,7 +217,7 @@ export default defineConfig({
 ```ts [qwik]
 import { defineConfig } from 'vitest/config'
 import { qwikVite } from '@builder.io/qwik/optimizer'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 // optional, run the tests in SSR mode
 import { testSSR } from 'vitest-browser-qwik/ssr-plugin'
@@ -241,7 +241,7 @@ If you need to run some tests using Node-based runner, you can define a [`projec
 
 ```ts [vitest.config.ts]
 import { defineConfig } from 'vitest/config'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   test: {
@@ -338,7 +338,7 @@ Here's an example configuration enabling headless mode:
 
 ```ts [vitest.config.ts]
 import { defineConfig } from 'vitest/config'
-import { playwright } from '@vitest/browser/providers/playwright'
+import { playwright } from '@vitest/browser-playwright'
 
 export default defineConfig({
   test: {
@@ -369,7 +369,7 @@ By default, you don't need any external packages to work with the Browser Mode:
 
 ```js [example.test.js]
 import { expect, test } from 'vitest'
-import { page } from '@vitest/browser/context'
+import { page } from 'vitest/browser'
 import { render } from './my-render-function.js'
 
 test('properly handles form inputs', async () => {
@@ -407,15 +407,15 @@ Besides rendering components and locating elements, you will also need to make a
 
 ```ts
 import { expect } from 'vitest'
-import { page } from '@vitest/browser/context'
+import { page } from 'vitest/browser'
 // element is rendered correctly
 await expect.element(page.getByText('Hello World')).toBeInTheDocument()
 ```
 
-Vitest exposes a [Context API](/guide/browser/context) with a small set of utilities that might be useful to you in tests. For example, if you need to make an interaction, like clicking an element or typing text into an input, you can use `userEvent` from `@vitest/browser/context`. Read more at the [Interactivity API](/guide/browser/interactivity-api).
+Vitest exposes a [Context API](/guide/browser/context) with a small set of utilities that might be useful to you in tests. For example, if you need to make an interaction, like clicking an element or typing text into an input, you can use `userEvent` from `vitest/browser`. Read more at the [Interactivity API](/guide/browser/interactivity-api).
 
 ```ts
-import { page, userEvent } from '@vitest/browser/context'
+import { page, userEvent } from 'vitest/browser'
 await userEvent.fill(page.getByLabelText(/username/i), 'Alice')
 // or just locator.fill
 await page.getByLabelText(/username/i).fill('Alice')
@@ -532,7 +532,7 @@ For unsupported frameworks, we recommend using `testing-library` packages:
 You can also see more examples in [`browser-examples`](https://github.com/vitest-tests/browser-examples) repository.
 
 ::: warning
-`testing-library` provides a package `@testing-library/user-event`. We do not recommend using it directly because it simulates events instead of actually triggering them - instead, use [`userEvent`](/guide/browser/interactivity-api) imported from `@vitest/browser/context` that uses Chrome DevTools Protocol or Webdriver (depending on the provider) under the hood.
+`testing-library` provides a package `@testing-library/user-event`. We do not recommend using it directly because it simulates events instead of actually triggering them - instead, use [`userEvent`](/guide/browser/interactivity-api) imported from `vitest/browser` that uses Chrome DevTools Protocol or Webdriver (depending on the provider) under the hood.
 :::
 
 ::: code-group