3 Crosvm runs on a variety of platforms with a significant amount of platform-specific code. Testing
6 ## Types of tests
8 ### Unit Tests
10 Unit tests are your standard rust tests embedded with the rest of the code in `src/` and wrapped in
13 Unit tests **cannot make any guarantees on the runtime environment**. Avoid doing the following in
14 unit tests:
16 - Avoid kernel features such as io_uring or userfaultfd, which may not be available on all kernels.
17 - Avoid functionality that requires privileges (e.g. CAP_NET_ADMIN)
18 - Avoid spawning threads or processes
19 - Avoid accessing kernel devices
20 - Avoid global state in unit tests
22 This allows us to execute unit tests for any platform using emulators such as qemu-user-static or
25 #### File Access in Unit Tests  argument
27 Some unit tests may need to access extra data files. The files should be accessed at build time
34 These approaches ensure that units tests be able to find the correct paths in various build &
51 ### Documentation tests  argument
54 [documentation tests](https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.htm…
57 Documentation tests are slow and not run as part of the usual workflows, but can be run locally
64 ### Integration tests  argument
67 [integration testing](https://doc.rust-lang.org/rust-by-example/testing/integration_testing.html).
68 Integration tests are written just like unit tests, but live in a separate directory at `tests/`.
70 Integration tests **guarantee that the test has privileged access to the test environment**. They
71 are only executed when a device-under-test (DUT) is specified when running tests:
74 ./tools/run_tests --dut=vm|host
77 ### End To End (E2E) tests  argument
79 End to end tests live in the `e2e_tests` crate. The crate provides a framework to boot a guest with
82 E2E tests are executed just like integration tests. By giving
83 [nextest's filter expressions](https://nexte.st/book/filter-expressions), you can run a subset of
84 the tests.
87 # Run all e2e tests
88 ./tools/run_tests --dut=vm --filter-expr 'package(e2e_tests)'
89 # Run e2e tests whose name contains the string 'boot'.
90 ./tools/run_tests --dut=vm --filter-expr 'package(e2e_tests) and test(boot)'
93 ### Downstream Product tests  argument
99 Upstream crosvm is not involved in these tests and they are not executed in crosvm CI.
103 Crosvm tests are executed in parallel, each test case in its own process via
106 This requires tests to be cautious about global state, especially integration tests which interact
110 [file-based locking](https://docs.rs/named-lock/latest/named_lock) to prevent access by other test
115 The platforms below can all be tested using `tools/run_tests -p $platform`. The table indicates how
116 these tests are executed:
118 | Platform                    | Build |         Unit Tests         | Integration Tests | E2E Tests |
119 | :-------------------------- | :---: | :------------------------: | :---------------: | :-------: |
121 | aarch64 (linux)             |  ✅   | ✅ (qemu-user[^qemu-user]) | ✅ (qemu[^qemu])  |    ❌     |
122 | armhf (linux)               |  ✅   | ✅ (qemu-user[^qemu-user]) |        ❌         |    ❌     |
130 Here are some tips for developing or/and debugging crosvm tests.
134 When you run a test on a VM with `./tools/run_tests --dut=vm`, if the test fails, you'll see
143 crosvm@testvm-x8664:~$ journalctl -f
150 $ ./tools/run_tests --dut=vm --filter-expr 'package(e2e_tests) and test(boot)'
155 [^qemu-user]: qemu-aarch64-static or qemu-arm-static translate instructions into x86 and executes t…
156     host kernel. This works well for unit tests, but will fail when interacting with platform
160     emulation, which causes tests to be slow. Also not all aarch64 features are properly emulated,
161     which prevents us from running e2e tests.
163 [^windows]: Windows builds of crosvm are a work in progress. Some tests are executed via wine64 on …