Add test priorities to force test start order

2 files changed, 19 insertions, 0 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index a89d93977..bdcbe1fa3 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1520,6 +1520,12 @@ Keyword arguments are the following:
   Protocol](https://www.testanything.org/)). For more on the Meson test
   harness protocol read [Unit Tests](Unit-tests.md). Since 0.50.0
 
+- `priority` specifies the priority of a test. Tests with a
+  higher priority are *started* before tests with a lower priority.
+  The starting order of tests with identical priorities is
+  implementation-defined. The default priority is 0, negative numbers are
+  permitted. Since 0.52.0
+
 Defined tests can be run in a backend-agnostic way by calling
 `meson test` inside the build dir, or by using backend-specific
 commands, such as `ninja test` or `msbuild RUN_TESTS.vcxproj`.
diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md
index 3c2773205..9c2e3d50b 100644
--- a/docs/markdown/Unit-tests.md
+++ b/docs/markdown/Unit-tests.md
@@ -51,6 +51,19 @@ By default Meson uses as many concurrent processes as there are cores on the tes
 $ MESON_TESTTHREADS=5 ninja test
 ```
 
+Priorities
+--
+
+Tests can be assigned a priority that determines when a test is *started*. Tests with higher priority are started first, tests with lower priority started later. The default priority is 0, meson makes no guarantee on the ordering of tests with identical priority.
+
+```meson
+test('started second', t, priority : 0)
+test('started third', t, priority : -50)
+test('started first', t, priority : 1000)
+```
+
+Note that the test priority only affects the starting order of tests and subsequent tests are affected by how long it takes previous tests to complete. It is thus possible that a higher-priority test is still running when lower-priority tests with a shorter runtime have completed.
+
 ## Skipped tests and hard errors
 
 Sometimes a test can only determine at runtime that it can not be run.