test: Add documentation about configuring headless browser testing

crates/test/README.md

@@ -1,4 +1,4 @@
-# wasm-bindgen-test
+# `wasm-bindgen-test`
 
 This crate is an experimental test harness for `wasm32-unknown-unknown`, with
 the goal of allowing you to write tests as you normally do in Rust and then
@@ -131,6 +131,53 @@ error, and otherwise the test will fail.
 
 This support is currently powered by the `wasm-bindgen-futures` crate.
 
+## Running Tests in Headless Browsers
+
+Add this to the root of your test crate:
+
+```rust
+wasm_bindgen_test_configure!(run_in_browser);
+```
+
+### Configuring Which Browser is Used
+
+If one of the following environment variables is set, then the corresponding
+WebDriver and browser will be used. If none of these environment variables are
+set, then the `$PATH` is searched for a suitable WebDriver implementation.
+
+#### `GECKODRIVER=path/to/geckodriver`
+
+Use Firefox for headless browser testing, and `geckodriver` as its
+WebDriver.
+
+The `firefox` binary must be on your `$PATH`.
+
+[Get `geckodriver` here](https://github.com/mozilla/geckodriver/releases)
+
+#### `CHROMEDRIVER=path/to/chromedriver`
+
+Use Chrome for headless browser testing, and `chromedriver` as its
+WebDriver.
+
+The `chrome` binary must be on your `$PATH`.
+
+[Get `chromedriver` here](http://chromedriver.chromium.org/downloads)
+
+#### `SAFARIDRIVER=path/to/safaridriver`
+
+Use Safari for headless browser testing, and `safaridriver` as its
+WebDriver.
+
+This is installed by default on Mac OS. It should be able to find your Safari
+installation by default.
+
+### Debugging Headless Browser Tests
+
+Set the `NO_HEADLESS=1` environment variable and the browser tests will not run
+headless. Instead, the tests will start a local server that you can visit in
+your Web browser of choices, and headless testing should not be used. You can
+then use your browser's devtools to debug.
+
 ## Components
 
 The test harness is made of three separate components, but you typically don't