From 344a97e08a695af40ec77e439582ffdc06154f21 Mon Sep 17 00:00:00 2001
From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Fri, 19 Apr 2024 16:01:48 +0200
Subject: Add meson test --interactive

This is very similar to --gdb, except it doesn't spawn GDB, but
connects stdin/stdout/stderr directly to the test itself. This allows
interacting with integration tests that spawn a shell in a container
or virtual machine when the test fails.

In systemd we're migrating our integration tests to run using the
meson test runner. We want to allow interactive debugging of failed
tests directly in the virtual machine or container that is spawned
to run the test. To make this possible, we need meson test to connect
stdin/stdout/stderr of the test directly to the user's terminal, just
like is done with the --gdb option.
---
 docs/markdown/Unit-tests.md                | 10 ++++++++++
 docs/markdown/snippets/test_interactive.md |  6 ++++++
 2 files changed, 16 insertions(+)
 create mode 100644 docs/markdown/snippets/test_interactive.md

(limited to 'docs')

diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md
index dc509a818..73e58dc68 100644
--- a/docs/markdown/Unit-tests.md
+++ b/docs/markdown/Unit-tests.md
@@ -256,6 +256,16 @@ $ meson test --gdb --gdb-path /path/to/gdb testname
 $ meson test --print-errorlogs
 ```
 
+Running tests interactively can be done with the `--interactive` option.
+`meson test --interactive` invokes tests with stdout, stdin and stderr
+connected directly to the calling terminal. This can be useful if your test is
+an integration test running in a container or virtual machine where a debug
+shell is spawned if it fails *(added 1.5.0)*:
+
+```console
+$ meson test --interactive testname
+```
+
 Meson will report the output produced by the failing tests along with
 other useful information as the environmental variables. This is
 useful, for example, when you run the tests on Travis-CI, Jenkins and
diff --git a/docs/markdown/snippets/test_interactive.md b/docs/markdown/snippets/test_interactive.md
new file mode 100644
index 000000000..907147fd9
--- /dev/null
+++ b/docs/markdown/snippets/test_interactive.md
@@ -0,0 +1,6 @@
+## The Meson test program supports a new "--interactive" argument
+
+`meson test --interactive` invokes tests with stdout, stdin and stderr
+connected directly to the calling terminal. This can be useful when running
+integration tests that run in containers or virtual machines which can spawn a
+debug shell if a test fails.
-- 
cgit v1.2.3