Merge pull request #946 from fitzgen/guide-testing-wasm-pack

guide: clarify testing docs; prefer `wasm-pack`-based workflows

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

@@ -2,7 +2,7 @@
 
 ## Configure Your Test Crate
 
-Add this to the root of your test crate, e.g. `$MY_CRATE/tests/wasm.rs`:
+Add this to the root of your test crate, e.g. `$MY_CRATE/tests/web.rs`:
 
 ```rust
 use wasm_bindgen_test::wasm_bindgen_test_configure;
@@ -10,12 +10,57 @@ use wasm_bindgen_test::wasm_bindgen_test_configure;
 wasm_bindgen_test_configure!(run_in_browser);
 ```
 
+Note that although a particular test crate must target either headless browsers
+or Node.js, you can have test suites for both Node.js and browsers for your
+project by using multiple test crates. For example:
+
+```
+$MY_CRATE/
+`-- tests
+    |-- node.rs    # The tests in this suite use the default Node.js.
+    `-- web.rs     # The tests in this suite are configured for browsers.
+```
+
 ## Configuring Which Browser is Used
 
-> ⚡ If you are using `wasm-pack`, skip this step! Instead, use `wasm-pack test
+To control which browser is used for headless testing, use the appropriate flag
-> --chrome`, `wasm-pack test --firefox`, or `wasm-pack test --safari`.
+with `wasm-pack test`:
-> `wasm-pack` will automatically download and configure the appropriate
+
-> WebDriver client for you.
+* `wasm-pack test --chrome` — Run the tests in Chrome. This machine must
+  have Chrome installed.
+
+* `wasm-pack test --firefox` — Run the tests in Firefox. This machine must
+  have Firefox installed.
+
+* `wasm-pack test --safari` — Run the tests in Safari. This machine must
+  have Safari installed.
+
+If multiple browser flags are passed, the tests will be run under each browser.
+
+## Running the Tests in the Headless Browser
+
+Once the tests are configured to run in a headless browser, just run `wasm-pack
+test` with the appropriate browser flags and `--headless`:
+
+```bash
+wasm-pack test --headless --chrome --firefox --safari
+```
+
+### Debugging Headless Browser Tests
+
+Omitting the `--headless` flag will disable headless mode, and allow you to
+debug failing tests in your browser's devtools.
+
+--------------------------------------------------------------------------------
+
+## Appendix: Testing in headless browsers without `wasm-pack`
+
+**⚠️ The recommended way to use `wasm-bindgen-test` is with `wasm-pack`, since it
+will handle installing the test runner, installing a WebDriver client for your
+browser, and informing `cargo` how to use the custom test runner.** However, you
+can also manage those tasks yourself, if you wish.
+
+### 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
@@ -47,23 +92,17 @@ WebDriver.
 This is installed by default on Mac OS. It should be able to find your Safari
 installation by default.
 
-## Running the Tests in the Headless Browser
+### Running the Tests in the Headless Browser
 
-Once the tests are configured to run in a headless browser, executing the tests
+Once the tests are configured to run in a headless browser and the appropriate
-is the same:
+environment variables are set, executing the tests for headless browsers is the
+same as executing them for Node.js:
 
 ```bash
 cargo test --target wasm32-unknown-unknown
-
-# or, if you're using wasm-pack
-wasm-pack test --headless --chrome --firefox --safari
 ```
 
-### Debugging Headless Browser Tests
+#### Debugging Headless Browser Tests
-
-> If you're using `wasm-pack`, omitting the `--headless` flag will disable
-> headless mode, and allow you to debug failing tests in your browser's
-> devtools.
 
 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

guide/src/wasm-bindgen-test/usage.md

@@ -1,31 +1,6 @@
 # Using `wasm-bindgen-test`
 
-## Install the Test Runner
+### Add `wasm-bindgen-test` to Your `Cargo.toml`'s `[dev-dependencies]`
-
-> ⚡ If you are using `wasm-pack`, skip this step! `wasm-pack test` will
-> automatically ensure that the right version of the test runner is installed.
-
-The test runner comes along with the main `wasm-bindgen` CLI tool. Make sure to
-replace "X.Y.Z" with the same version of `wasm-bindgen` that you already have in
-`Cargo.toml`!
-
-```shell
-cargo install wasm-bindgen-cli --vers "X.Y.Z"
-```
-
-## Configure `.cargo/config` to use the Test Runner
-
-> ⚡ If you are using `wasm-pack`, skip this step! `wasm-pack test` will
-> automatically configure `cargo test` to use the `wasm-bindgen` test runner.
-
-Add this to `$MY_CRATE/.cargo/config`:
-
-```toml
-[target.wasm32-unknown-unknown]
-runner = 'wasm-bindgen-test-runner'
-```
-
-## Add `wasm-bindgen-test` to Your `Cargo.toml`'s `[dev-dependencies]`
 
 Make sure to replace "X.Y.Z" with the same version of `wasm-bindgen` that you
 have in the `[dependencies]` section!
@@ -62,15 +37,12 @@ within a `pub mod`. Putting them inside a private module will not work.
 
 ## Execute Your Tests
 
-> ⚡ If you are using `wasm-pack`, run `wasm-pack test` instead! For more
+Run the tests with `wasm-pack test`. By default, the tests are generated to
-> details, run `wasm-pack test --help`.
+target Node.js, but you can [configure tests to run inside headless
-
+browsers](./browsers.html) as well.
-Run the tests by specifying the `wasm32-unknown-unknown` target when running
-`cargo test`. By default, the tests are run in Node.js, but you can [configure
-tests to run inside headless browsers](./browsers.html) as well.
 
 ```shell
-$ cargo test --target wasm32-unknown-unknown
+$ wasm-pack test --node
     Finished dev [unoptimized + debuginfo] target(s) in 0.11s
      Running /home/.../target/wasm32-unknown-unknown/debug/deps/wasm-4a309ffe6ad80503.wasm
 running 2 tests
@@ -108,3 +80,43 @@ test result: FAILED. 1 passed; 1 failed; 0 ignored
 
 error: test failed, to rerun pass '--test wasm'
 ```
+
+That's it!
+
+--------------------------------------------------------------------------------
+
+## Appendix: Using `wasm-bindgn-test` without `wasm-pack`
+
+**⚠️ The recommended way to use `wasm-bindgen-test` is with `wasm-pack`, since it
+will handle installing the test runner, installing a WebDriver client for your
+browser, and informing `cargo` how to use the custom test runner.** However, you
+can also manage those tasks yourself, if you wish.
+
+In addition to the steps above, you must also do the following.
+
+### Install the Test Runner
+
+The test runner comes along with the main `wasm-bindgen` CLI tool. Make sure to
+replace "X.Y.Z" with the same version of `wasm-bindgen` that you already have in
+`Cargo.toml`!
+
+```shell
+cargo install wasm-bindgen-cli --vers "X.Y.Z"
+```
+
+### Configure `.cargo/config` to use the Test Runner
+
+Add this to `$MY_CRATE/.cargo/config`:
+
+```toml
+[target.wasm32-unknown-unknown]
+runner = 'wasm-bindgen-test-runner'
+```
+
+### Run the Tests
+
+Run the tests by passing `--target wasm32-unknown-unknown` to `cargo test`:
+
+```
+cargo test --target wasm32-unknown-unknown
+```