1# Testing in Headless Browsers
2
3## Configure Your Test Crate
4
5Add this to the root of your test crate, e.g. `$MY_CRATE/tests/web.rs`:
6
7```rust
8use wasm_bindgen_test::wasm_bindgen_test_configure;
9
10wasm_bindgen_test_configure!(run_in_browser);
11```
12
13Note that although a particular test crate must target either headless browsers
14or Node.js, you can have test suites for both Node.js and browsers for your
15project by using multiple test crates. For example:
16
17```
18$MY_CRATE/
19`-- tests
20    |-- node.rs    # The tests in this suite use the default Node.js.
21    `-- web.rs     # The tests in this suite are configured for browsers.
22```
23
24## Configuring Which Browser is Used
25
26To control which browser is used for headless testing, use the appropriate flag
27with `wasm-pack test`:
28
29* `wasm-pack test --chrome` — Run the tests in Chrome. This machine must
30  have Chrome installed.
31
32* `wasm-pack test --firefox` — Run the tests in Firefox. This machine must
33  have Firefox installed.
34
35* `wasm-pack test --safari` — Run the tests in Safari. This machine must
36  have Safari installed.
37
38If multiple browser flags are passed, the tests will be run under each browser.
39
40## Running the Tests in the Headless Browser
41
42Once the tests are configured to run in a headless browser, just run `wasm-pack
43test` with the appropriate browser flags and `--headless`:
44
45```bash
46wasm-pack test --headless --chrome --firefox --safari
47```
48
49## Configuring Headless Browser capabilities
50
51Add the file `webdriver.json` to the root of your crate. Each browser has own
52section for capabilities. For example:
53
54```json
55{
56  "moz:firefoxOptions": {
57    "prefs": {
58      "media.navigator.streams.fake": true,
59      "media.navigator.permission.disabled": true
60    },
61    "args": []
62  },
63  "goog:chromeOptions": {
64    "args": [
65      "--use-fake-device-for-media-stream",
66      "--use-fake-ui-for-media-stream"
67    ]
68  }
69}
70```
71Full list supported capabilities can be found:
72
73* for Chrome - [here](https://peter.sh/experiments/chromium-command-line-switches/)
74* for Firefox - [here](https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions)
75
76Note that the `headless` argument is always enabled for both browsers.
77
78### Debugging Headless Browser Tests
79
80Omitting the `--headless` flag will disable headless mode, and allow you to
81debug failing tests in your browser's devtools.
82
83--------------------------------------------------------------------------------
84
85## Appendix: Testing in headless browsers without `wasm-pack`
86
87**⚠️ The recommended way to use `wasm-bindgen-test` is with `wasm-pack`, since it
88will handle installing the test runner, installing a WebDriver client for your
89browser, and informing `cargo` how to use the custom test runner.** However, you
90can also manage those tasks yourself, if you wish.
91
92### Configuring Which Browser is Used
93
94If one of the following environment variables is set, then the corresponding
95WebDriver and browser will be used. If none of these environment variables are
96set, then the `$PATH` is searched for a suitable WebDriver implementation.
97
98#### `GECKODRIVER=path/to/geckodriver`
99
100Use Firefox for headless browser testing, and `geckodriver` as its
101WebDriver.
102
103The `firefox` binary must be on your `$PATH`.
104
105[Get `geckodriver` here](https://github.com/mozilla/geckodriver/releases)
106
107#### `CHROMEDRIVER=path/to/chromedriver`
108
109Use Chrome for headless browser testing, and `chromedriver` as its
110WebDriver.
111
112The `chrome` binary must be on your `$PATH`.
113
114[Get `chromedriver` here](http://chromedriver.chromium.org/downloads)
115
116#### `SAFARIDRIVER=path/to/safaridriver`
117
118Use Safari for headless browser testing, and `safaridriver` as its
119WebDriver.
120
121This is installed by default on Mac OS. It should be able to find your Safari
122installation by default.
123
124### Running the Tests in the Remote Headless Browser
125
126Tests can be run on a remote webdriver. To do this, the above environment
127variables must be set as URL to the remote webdriver. For example:
128
129```
130CHROMEDRIVER_REMOTE=http://remote.host/
131```
132
133### Running the Tests in the Headless Browser
134
135Once the tests are configured to run in a headless browser and the appropriate
136environment variables are set, executing the tests for headless browsers is the
137same as executing them for Node.js:
138
139```bash
140cargo test --target wasm32-unknown-unknown
141```
142
143#### Debugging Headless Browser Tests
144
145Set the `NO_HEADLESS=1` environment variable and the browser tests will not run
146headless. Instead, the tests will start a local server that you can visit in
147your Web browser of choices, and headless testing should not be used. You can
148then use your browser's devtools to debug.
149