From 8d195d07ee1d1e8b612266e11cf58b448375c8d9 Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Tue, 9 Oct 2018 09:31:01 -0700 Subject: [PATCH] guide: clarify testing docs; prefer `wasm-pack`-based workflows --- guide/src/wasm-bindgen-test/browsers.md | 71 +++++++++++++++++----- guide/src/wasm-bindgen-test/usage.md | 78 ++++++++++++++----------- 2 files changed, 100 insertions(+), 49 deletions(-) diff --git a/guide/src/wasm-bindgen-test/browsers.md b/guide/src/wasm-bindgen-test/browsers.md index cf947956..c9115ad8 100644 --- a/guide/src/wasm-bindgen-test/browsers.md +++ b/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 -> --chrome`, `wasm-pack test --firefox`, or `wasm-pack test --safari`. -> `wasm-pack` will automatically download and configure the appropriate -> WebDriver client for you. +To control which browser is used for headless testing, use the appropriate flag +with `wasm-pack test`: + +* `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 -is the same: +Once the tests are configured to run in a headless browser and the appropriate +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 - -> 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. +#### 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 diff --git a/guide/src/wasm-bindgen-test/usage.md b/guide/src/wasm-bindgen-test/usage.md index 837ea7de..c510ebfd 100644 --- a/guide/src/wasm-bindgen-test/usage.md +++ b/guide/src/wasm-bindgen-test/usage.md @@ -1,31 +1,6 @@ # Using `wasm-bindgen-test` -## Install the Test Runner - -> ⚡ 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]` +### 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 -> details, run `wasm-pack test --help`. - -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. +Run the tests with `wasm-pack test`. By default, the tests are generated to +target 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 +```