Skip to main content

test

gpui

Attribute Macro test 

Source 
#[test]
Expand description

Marks a function as a GPUI test. The generated function is a #[test], so it runs under cargo test or cargo nextest.

The function can be synchronous or async. Its parameters decide what it receives:

  • &mut TestAppContext (or &TestAppContext): a fresh test context. Use one per app you need. Any number is allowed.
  • &mut App: a synchronous test only. The test gets the app directly.
  • BackgroundExecutor: an async test only. An executor for the test’s scheduler.
  • StdRng: a random number generator seeded with the current run’s seed. Use it to vary inputs. Each run sees the same values for the same seed, so changing the seed explores other interleavings.

Any other parameter type is a compile error.

An async test takes a context, for example async fn test_counter(cx: &mut TestAppContext), and runs inside the test scheduler.

Your crate needs rand as a dev-dependency, because the generated code calls rand::SeedableRng to seed a StdRng parameter.

§Arguments

  • #[gpui::test] with no arguments runs once, with seed 0 or the value of the SEED environment variable.
  • #[gpui::test(seed = 10)] runs once with seed 10.
  • #[gpui::test(seeds(10, 20, 30))] runs once for each of seeds 10, 20 and 30.
  • #[gpui::test(iterations = 5)] runs with seeds 0 to 4.
  • #[gpui::test(retries = 3)] retries a failing seed up to three more times, so a seed runs at most four times. The retries are per seed.
  • #[gpui::test(on_failure = "crate::test::report_failure")] calls the named function with no arguments once a seed has failed on its final attempt, before the test panics. Use it to write out more details about the failure. The path must be a fn().

iterations combines with seed and seeds. The iteration seeds run first, then the explicit seeds. For example, #[gpui::test(iterations = 5, seed = 10)] runs seeds 0, 1, 2, 3, 4, 10.

When a run has more than one seed, the macro prints each seed to stderr. It prints the failing seed too, along with how to rerun it.

§Environment Variables

  • SEED: runs only that seed (or SEED through SEED + iterations - 1 when iterations is set). It overrides every explicit seed.
  • ITERATIONS: overrides the value of the iterations argument.