rustwasm/wasm-bindgen
1
0
Fork 0
mirror of https://github.com/rustwasm/wasm-bindgen.git synced 2024-11-24 06:33:33 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Nick Fitzgerald 2018-10-09 09:31:01 -07:00
parent 1410b5253d
commit 8d195d07ee
2 changed files with 100 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
guide/src/wasm-bindgen-test/browsers.md
View File

@ -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

78
guide/src/wasm-bindgen-test/usage.md
View File

@ -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
```