Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/wasm-bindgen-test/browsers.md

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