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