1# Testing
2
3This section describes how to run Wasmtime's tests and add new tests.
4
5Before continuing, make sure you can [build
6Wasmtime](./contributing-building.html) successfully. Can't run the tests if you
7can't build it!
8
9## Running All Tests
10
11To run all of Wasmtime's tests, execute this command:
12
13```shell
14cargo test --all
15```
16
17You can also exclude a particular crate from testing with `--exclude`. For
18example, if you want to avoid testing the `wastime-fuzzing` crate — which
19requires that `libclang` is installed on your system, and for some reason maybe
20you don't have it — you can run:
21
22```shell
23cargo test --all --exclude wasmtime-fuzzing
24```
25
26## Testing a Specific Crate
27
28You can test a particular Wasmtime crate with `cargo test -p
29wasmtime-whatever`. For example, to test the `wasmtime-environ` crate, execute
30this command:
31
32```shell
33cargo test -p wasmtime-environ
34```
35
36Alternatively, you can `cd` into the crate's directory, and run `cargo test`
37there, without needing to supply the `-p` flag:
38
39```shell
40cd crates/environ/
41cargo test
42```
43
44## Running the Wasm Spec Tests
45
46The spec testsuite itself is in a git submodule, so make sure you've
47checked it out and initialized its submodule:
48
49```shell
50git submodule update --init
51```
52
53When the submodule is checked out, Wasmtime runs the Wasm spec testsuite as part
54of testing the `wasmtime-cli` crate:
55
56```shell
57cargo test -p wasmtime-cli
58```
59
60## Adding New Tests
61
62### Adding Rust's `#[test]`-Style Tests
63
64For very "unit-y" tests, we add `test` modules in the same `.rs` file as the
65code that is being tested. These `test` modules are configured to only get
66compiled during testing with `#[cfg(test)]`.
67
68```rust
69// some code...
70
71#[cfg(test)]
72mod tests {
73    use super::*;
74
75    #[test]
76    fn some_test_for_that_code() {
77        // ...
78    }
79}
80```
81
82If you're writing a unit test and a `test` module doesn't already exist, you can
83create one.
84
85For more "integration-y" tests, we create a `tests` directory within the crate,
86and put the tests inside there. For example, there are various code
87cache-related tests at `crates/environ/tests/cache_*.rs`. Always feel free to
88add a `tests` directory to a crate, if you want to add a new test and there
89aren't any existing tests.
90
91### Adding Specification-Style Wast Tests
92
93We use the spec testsuite as-is and without custom patches or a forked
94version. This probably isn't what you want to modify when adding a new Wasmtime
95test!
96
97When you have a Wasmtime-specific test that you'd like to write in Wast and use
98the Wast-style assertions, you can add it to our "misc testsuite". The misc
99testsuite uses the same syntax and assertions as the spec testsuite, but lives
100in `tests/misc_testsuite`. Feel free to add new tests to existing
101`tests/misc_testsuite/*.wast` files or create new ones as needed. These tests
102are run as part of the `wasmtime-cli` crate's tests.
103
104If you have a new test that you think really belongs in the spec testsuite, make
105sure it makes sense for every Wasm implementation to run your test (i.e. it
106isn't Wasmtime-specific) and send a pull request
107[upstream](https://github.com/WebAssembly/testsuite/). Once it is accepted in
108the upstream repo, we can update our git submodule and we'll start running the
109new tests.
110