From 2fcc74e226dd05e1a326f805b55cb6dacbaf354d Mon Sep 17 00:00:00 2001
From: Nick Fitzgerald <fitzgen@gmail.com>
Date: Wed, 8 Aug 2018 15:33:56 -0700
Subject: [PATCH] guide: refactor and update testing instructions for
 contributing

---
 guide/src/SUMMARY.md         |  1 +
 guide/src/contributing.md    | 21 ----------------
 guide/src/testing.md         | 47 ++++++++++++++++++++++++++++++++++++
 guide/src/web-sys/testing.md | 16 ++++--------
 4 files changed, 53 insertions(+), 32 deletions(-)
 create mode 100644 guide/src/testing.md

diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
index 515fb597..3ed08435 100644
--- a/guide/src/SUMMARY.md
+++ b/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)
diff --git a/guide/src/contributing.md b/guide/src/contributing.md
index 62d2f222..b2b0b738 100644
--- a/guide/src/contributing.md
+++ b/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
-```
diff --git a/guide/src/testing.md b/guide/src/testing.md
new file mode 100644
index 00000000..8f4c2974
--- /dev/null
+++ b/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).
diff --git a/guide/src/web-sys/testing.md b/guide/src/web-sys/testing.md
index afa12698..411c2200 100644
--- a/guide/src/web-sys/testing.md
+++ b/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.