Test modules

This page provides basic information on how to build a rust_test module that uses the Rust test harness.

Write a basic Rust test

For a live example of an on-device and on-host Rust test, view keystore2 Android.bp, or locate one in many of the crates in the external/rust/crates directory.

A rust_test module builds using rustc's --test flag, which creates tests out of code marked with the #[test] attribute. For more information, see the The Rust Reference Testing Attributes documentation.

Define a test module as follows:

rust_test {
    name: "libfoo_inline_tests",

    // Specify the entry point of your library or binary to run all tests
    // specified in-line with the test attribute.
    srcs: ["src/lib.rs"],

    // Tradefed test suite to include this test in.
    test_suites: ["general-tests"],

    // Autogenerate the test config
    auto_gen_config: true,

    rustlibs: [
        "libfoo",
    ],
}

A TEST_MAPPING file contains a list of tests. Although it’s not a requirement, if you do create a TEST_MAPPING file, the tests you include in it will run in presubmit tests, and can be invoked using atest.

You can reference the TEST_MAPPING documentation for more information, but for the libfoo_inline_tests example, add this to presubmit to enable your test runs on TreeHugger:

{
  "presubmit": [
    {
      "name": "libfoo_inline_tests",
    },
  ]
}

Note that rust_test_host modules run by default in presubmit unless unit_tests: is set to false, so you don't need to declare these in TEST_MAPPING files.

For more information on how the auto_gen_config and test_suites properties work, see the Settings section of the Test Development Workflow documentation.

Notable Rust test properties

The rust_test modules inherit properties from rust_binary modules as described on the Binary Modules page.

The properties defined in the table below are in addition to the Important common properties that apply to all modules. These are either particularly important to Rust test modules, or exhibit unique behavior specific to the rust_test module type.

• test_harness: Advanced usage, defaults to true.

Set this to false if your rust_test implements its own test harness and you don't need to use the built-in Rust test harness (in other words, setting this to false won't pass the --test flag to rustc).

Avoid duplication between rust_library and rust_test

When you use inline Rust tests via nested modules, you end up with duplication in your Android.bp file. The problem is that you have to list the dependencies twice, once for rust_library and once for rust_test:

rust_library {
    name: "libfoo",
    srcs: ["src/lib.rs"],
    rustlibs: [
        "libx",
        "liby",
        "libz",
    ],
}

rust_test {
    name: "libfoo_inline_tests",
    srcs: ["src/lib.rs"],
    test_suites: ["general-tests"],
    rustlibs: [
        "libx",
        "liby",
        "libz",
    ],
}

Each rust_test module will end up listing the same dependencies as the corresponding rust_library module. To ensure consistency between the modules, you can list the dependencies just once in a rust_defaults module:

rust_defaults {
    name: "libfoo_defaults",
    srcs: ["src/lib.rs"],
    rustlibs: [
        "libx",
        "liby",
        "libz",
    ],
}

rust_library {
    name: "libfoo",
    defaults: ["libfoo_defaults"],
}

rust_test {
    name: "libfoo_inline_tests",
    defaults: ["libfoo_defaults"],
    test_suites: ["general-tests"],
}

This way, the library and the test module will always use the same dependencies.