Tags

Assigning tags

Tests can be associated with an arbitrary number of tags. Each tag is global, and must be a valid Rust identifier. Tags can be assigned to tests using the #[tag] attribute:

#![allow(unused)]
fn main() {
use test_r::{tag, test};

#[tag(tag1)]
#[tag(tag2)]
#[test]
fn tagged_test() {
    assert!(true);
}
}

Matrix-generated test cases also get an auto-derived tag for each matrix case. See Dependency matrix for details.

Tagging entire test suites

It is possible to tag an entire test suite. This can be done by using the #[tag] attribute on the module containing the tests, or alternatively using the tag_suite! macro:

#![allow(unused)]
fn main() {
use test_r::{tag, tag_suite, test};

mod inner1;

tag_suite!(inner1, tag1);

#[tag(tag2)]
mod inner2 {
    // ...
}
}

The tag_suite! macro is necessary because currently it is not possible to put attributes on non-inlined modules.

Running tagged tests

The purpose of tagging tests is to run a subset of the crate’s tests selected by tags. To select tests by tags, use the :tag: prefix when passing the test name to cargo test:

cargo test :tag:tag1

This example will run every test tagged as tag1, but no others.

Selecting matrix cases by auto-derived tags

Each generated dependency-matrix case is automatically tagged as <dimension>_<case>. For example, a matrix dimension named db with cases postgres and sqlite produces case tags db_postgres and db_sqlite.

These are ordinary tags and can be selected with the same :tag: syntax:

cargo test ':tag:db_sqlite'

When a test uses multiple matrix dimensions, the generated case carries one auto-derived tag per dimension, so tag expressions can select a specific combination:

cargo test ':tag:db_postgres&runtime_tokio'

Selecting untagged tests

Sometimes it is useful to select all tests without a tag. This can be done by using the :tag: prefix with no tag name:

cargo test :tag:

Selecting tests by multiple tags

Multiple tags can be combined with the | (or) and & (and) operators. The & operator has higher precedence than |. So the following example:

cargo test ':tag:tag1|tag2&tag3'

is going to run tests tagged as either tag1 or both tag2 and tag3.

Skipping tests by tag

The :tag: syntax also works with the --skip option. This allows skipping all tests with a specific tag:

cargo test -- --skip ':tag:slow'

This runs all tests except those tagged as slow.