Merge pull request #669 from fitzgen/contributing-testing

Contributing testing docs

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
@@ -33,15 +33,15 @@ ton of documentation just yet, but a taste of how it works is:
   # or [target.'cfg(target_arch = "wasm32")'.dev-dependencies]
   wasm-bindgen-test = { git = 'https://github.com/rustwasm/wasm-bindgen' }
   ```
-  
+
   **WARNING**: the `console_error_panic_hook` has a dependency on `wasm-bindgen`
-  from `crates.io` which conflicts with the one from git used by `wasm-bindgen-test`: 
-  it produces linker errors due to duplicated symbols. 
-  
+  from `crates.io` which conflicts with the one from git used by `wasm-bindgen-test`:
+  it produces linker errors due to duplicated symbols.
+
   Until `wasm-bindgen-test` is released on `crates.io`, the temporary workaround
-  is to patch the `crates.io`'s `wasm-bindgen` dependency to be the same that 
+  is to patch the `crates.io`'s `wasm-bindgen` dependency to be the same that
   `wasm-bindgen-test` uses by adding the following to your project's `Cargo.toml`:
-  
+
   ```toml
   [patch.crates-io]
   wasm-bindgen = { git = 'https://github.com/rustwasm/wasm-bindgen' }
@@ -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

guide/src/SUMMARY.md

@@ -37,6 +37,7 @@
 --------------------------------------------------------------------------------
 
 - [Contributing](./contributing.md)
+  - [Testing](./testing.md)
   - [Internal Design](./design.md)
     - [JS Objects in Rust](./design/js-objects-in-rust.md)
     - [Exporting a function to JS](./design/exporting-rust.md)

guide/src/contributing.md

@@ -34,24 +34,3 @@ development.
    ```shell
    yarn
    ```
-
-## Running Tests
-
-Finally, you can run the tests with `cargo`:
-
-```shell
-cargo test
-```
-
-### Headless Browser Tests
-
-Some tests are configured to run in a headless Firefox instance. To run these
-tests, you must have Firefox installed. If you have Firefox installed in a
-non-default, custom location you can set the `WASM_BINDGEN_FIREFOX_BIN_PATH`
-environment variable to the path to your `firefox-bin`.
-
-For example:
-
-```shell
-WASM_BINDGEN_FIREFOX_BIN_PATH=/home/fitzgen/firefox/firefox-bin cargo test
-```

guide/src/testing.md

@@ -0,0 +1,47 @@
+# Running `wasm-bindgen`'s Tests
+
+## Wasm Tests on Node and Headless Browsers
+
+These are the largest test suites, and most common to run in day to day
+`wasm-bindgen` development. These tests are compiled to Wasm and then run in
+Node.js or a headless browser via the WebDriver protocol.
+
+```bash
+cargo test --target wasm32-unknown-unknown
+```
+
+See [the `wasm-bindgen-test` crate's
+`README.md`](https://github.com/rustwasm/wasm-bindgen/blob/master/crates/test/README.md)
+for details and configuring which headless browser is used.
+
+## Sanity Tests for `wasm-bindgen` on the Native Host Target
+
+This small test suite just verifies that exported `wasm-bindgen` methods can
+still be used on the native host's target.
+
+```
+cargo test
+```
+
+## The Web IDL Frontend's Tests
+
+```
+cargo test -p wasm-bindgen-webidl
+```
+
+## The Macro UI Tests
+
+These tests assert that we have reasonable error messages that point to the
+right source spans when the `#[wasm_bindgen]` proc-macro is misused.
+
+```
+cargo test -p ui-tests
+```
+
+## The `js-sys` Tests
+
+See [the `js-sys` testing page](js-sys/testing.html).
+
+## The `web-sys` Tests
+
+See [the `web-sys` testing page](web-sys/testing.html).

guide/src/web-sys/testing.md

@@ -5,17 +5,11 @@ You can test the `web-sys` crate by running `cargo test` within the
 
 ```sh
 cd wasm-bindgen/crates/web-sys
+cargo test
 cargo test --target wasm32-unknown-unknown
 ```
 
-These tests all use a headless browser. See the [*Headless Browser
-Tests* section for details on setup and
-configuration.](../contributing.html#headless-browser-tests)
-
-## Grouping Tests
-
-Because headless tests can have significant setup and tear down overheads, try
-and group tests together. Instead of having a different `#[test]` for every
-method on some interface, have a single `#[test]` for the interface and all of
-its methods. This will keep the test suite running fast, resulting in better
-developer ergonomics and CI turn around times. Thanks!
+The Wasm tests all run within a headless browser. See [the `wasm-bindgen-test`
+crate's
+`README.md`](https://github.com/rustwasm/wasm-bindgen/blob/master/crates/test/README.md)
+for details and configuring which headless browser is used.