# What does \`--test-load\` do?

**URL:** https://discourse.cmake.org/t/what-does-test-load-do/8610
**Category:** Usage
**Tags:** os:linux
**Created:** [July 26, 2023, 8:39pm UTC](https://discourse.cmake.org/t/what-does-test-load-do/8610 "2023-07-26T20:39:01Z")
**Posts on this page:** 3
**Page:** 1

<div class="post-metadata">

### Author: ![Barry\_Revzin](https://discourse.cmake.org/user_avatar/discourse.cmake.org/barry_revzin/32/1283_2.png) [@Barry\_Revzin](https://discourse.cmake.org/u/Barry_Revzin)
#### Post date: [July 26, 2023, 8:39pm UTC](https://discourse.cmake.org/t/what-does-test-load-do/8610/1 "2023-07-26T20:39:01Z")

</div>

The documentation for `--test-load` in ctest currently reads:

> `--test-load <level>`
> 
> While running tests in parallel (e.g. with [`-j`](https://cmake.org/cmake/help/latest/manual/ctest.1.html#cmdoption-ctest-j)), try not to start tests when they may cause the CPU load to pass above a given threshold.

This then links to other docs that also basically say the same thing.

But what does this actually mean? What does `<level>` mean? Is it in units of percent? So if I write `--test-load 60` does that mean that it will wait to start a test until some available CPU drops below `60%`?

---

<div class="post-metadata">

### Author: ![craig.scott](https://discourse.cmake.org/user_avatar/discourse.cmake.org/craig.scott/32/20_2.png) [@craig.scott](https://discourse.cmake.org/u/craig.scott)
#### Post date: [July 26, 2023, 11:17pm UTC](https://discourse.cmake.org/t/what-does-test-load-do/8610/2 "2023-07-26T23:17:56Z")

</div>

My recollection is that this is equivalent to the `-l` flag for `make` or `ninja`. Those tools explain it as something like “`-l N` → do not start new jobs if the load average is greater than N”. I haven’t checked the implementation of `--test-load` for ctest, but I believe it is the same.

FWIW, this flag on its own is typically useless. At the very start of the test run, ctest would launch many tests because there’s always a lag before the load average increases. So at the start, you end up hopelessly oversubscribing the CPU. You must use `--test-load` in conjunction with `--parallel` or an equivalent.

---

<div class="post-metadata">

### Author: ![ben.boeckel](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/b/ea5d25/32.png) [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [July 27, 2023, 2:47am UTC](https://discourse.cmake.org/t/what-does-test-load-do/8610/3 "2023-07-27T02:47:25Z")

</div>

The “load” of a machine (in POSIX at least; I’m less familiar with how it works on Windows) is generally a count of how many processes are waiting to do work. If this rises above the number of cores, it means there is more work available than the CPU can perform concurrently. Generally, you can do something like `ninja -j$((2 * $(nproc))) -l$(nproc)` so that you can have more I/O-bound tasks but also don’t swamp the system with CPU-bound tasks.

See [this LWN article for some more details](https://lwn.net/Articles/759781/).