From f50ba69fe6f5586507cf361f4d6fd7dadf86823c Mon Sep 17 00:00:00 2001
From: Alexandre Janniaux <ajanni@videolabs.io>
Date: Tue, 23 Apr 2024 10:27:57 +0200
Subject: [PATCH] doc: buildsystem: document meson tests

The buildsystem provides a dedicated meson array for tests to generate
the test executables and test scenarios in a unified way while declaring
the dependencies to runtime dependencies (mainly plugins).
---
 doc/standalone/buildsystem.md | 75 +++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/doc/standalone/buildsystem.md b/doc/standalone/buildsystem.md
index a11096b032..6be80a3883 100644
--- a/doc/standalone/buildsystem.md
+++ b/doc/standalone/buildsystem.md
@@ -216,6 +216,81 @@ endif
 it would not do what you might expect, as `disable_auto_if` returns a new option and does not mutate the
 existing one. The returned option object is never assigned to any variable, so it is lost.
 
+### Adding new tests
+
+VLC tests are also meson dictionaries added to the special array named `vlc_tests`.
+This mechanism allows a test to reference modules that should be available when
+running the test.
+
+To add a new test, simply append to that variable:
+
+```meson
+vlc_tests += {
+    'name' : 'test_src_input_thumbnail',
+    'sources' : files('input/thumbnail.c'),
+    'suite' : ['src', 'test_src'],
+    'link_with' : [libvlc, libvlccore],
+    'module_depends' : ['demux_mock', 'rawvideo']
+}
+```
+
+@warning    Make sure to not accidentally overwrite the `vlc_tests` variable
+            by using an `=` instead of `+=` when appending the dictionary.
+
+Currently the modules dictionary accepts the following keys:
+
+@param  name
+        The name of the new VLC test, which will map to the executable name. **Required**
+
+@param  sources
+        The source files for the new test, use [`files()`][mref_files] to specify them. **Required**
+
+@param  suite
+        The meson test suites to which this test should be available.
+
+@param  dependencies
+		The dependencies needed by the test. Only list external dependencies
+		here, not libraries that are built as part of the VLC build, for these
+		use `link_with` instead.
+
+@param  link_with
+		The dependencies needed by the test that are part of the VLC build.
+        For external dependencies, use `dependencies` instead.
+
+@param  include_directories
+		Additional include directories that should be used when compiling the test.
+		These should be specified using the [`include_directories()`][mref_include_directories]
+		function.
+
+@param  module_depends
+        The list of module names this test depends upon.
+
+@param  moc_headers
+        A list of header files that should be transformed by Qt's moc
+        source translater built for the test.
+
+@param  c_args
+	    Additional flags to pass to the C compiler.
+
+@param  cpp_args
+		Additional flags to pass to the C++ compiler.
+
+@param  objc_args
+		Additional flags to pass to the Objective-C compiler.
+
+To run a specific test, you can directly use:
+
+```bash
+meson test -C build-meson test_src_input_thumbnail
+```
+
+where `test_src_input_thumbnail` can be replaced by the `name` of the test.
+Make sure that a module really depends upon the module it's using through the
+`module_depends` variable. If every modules should be used to run the test,
+you can use the special value `vlc_plugins_targets.keys()`, but adding more
+module dependencies than necessary will drastically increase the compile time
+when running a specific test in cases like automated `git bisect`.
+
 #### Compiling with contribs
 
 The meson build system also supports using dependencies and binaries provided