Skip to content

Commit 606cb9e

Browse files
sheremet-vasheremet-va
authored
feat(browser)!: require a provider factory instead of a string (#8445)
1 parent 9a0274c commit 606cb9e

File tree

87 files changed

+780
-827
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+780
-827
lines changed

‎docs/guide/browser/config.md

Lines changed: 62 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,13 @@ You can change the browser configuration by updating the `test.browser` field in
44

55
```ts [vitest.config.ts]
66
import { defineConfig } from 'vitest/config'
7+
import { playwright } from '@vitest/browser/providers/playwright'
78

89
export default defineConfig({
910
test: {
1011
browser: {
1112
enabled: true,
12-
provider: 'playwright',
13+
provider: playwright(),
1314
instances: [
1415
{
1516
browser: 'chromium',
@@ -53,15 +54,6 @@ Defines multiple browser setups. Every config has to have at least a `browser` f
5354
- [Configuring Playwright](/guide/browser/playwright)
5455
- [Configuring WebdriverIO](/guide/browser/webdriverio)
5556

56-
::: tip
57-
To have a better type safety when using built-in providers, you should reference one of these types (for provider that you are using) in your [config file](/config/):
58-
59-
```ts
60-
/// <reference types="@vitest/browser/providers/playwright" />
61-
/// <reference types="@vitest/browser/providers/webdriverio" />
62-
```
63-
:::
64-
6557
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`.
6658

6759
::: warning
@@ -100,26 +92,12 @@ List of available `browser` options:
10092
- [`browser.testerHtmlPath`](#browser-testerhtmlpath)
10193
- [`browser.screenshotDirectory`](#browser-screenshotdirectory)
10294
- [`browser.screenshotFailures`](#browser-screenshotfailures)
95+
- [`browser.provider`](#browser-provider)
10396

10497
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.
10598

10699
Under the hood, Vitest transforms these instances into separate [test projects](/advanced/api/test-project) sharing a single Vite server for better caching performance.
107100

108-
## browser&#46;name <Badge type="danger">deprecated</Badge> {#browser-name}
109-
110-
- **Type:** `string`
111-
- **CLI:** `--browser=safari`
112-
113-
::: danger DEPRECATED
114-
This API is deprecated an will be removed in Vitest 4. Please, use [`browser.instances`](#browser-instances) option instead.
115-
:::
116-
117-
Run all tests in a specific browser. Possible options in different providers:
118-
119-
- `webdriverio`: `firefox`, `chrome`, `edge`, `safari`
120-
- `playwright`: `firefox`, `webkit`, `chromium`
121-
- custom: any string that will be passed to the provider
122-
123101
## browser.headless
124102

125103
- **Type:** `boolean`
@@ -150,70 +128,86 @@ A path to the HTML entry point. Can be relative to the root of the project. This
150128

151129
Configure options for Vite server that serves code in the browser. Does not affect [`test.api`](#api) option. By default, Vitest assigns port `63315` to avoid conflicts with the development server, allowing you to run both in parallel.
152130

153-
## browser.provider {#browser-provider}
131+
## browser.provider <Badge type="danger">advanced</Badge> {#browser-provider}
154132

155-
- **Type:** `'webdriverio' | 'playwright' | 'preview' | string`
133+
- **Type:** `BrowserProviderOption`
156134
- **Default:** `'preview'`
157135
- **CLI:** `--browser.provider=playwright`
158136

159-
Path to a provider that will be used when running browser tests. Vitest provides three providers which are `preview` (default), `webdriverio` and `playwright`. Custom providers should be exported using `default` export and have this shape:
137+
The return value of the provider factory. You can import the factory from `@vitest/browser/providers/<provider-name>` or make your own provider:
160138

161-
```ts
162-
export interface BrowserProvider {
163-
name: string
164-
supportsParallelism: boolean
165-
getSupportedBrowsers: () => readonly string[]
166-
beforeCommand?: (command: string, args: unknown[]) => Awaitable<void>
167-
afterCommand?: (command: string, args: unknown[]) => Awaitable<void>
168-
getCommandsContext: (sessionId: string) => Record<string, unknown>
169-
openPage: (sessionId: string, url: string, beforeNavigate?: () => Promise<void>) => Promise<void>
170-
getCDPSession?: (sessionId: string) => Promise<CDPSession>
171-
close: () => Awaitable<void>
172-
initialize(
173-
ctx: TestProject,
174-
options: BrowserProviderInitializationOptions
175-
): Awaitable<void>
176-
}
177-
```
139+
```ts{8-10}
140+
import { playwright } from '@vitest/browser/providers/playwright'
141+
import { webdriverio } from '@vitest/browser/providers/webdriverio'
142+
import { preview } from '@vitest/browser/providers/preview'
178143
179-
::: danger ADVANCED API
180-
The custom provider API is highly experimental and can change between patches. If you just need to run tests in a browser, use the [`browser.instances`](#browser-instances) option instead.
181-
:::
182-
183-
## browser.providerOptions <Badge type="danger">deprecated</Badge> {#browser-provideroptions}
184-
185-
- **Type:** `BrowserProviderOptions`
186-
187-
::: danger DEPRECATED
188-
This API is deprecated an will be removed in Vitest 4. Please, use [`browser.instances`](#browser-instances) option instead.
189-
:::
144+
export default defineConfig({
145+
test: {
146+
browser: {
147+
provider: playwright(),
148+
provider: webdriverio(),
149+
provider: preview(), // default
150+
},
151+
},
152+
})
153+
```
190154

191-
Options that will be passed down to provider when calling `provider.initialize`.
155+
To configure how provider initializes the browser, you can pass down options to the factory function:
192156

193-
```ts
194-
import { defineConfig } from 'vitest/config'
157+
```ts{7-15,22-27}
158+
import { playwright } from '@vitest/browser/providers/playwright'
195159
196160
export default defineConfig({
197161
test: {
198162
browser: {
199-
providerOptions: {
200-
launch: {
201-
devtools: true,
163+
// shared provider options between all instances
164+
provider: playwright({
165+
launchOptions: {
166+
slowMo: 50,
167+
channel: 'chrome-beta',
202168
},
203-
},
169+
actionTimeout: 5_000,
170+
}),
171+
instances: [
172+
{ browser: 'chromium' },
173+
{
174+
browser: 'firefox',
175+
// overriding options only for a single instance
176+
// this will NOT merge options with the parent one
177+
provider: playwright({
178+
launchOptions: {
179+
firefoxUserPrefs: {
180+
'browser.startup.homepage': 'https://example.com',
181+
},
182+
},
183+
})
184+
}
185+
],
204186
},
205187
},
206188
})
207189
```
208190

209-
::: tip
210-
To have a better type safety when using built-in providers, you should reference one of these types (for provider that you are using) in your [config file](/config/):
191+
### Custom Provider
192+
193+
::: danger ADVANCED API
194+
The custom provider API is highly experimental and can change between patches. If you just need to run tests in a browser, use the [`browser.instances`](#browser-instances) option instead.
195+
:::
211196

212197
```ts
213-
/// <reference types="@vitest/browser/providers/playwright" />
214-
/// <reference types="@vitest/browser/providers/webdriverio" />
198+
export interface BrowserProvider {
199+
name: string
200+
mocker?: BrowserModuleMocker
201+
/**
202+
* @experimental opt-in into file parallelisation
203+
*/
204+
supportsParallelism: boolean
205+
getCommandsContext: (sessionId: string) => Record<string, unknown>
206+
openPage: (sessionId: string, url: string) => Promise<void>
207+
getCDPSession?: (sessionId: string) => Promise<CDPSession>
208+
close: () => Awaitable<void>
209+
}
215210
```
216-
:::
217211

218212
## browser.ui
219213

‎docs/guide/browser/index.md

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -99,10 +99,12 @@ To activate browser mode in your Vitest configuration, set the `browser.enabled`
9999

100100
```ts [vitest.config.ts]
101101
import { defineConfig } from 'vitest/config'
102+
import { playwright } from '@vitest/browser/providers/playwright'
103+
102104
export default defineConfig({
103105
test: {
104106
browser: {
105-
provider: 'playwright', // or 'webdriverio'
107+
provider: playwright(),
106108
enabled: true,
107109
// at least one instance is required
108110
instances: [
@@ -125,13 +127,14 @@ If you have not used Vite before, make sure you have your framework's plugin ins
125127
```ts [react]
126128
import { defineConfig } from 'vitest/config'
127129
import react from '@vitejs/plugin-react'
130+
import { playwright } from '@vitest/browser/providers/playwright'
128131

129132
export default defineConfig({
130133
plugins: [react()],
131134
test: {
132135
browser: {
133136
enabled: true,
134-
provider: 'playwright',
137+
provider: playwright(),
135138
instances: [
136139
{ browser: 'chromium' },
137140
],
@@ -141,14 +144,15 @@ export default defineConfig({
141144
```
142145
```ts [vue]
143146
import { defineConfig } from 'vitest/config'
147+
import { playwright } from '@vitest/browser/providers/playwright'
144148
import vue from '@vitejs/plugin-vue'
145149

146150
export default defineConfig({
147151
plugins: [vue()],
148152
test: {
149153
browser: {
150154
enabled: true,
151-
provider: 'playwright',
155+
provider: playwright(),
152156
instances: [
153157
{ browser: 'chromium' },
154158
],
@@ -159,13 +163,14 @@ export default defineConfig({
159163
```ts [svelte]
160164
import { defineConfig } from 'vitest/config'
161165
import { svelte } from '@sveltejs/vite-plugin-svelte'
166+
import { playwright } from '@vitest/browser/providers/playwright'
162167

163168
export default defineConfig({
164169
plugins: [svelte()],
165170
test: {
166171
browser: {
167172
enabled: true,
168-
provider: 'playwright',
173+
provider: playwright(),
169174
instances: [
170175
{ browser: 'chromium' },
171176
],
@@ -176,13 +181,14 @@ export default defineConfig({
176181
```ts [solid]
177182
import { defineConfig } from 'vitest/config'
178183
import solidPlugin from 'vite-plugin-solid'
184+
import { playwright } from '@vitest/browser/providers/playwright'
179185

180186
export default defineConfig({
181187
plugins: [solidPlugin()],
182188
test: {
183189
browser: {
184190
enabled: true,
185-
provider: 'playwright',
191+
provider: playwright(),
186192
instances: [
187193
{ browser: 'chromium' },
188194
],
@@ -193,13 +199,14 @@ export default defineConfig({
193199
```ts [marko]
194200
import { defineConfig } from 'vitest/config'
195201
import marko from '@marko/vite'
202+
import { playwright } from '@vitest/browser/providers/playwright'
196203

197204
export default defineConfig({
198205
plugins: [marko()],
199206
test: {
200207
browser: {
201208
enabled: true,
202-
provider: 'playwright',
209+
provider: playwright(),
203210
instances: [
204211
{ browser: 'chromium' },
205212
],
@@ -210,6 +217,7 @@ export default defineConfig({
210217
```ts [qwik]
211218
import { defineConfig } from 'vitest/config'
212219
import { qwikVite } from '@builder.io/qwik/optimizer'
220+
import { playwright } from '@vitest/browser/providers/playwright'
213221

214222
// optional, run the tests in SSR mode
215223
import { testSSR } from 'vitest-browser-qwik/ssr-plugin'
@@ -219,7 +227,7 @@ export default defineConfig({
219227
test: {
220228
browser: {
221229
enabled: true,
222-
provider: 'playwright',
230+
provider: playwright(),
223231
instances: [{ browser: 'chromium' }]
224232
},
225233
},
@@ -370,10 +378,12 @@ Here's an example configuration enabling headless mode:
370378

371379
```ts [vitest.config.ts]
372380
import { defineConfig } from 'vitest/config'
381+
import { playwright } from '@vitest/browser/providers/playwright'
382+
373383
export default defineConfig({
374384
test: {
375385
browser: {
376-
provider: 'playwright',
386+
provider: playwright(),
377387
enabled: true,
378388
headless: true,
379389
},

‎docs/guide/browser/multiple-setups.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,13 @@ You can use the `browser.instances` field to specify options for different brows
1010

1111
```ts [vitest.config.ts]
1212
import { defineConfig } from 'vitest/config'
13+
import { playwright } from '@vitest/browser/providers/playwright'
14+
1315
export default defineConfig({
1416
test: {
1517
browser: {
1618
enabled: true,
17-
provider: 'playwright',
19+
provider: playwright(),
1820
headless: true,
1921
instances: [
2022
{ browser: 'chromium' },
@@ -33,11 +35,13 @@ You can also specify different config options independently from the browser (al
3335
::: code-group
3436
```ts [vitest.config.ts]
3537
import { defineConfig } from 'vitest/config'
38+
import { playwright } from '@vitest/browser/providers/playwright'
39+
3640
export default defineConfig({
3741
test: {
3842
browser: {
3943
enabled: true,
40-
provider: 'playwright',
44+
provider: playwright(),
4145
headless: true,
4246
instances: [
4347
{

0 commit comments

Comments
 (0)