microsoft/openvmm
Publicmirrored from https://github.com/microsoft/openvmmAvailable
Guide/src/dev_guide/tests/unit.md
83lines · modecode
| 1 | # Unit Tests |
| 2 | |
| 3 | > Note: We recommend using [cargo-nextest](https://nexte.st/) to run unit / VMM |
| 4 | > tests. It is a significant improvement over the built-in `cargo test` runner, |
| 5 | > and is the test runner we use in all our CI pipelines. |
| 6 | > |
| 7 | > You can install it locally by running: |
| 8 | > |
| 9 | > ```bash |
| 10 | > cargo install cargo-nextest --locked |
| 11 | > ``` |
| 12 | > |
| 13 | > See the [cargo-nextest](https://nexte.st/) documentation for more info. |
| 14 | |
| 15 | |
| 16 | Unit tests test individual functions or components without pulling in lots of |
| 17 | ambient infrastructure. In Rust, these are usually written in the same file as |
| 18 | the product code--this ensures that the test has access to any internal methods |
| 19 | or state it requires, and it makes it easier to ensure that tests and code are |
| 20 | updated at the same time. |
| 21 | |
| 22 | A typical module with unit tests might look something like this: |
| 23 | |
| 24 | ```rust |
| 25 | fn add_5(n: u32) -> u32 { |
| 26 | n + 5 |
| 27 | } |
| 28 | |
| 29 | #[cfg(test)] |
| 30 | mod tests { |
| 31 | #[test] |
| 32 | fn test_add_5() { |
| 33 | assert_eq!(add_5(3), 8); |
| 34 | } |
| 35 | } |
| 36 | ``` |
| 37 | |
| 38 | In the OpenVMM repo, all the unit tests are run on every pull request, on an |
| 39 | arbitrary build machine. As a result of this approach, it's important that unit |
| 40 | tests: |
| 41 | |
| 42 | - run quickly |
| 43 | - do not affect the state of the machine that runs them |
| 44 | - do not take a dependency on machine configuration |
| 45 | - e.g: no root/administrator access or virtualization requirement |
| 46 | |
| 47 | We may loosen these guidelines over time if it becomes necessary. You can also |
| 48 | mark tests with `#[ignore]` if they do not meet these guidelines but are useful |
| 49 | for manual testing. |
| 50 | |
| 51 | See the [unit testing section](https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html) |
| 52 | in "Rust by example" for more details. |
| 53 | |
| 54 | ## Doc tests |
| 55 | |
| 56 | Rust has another type of unit tests known as doc tests. These are unit tests |
| 57 | that are written in the API documentation comments of public functions. They |
| 58 | will be run automatically along with the unit tests, so the same guidelines |
| 59 | apply. |
| 60 | |
| 61 | When do you choose a doc test over a unit test? |
| 62 | |
| 63 | Doc tests can only access public functionality, and they are intended to |
| 64 | document the usage of a function or method, not to exhaustively check every |
| 65 | case. So write doc tests primarily as examples for other developers, and rely on |
| 66 | unit tests for your main coverage. |
| 67 | |
| 68 | An example might look like this: |
| 69 | |
| 70 | ```rust |
| 71 | /// Adds 5 to `n`. |
| 72 | /// |
| 73 | /// ``` |
| 74 | /// assert_eq!(mycrate::add_5(3), 8); |
| 75 | /// ``` |
| 76 | pub fn add_5(n: u32) -> u32 { |
| 77 | n + 5 |
| 78 | } |
| 79 | ``` |
| 80 | |
| 81 | See the [documentation testing |
| 82 | section](https://doc.rust-lang.org/rust-by-example/testing/doc_testing.html) in |
| 83 | Rust by example for more info. |