id: move-unit-test title: Move Unit Testing Framework custom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-unit-test/README.md

Summary

This crate defines the core logic for running and reporting Move unit tests. Move unit testing is made up of two main components; a test runner, and a test reporter.

It's important to also note here that unit tests can be run using the stackless bytecode interpreter. If the unit tests are run with the stackless bytecode interpreter and the test returns a value, then the result of executing the unit test with the Move VM and the result of the interpreter will be compared and an error will be raised if they are not equal.

Detailed information on how to use unit tests as a user of Move can be found here.

Test Runner

The test runner consumes a TestPlan: this is a datastructure that is built by the Move compiler, based on source #[test] attributes. At a high level, this test plan consists of:

1. A list of ModuleTestPlans for each non-dependency module. A ModuleTestPlan consists of a list of unit tests declared in a module, along with its arguments and whether the unit test is an expected failure or not.
2. Compiled modules for each source module, along with compiled modules for all transitive dependencies.
3. The source text and source maps for every source and transitive dependency.

The test runner takes this TestPlan along with various configuration options (e.g., number of threads). From this information the test runner creates an initial test state consisting solely of the modules in bullet (2) above. This will be the same initial state for all unit tests.

After constructing this initial state, a work queue of ModuleTestPlans is passed to a rayon threadpool to execute. After the execution of each test a PASS, FAIL or TIMEOUT is reported to the writer (usually std::io::stdout) as soon as the test's result is known. The result of running tests in a ModuleTestPlan is a mapping of failing and passing tests (where failing means that the tests failed when it was expected to fail, or vis versa) along with profiling information and failure information if applicable. These test statistics for each module are combined in parallel and produce a TestResults data structure.

Test Reporter

After all of the unit tests have been run and a TestResults data structure has been created, the test reporter will iterate through the test results, and will use the data in the TestFailure info along with the source maps and source text in the test plan to display source-level error messages for any failing tests.

Depending on the options passed to the unit testing framework, additional info, such as the global storage state at the point of error for each failing test, or the execution time and number of instructions for each test may be display at the end of a test run.