Slow tests and timeouts

Slow tests can bottleneck your test run. Nextest identifies tests that take more than a certain amount of time, and optionally lets you terminate tests that take too long to run.

Slow tests

For tests that take more than a certain amount of time (by default 60 seconds), nextest prints out a SLOW status. For example, in the output below, test_slow_timeout takes 90 seconds to execute and is marked as a slow test.

    Starting 6 tests across 8 binaries (19 skipped)
        PASS [   0.001s] nextest-tests::basic test_success
        PASS [   0.001s] nextest-tests::basic test_success_should_panic
        PASS [   0.001s] nextest-tests::other other_test_success
        PASS [   0.001s]        nextest-tests tests::unit_test_success
        PASS [   1.501s] nextest-tests::basic test_slow_timeout_2
        SLOW [> 60.000s] nextest-tests::basic test_slow_timeout
        PASS [  90.001s] nextest-tests::basic test_slow_timeout
------------
     Summary [  90.002s] 6 tests run: 6 passed (1 slow), 19 skipped

Configuring timeouts

To customize how long it takes before a test is marked slow, you can use the slow-timeout configuration parameter. For example, to set a timeout of 2 minutes before a test is marked slow, add this to .config/nextest.toml:

[profile.default]
slow-timeout = "2m"

Nextest uses the humantime parser: see its documentation for the full supported syntax.

Terminating tests after a timeout

Nextest lets you optionally specify a timeout after which a test is terminated. For example, to configure a slow timeout of 60 seconds and for tests to be terminated after 3 minutes, add this to .config/nextest.toml:

[profile.default]
slow-timeout = { period = "60s", terminate-after = 3 }

terminate-after indicates the number of slow-timeout periods after which the test is terminated.

The run below is configured with:

slow-timeout = { period = "1s", terminate-after = 2 }

    Starting 5 tests across 8 binaries (20 skipped)
        PASS [   0.001s] nextest-tests::basic test_success
        PASS [   0.001s] nextest-tests::basic test_success_should_panic
        PASS [   0.001s] nextest-tests::other other_test_success
        PASS [   0.001s]        nextest-tests tests::unit_test_success
        SLOW [>  1.000s] nextest-tests::basic test_slow_timeout
        SLOW [>  2.000s] nextest-tests::basic test_slow_timeout
     TIMEOUT [   2.001s] nextest-tests::basic test_slow_timeout

--- STDOUT:              nextest-tests::basic test_slow_timeout ---

running 1 test

------------
     Summary [   2.001s] 5 tests run: 4 passed, 1 timed out, 20 skipped

How nextest terminates tests

On Unix platforms, nextest creates a process group for each test. On timing out, nextest attempts a graceful shutdown: it first sends the SIGTERM signal to the process group, then waits for a grace period (by default 10 seconds) for the test to shut down. If the test doesn't shut itself down within that time, nextest sends SIGKILL (kill -9) to the process group to terminate it immediately.

To customize the grace period, use the slow-timeout.grace-period configuration setting. For example, with the ci profile, to terminate tests after 5 minutes with a grace period of 30 seconds:

[profile.ci]
slow-timeout = { period = "60s", terminate-after = 5, grace-period = "30s" }

To send SIGKILL to a process immediately, without a grace period, set slow-timeout.grace-period to zero:

[profile.ci]
slow-timeout = { period = "60s", terminate-after = 5, grace-period = "0s" }

On other platforms including Windows, nextest terminates the test immediately in a manner akin to SIGKILL. (On Windows, nextest uses job objects to kill the test process and all its descendants.) The slow-timeout.grace-period configuration setting is ignored.

Per-test overrides

Nextest supports per-test overrides for the slow-timeout and terminate-after settings.

For example, some end-to-end tests might take longer to run and sometimes get stuck. For tests containing the substring test_e2e, to configure a slow timeout of 120 seconds, and to terminate tests after 10 minutes:

[[profile.default.overrides]]
filter = 'test(test_e2e)'
slow-timeout = { period = "120s", terminate-after = 5 }

See Override precedence for more about the order in which overrides are evaluated.

cargo-nextest