guide: Add documentation for testing with wasm-bindgen-test

2025-06-27 03:31:35 +00:00 · 2018-09-12 13:14:39 -07:00
parent fd75280ef5
commit e2e815a477
7 changed files with 313 additions and 163 deletions
--- a/guide/src/wasm-bindgen-test/usage.md
+++ b/guide/src/wasm-bindgen-test/usage.md
@ -0,0 +1,110 @@
+# 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]`
+
+Make sure to replace "X.Y.Z" with the same version of `wasm-bindgen` that you
+have in the `[dependencies]` section!
+
+```toml
+[dev-dependencies]
+wasm-bindgen-test = "X.Y.Z"
+```
+
+## Write Some Tests
+
+Create a `$MY_CRATE/tests/wasm.rs` file:
+
+```rust
+extern crate wasm_bindgen_test;
+use wasm_bindgen_test::*;
+
+#[wasm_bindgen_test]
+fn pass() {
+    assert_eq!(1, 1);
+}
+
+#[wasm_bindgen_test]
+fn fail() {
+    assert_eq!(1, 2);
+}
+```
+
+Writing tests is the same as normal Rust `#[test]`s, except we are using the
+`#[wasm_bindgen_test]` attribute.
+
+One other difference is that the tests **must** be in the root of the crate, or
+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.
+
+```shell
+$ cargo test --target wasm32-unknown-unknown
+    Finished dev [unoptimized + debuginfo] target(s) in 0.11s
+     Running /home/.../target/wasm32-unknown-unknown/debug/deps/wasm-4a309ffe6ad80503.wasm
+running 2 tests
+
+test wasm::pass ... ok
+test wasm::fail ... FAILED
+
+failures:
+
+---- wasm::fail output ----
+    error output:
+        panicked at 'assertion failed: `(left == right)`
+          left: `1`,
+         right: `2`', crates/test/tests/wasm.rs:14:5
+
+    JS exception that was thrown:
+        RuntimeError: unreachable
+            at __rust_start_panic (wasm-function[1362]:33)
+            at rust_panic (wasm-function[1357]:30)
+            at std::panicking::rust_panic_with_hook::h56e5e464b0e7fc22 (wasm-function[1352]:444)
+            at std::panicking::continue_panic_fmt::had70ba48785b9a8f (wasm-function[1350]:122)
+            at std::panicking::begin_panic_fmt::h991e7d1ca9bf9c0c (wasm-function[1351]:95)
+            at wasm::fail::ha4c23c69dfa0eea9 (wasm-function[88]:477)
+            at core::ops::function::FnOnce::call_once::h633718dad359559a (wasm-function[21]:22)
+            at wasm_bindgen_test::__rt::Context::execute::h2f669104986475eb (wasm-function[13]:291)
+            at __wbg_test_fail_1 (wasm-function[87]:57)
+            at module.exports.__wbg_apply_2ba774592c5223a7 (/home/alex/code/wasm-bindgen/target/wasm32-unknown-unknown/wbg-tmp/wasm-4a309ffe6ad80503.js:61:66)
+
+
+failures:
+
+    wasm::fail
+
+test result: FAILED. 1 passed; 1 failed; 0 ignored
+
+error: test failed, to rerun pass '--test wasm'
+```