| 1 |
# Using `wasm-bindgen-test` |
| 2 |
|
| 3 |
### Add `wasm-bindgen-test` to Your `Cargo.toml`'s `[dev-dependencies]` |
| 4 |
|
| 5 |
```toml |
| 6 |
[dev-dependencies] |
| 7 |
wasm-bindgen-test = "0.3.0" |
| 8 |
``` |
| 9 |
|
| 10 |
Note that the `0.3.0` track of `wasm-bindgen-test` supports Rust 1.39.0+, which |
| 11 |
is currently the nightly channel (as of 2019-09-05). If you want support for |
| 12 |
older compilers use the `0.2.*` track of `wasm-bindgen-test`. |
| 13 |
|
| 14 |
## Write Some Tests |
| 15 |
|
| 16 |
Create a `$MY_CRATE/tests/wasm.rs` file: |
| 17 |
|
| 18 |
```rust |
| 19 |
use wasm_bindgen_test::*; |
| 20 |
|
| 21 |
#[wasm_bindgen_test] |
| 22 |
fn pass() { |
| 23 |
assert_eq!(1, 1); |
| 24 |
} |
| 25 |
|
| 26 |
#[wasm_bindgen_test] |
| 27 |
fn fail() { |
| 28 |
assert_eq!(1, 2); |
| 29 |
} |
| 30 |
``` |
| 31 |
|
| 32 |
Writing tests is the same as normal Rust `#[test]`s, except we are using the |
| 33 |
`#[wasm_bindgen_test]` attribute. |
| 34 |
|
| 35 |
One other difference is that the tests **must** be in the root of the crate, or |
| 36 |
within a `pub mod`. Putting them inside a private module will not work. |
| 37 |
|
| 38 |
## Execute Your Tests |
| 39 |
|
| 40 |
Run the tests with `wasm-pack test`. By default, the tests are generated to |
| 41 |
target Node.js, but you can [configure tests to run inside headless |
| 42 |
browsers](./browsers.html) as well. |
| 43 |
|
| 44 |
```shell |
| 45 |
$ wasm-pack test --node |
| 46 |
Finished dev [unoptimized + debuginfo] target(s) in 0.11s |
| 47 |
Running /home/.../target/wasm32-unknown-unknown/debug/deps/wasm-4a309ffe6ad80503.wasm |
| 48 |
running 2 tests |
| 49 |
|
| 50 |
test wasm::pass ... ok |
| 51 |
test wasm::fail ... FAILED |
| 52 |
|
| 53 |
failures: |
| 54 |
|
| 55 |
---- wasm::fail output ---- |
| 56 |
error output: |
| 57 |
panicked at 'assertion failed: `(left == right)` |
| 58 |
left: `1`, |
| 59 |
right: `2`', crates/test/tests/wasm.rs:14:5 |
| 60 |
|
| 61 |
JS exception that was thrown: |
| 62 |
RuntimeError: unreachable |
| 63 |
at __rust_start_panic (wasm-function[1362]:33) |
| 64 |
at rust_panic (wasm-function[1357]:30) |
| 65 |
at std::panicking::rust_panic_with_hook::h56e5e464b0e7fc22 (wasm-function[1352]:444) |
| 66 |
at std::panicking::continue_panic_fmt::had70ba48785b9a8f (wasm-function[1350]:122) |
| 67 |
at std::panicking::begin_panic_fmt::h991e7d1ca9bf9c0c (wasm-function[1351]:95) |
| 68 |
at wasm::fail::ha4c23c69dfa0eea9 (wasm-function[88]:477) |
| 69 |
at core::ops::function::FnOnce::call_once::h633718dad359559a (wasm-function[21]:22) |
| 70 |
at wasm_bindgen_test::__rt::Context::execute::h2f669104986475eb (wasm-function[13]:291) |
| 71 |
at __wbg_test_fail_1 (wasm-function[87]:57) |
| 72 |
at module.exports.__wbg_apply_2ba774592c5223a7 (/home/alex/code/wasm-bindgen/target/wasm32-unknown-unknown/wbg-tmp/wasm-4a309ffe6ad80503.js:61:66) |
| 73 |
|
| 74 |
|
| 75 |
failures: |
| 76 |
|
| 77 |
wasm::fail |
| 78 |
|
| 79 |
test result: FAILED. 1 passed; 1 failed; 0 ignored |
| 80 |
|
| 81 |
error: test failed, to rerun pass '--test wasm' |
| 82 |
``` |
| 83 |
|
| 84 |
That's it! |
| 85 |
|
| 86 |
-------------------------------------------------------------------------------- |
| 87 |
|
| 88 |
## Appendix: Using `wasm-bindgen-test` without `wasm-pack` |
| 89 |
|
| 90 |
**⚠️ The recommended way to use `wasm-bindgen-test` is with `wasm-pack`, since it |
| 91 |
will handle installing the test runner, installing a WebDriver client for your |
| 92 |
browser, and informing `cargo` how to use the custom test runner.** However, you |
| 93 |
can also manage those tasks yourself, if you wish. |
| 94 |
|
| 95 |
In addition to the steps above, you must also do the following. |
| 96 |
|
| 97 |
### Install the Test Runner |
| 98 |
|
| 99 |
The test runner comes along with the main `wasm-bindgen` CLI tool. Make sure to |
| 100 |
replace "X.Y.Z" with the same version of `wasm-bindgen` that you already have in |
| 101 |
`Cargo.toml`! |
| 102 |
|
| 103 |
```shell |
| 104 |
cargo install wasm-bindgen-cli --vers "X.Y.Z" |
| 105 |
``` |
| 106 |
|
| 107 |
### Configure `.cargo/config` to use the Test Runner |
| 108 |
|
| 109 |
Add this to `$MY_CRATE/.cargo/config`: |
| 110 |
|
| 111 |
```toml |
| 112 |
[target.wasm32-unknown-unknown] |
| 113 |
runner = 'wasm-bindgen-test-runner' |
| 114 |
``` |
| 115 |
|
| 116 |
### Run the Tests |
| 117 |
|
| 118 |
Run the tests by passing `--target wasm32-unknown-unknown` to `cargo test`: |
| 119 |
|
| 120 |
``` |
| 121 |
cargo test --target wasm32-unknown-unknown |
| 122 |
``` |