Testing & Debugging Rust Code

This page explains how to test and debug Rust code in Firefox.

The build documentation explains how to add new Rust code to Firefox. The code documentation explains how to write and work with 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.

Rust tests

If a Mozilla crate has “normal” Rust tests (i.e. #[test] functions that run with cargo test), you can add the crate’s name to RUST_TESTS in toolkit/library/rust/moz.build. (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 of 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 nsstring and xpcom.

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 example.

GTests

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 -gtest suffix.
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.toml file that references the Rust file, and a moz.build file that references the C++ file.
Add an entry to the [dependencies] section in toolkit/library/gtest/rust/Cargo.toml.
Add an extern crate entry to toolkit/library/gtest/rust/lib.rs.

See xpcom/rust/gtest/nsstring/ 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