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