You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Run Vitest tests in a browser. If the browser name is not specified, Vitest will try to determine your default browser automatically. We use [WebdriverIO](https://webdriver.io/) for running tests by default, but it can be configured with [browser.provider](/config/#browser-provider) option.
1005
+
1006
+
::: tip NOTE
1007
+
Read more about testing in a real browser in the [guide page](/guide/browser).
1008
+
:::
1009
+
1010
+
::: warning
1011
+
This is an experimental feature. Breaking changes might not follow semver, please pin Vitest's version when using it.
1012
+
:::
1013
+
1014
+
#### browser.enabled
1015
+
1016
+
-**Type:**`boolean`
1017
+
-**Default:**`false`
1018
+
-**CLI:**`--browser`, `--browser.enabled=false`
1019
+
1020
+
Run all tests inside a browser by default. Can be overriden with [`poolMatchGlobs`](/config/#poolmatchglobs) option.
1021
+
1022
+
#### browser.name
1023
+
1024
+
-**Type:**`string`
1025
+
-**Default:**_tries to find default browser automatically_
1026
+
-**CLI:**`--browser=safari`
1027
+
1028
+
Run all tests in a specific browser. If not specified, tries to find a browser automatically.
This page provides information about the experimental browser mode feature in the Vitest API, which allows you to run your tests in the browser natively, providing access to browser globals like window and document. This feature is currently under development, and APIs may change in the future.
8
+
9
+
## Configuration
10
+
11
+
To activate browser mode in your Vitest configuration, you can use the `--browser` flag or set the `browser.enabled` field to `true` in your Vitest configuration file. Here is an example configuration using the browser field:
12
+
13
+
```ts
14
+
exportdefaultdefineConfig({
15
+
test: {
16
+
browser: {
17
+
enabled: true
18
+
},
19
+
}
20
+
})
21
+
```
22
+
23
+
## Browser Option Types:
24
+
25
+
The browser option in Vitest can be set to either a boolean or a string type. If set to `true`, Vitest will try to automatically find your default browser. You can also specify a browser by providing its name as a `string`. The available browser options are:
26
+
-`firefox`
27
+
-`chrome`
28
+
-`edge`
29
+
-`safari`
30
+
31
+
Here's an example configuration setting chrome as the browser option:
32
+
33
+
```ts
34
+
exportdefaultdefineConfig({
35
+
test: {
36
+
browser: {
37
+
enabled: true,
38
+
name: 'chrome',
39
+
},
40
+
}
41
+
})
42
+
```
43
+
44
+
## Cross-browser Testing:
45
+
46
+
When you specify a browser name in the browser option, Vitest will try to run the specified browser using [WebdriverIO](https://webdriver.io/) by default, and then run the tests there. This feature makes cross-browser testing easy to use and configure in environments like a CI. If you don't want to use WebdriverIO, you can configure the custom browser provider by using `browser.provider` option.
47
+
48
+
To specify a browser using the CLI, use the `--browser` flag followed by the browser name, like this:
49
+
50
+
```sh
51
+
npx vitest --browser=chrome
52
+
```
53
+
54
+
Or if you pass down several options, you dot-syntax:
When using the Safari browser option, the `safaridriver` needs to be activated by running `sudo safaridriver --enable` on your device.
62
+
63
+
Additionally, when running your tests, Vitest will attempt to install some drivers for compatibility with `safaridriver`.
64
+
:::
65
+
66
+
## Headless
67
+
68
+
Headless mode is another option available in the browser mode. In headless mode, the browser runs in the background without a user interface, which makes it useful for running automated tests. The headless option in Vitest can be set to a boolean value to enable or disable headless mode.
69
+
70
+
Here's an example configuration enabling headless mode:
71
+
72
+
```ts
73
+
exportdefaultdefineConfig({
74
+
test: {
75
+
browser: {
76
+
enabled: true,
77
+
headless: true,
78
+
},
79
+
}
80
+
})
81
+
```
82
+
83
+
You can also set headless mode using the `--browser.headless` flag in the CLI, like this:
0 commit comments