Testing & Debugging Rust Code¶
This page explains how to test and debug Rust code in Firefox.
Testing Mozilla crates¶
Rust code will naturally be tested as part of system tests such as Mochitests. This section describes the two methods for unit testing of individual Rust crates. Which method should be used depends on the circumstances.
If a Mozilla crate has “normal” Rust tests (i.e.
#[test] functions that run
cargo test), you can add the crate’s name to
(Cargo features can be activated for Rust tests by adding them to
RUST_TEST_FEATURES in the same file.)
Rust tests are run with
./mach rusttests. They run on automation in a couple
rusttests jobs, but not on all platforms.
Rust tests have one major restriction: they cannot link against Gecko symbols.
Therefore, Rust tests cannot be used for crates that use Gecko crates like
It’s also possible to use
RUST_TESTS in a different
moz.build file. See
testing/geckodriver/moz.build and the geckodriver testing docs for an
Another way to unit test a Mozilla crate is by writing a GTest that uses FFI to call into Rust code. This requires the following steps.
Create a new test crate whose name is the same as the name of crate being tested, with a
Add to the test crate a Rust file, a C++ file containing GTest
TEST()functions that use FFI to call into the Rust file, a
Cargo.tomlfile that references the Rust file, and a
moz.buildfile that references the C++ file.
Add an entry to the
[dependencies]section in toolkit/library/gtest/rust/Cargo.toml.
extern crateentry to toolkit/library/gtest/rust/lib.rs.
for a simple example. (Note that the
moz.build file is in the parent
directory for that crate.)
A Rust GTest can be run like any other GTest via
./mach gtest, using the C++
TEST() functions as the starting point.
Unlike Rust tests, GTests can be used when linking against Gecko symbols is required.
Testing third-party crates¶
In general we don’t run tests for third-party crates. The assumption is that these crates are sufficiently well-tested elsewhere.
Debugging Rust code¶
In theory, Rust code is debuggable much like C++ code, using standard tools
rr, and the Microsoft Visual Studio Debugger. In practice, the
experience can be worse, because shortcomings such as the following can occur.
Inability to print local variables, even in non-optimized builds.
Inability to call generic functions.
Missing line numbers and stack frames.
Printing of basic types such as
Vecis sometimes sub-optimal. If you see a warning “Missing auto-load script at offset 0 in section
.debug_gdb_scripts” when starting
rust-gdbwrapper may give better results.
Logging from Rust code¶
RUST_LOG environment variable (from the
env_logger crate) can be used
to enable logging to stderr from Rust code in Firefox. The logging macros from
log crate can be used. In order of importance, they are:
For example, to show all log messages of
info level or higher, run:
Module-level logging can also be specified, see the documentation for the
env_logger crate for details.
To restrict logging to child processes, use
RUST_LOG_CHILD instead of
Rust logging can also be forwarded to the Gecko logger for capture via
When parsing modules from
MOZ_LOG, modules containing
::are considered to be Rust modules. To log everything in a top-level module like
neqo_transport, specify it as
neqo_transport::*. For example:
When logging from a submodule the
::*is allowed but isn’t necessary. So these two lines are equivalent:
MOZ_LOG=timestamp,sync,neqo_transport::recovery:5 firefox MOZ_LOG=timestamp,sync,neqo_transport::recovery::*:5 firefox
trace!logs will not appear in non-debug builds. This is due to our use of the
release_max_level_infofeature in the
When using both
RUST_LOG, modules that are specified in
MOZ_LOGwill not appear in