From 306373027a18f44ba6dec2370dfde9d83ad7eeec Mon Sep 17 00:00:00 2001
From: Pau Espin Pedrol <pespin@sysmocom.de>
Date: Wed, 6 May 2020 21:11:02 +0200
Subject: Allow suites to dynamically register schemas so tests can receive
 parameters

Change-Id: Idbe99a35993d193cd97059feb980e61ff14c67ad
---
 doc/manuals/chapters/config.adoc | 55 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 4 deletions(-)

(limited to 'doc')

diff --git a/doc/manuals/chapters/config.adoc b/doc/manuals/chapters/config.adoc
index 4dd90ff..483fd8c 100644
--- a/doc/manuals/chapters/config.adoc
+++ b/doc/manuals/chapters/config.adoc
@@ -305,16 +305,26 @@ suites_dir/
 
 This file content is parsed using the <<schema_want,Want>> schema.
 
-It provides
-{app-name} with the base restrictions (later to be further filtered by
-<<scenario_conf,scenario>> files) to apply when allocating resources.
+On the <<schema_want,resources>> section, it provides {app-name} with the base restrictions
+(later to be further filtered by <<scenario_conf,scenario>> files) to apply when
+allocating resources.
 
 It can also override attributes for the allocated resources through the
 <<schema_want,modifiers>> section (to be further modified by
-<<scenario_conf,scenario>> files later on). Similary it can do the same for
+<<scenario_conf,scenario>> files later on). Similarly it can do the same for
 general configuration options (no per-resource) through the
 <<schema_want,config>> section.
 
+The _schema_ section allows defining a suite's own schema used to validate
+parameters passed to it later on through <<scenario_conf,scenario>> files (See
+<<scenario_suite_params>>), and which can be retrieved by tests using the
+_tenv.config_suite_specific()_ and _tenv.config_test_specific()_ APIs. The first
+one will provide the whole dictionary under schema, while the later will return
+the dictionary immediatelly inside the former and matching the test name being
+run. For instance, if _tenv.config_test_specific()_ is called from test
+_a_suite_test_foo.py_, the method will return the contents under dictionary with
+key _a_suite_test_foo_.
+
 .Sample 'suite.conf' file:
 ----
 resources:
@@ -337,6 +347,12 @@ config:
       codec_list:
       - fr1
 
+schema:
+  some_suite_parameter: 'uint'
+  a_suite_test_foo:
+    one_test_parameter_for_test_foo: 'str'
+    another_test_parameter_for_test_foo: ['bool_str']
+
 defaults:
   timeout: 50s
 ----
@@ -431,6 +447,37 @@ This way {app-name} when parsing the scenarios and combining them with the suite
 . Generate the final
   scenario content from the template available in the matched '.conf' file.
 
+[[scenario_suite_params]]
+*_Scenario to set suite/test parameters_*:
+
+First, the suite needs to define its schema in its <<suite_conf,suite.conf>>
+file. Check <<suite_conf>> on how to do so.
+
+For instance, for a suite named 'mysuite' containing a test 'a_suite_test_foo.py', and containing this schema in its <<suite_conf,suite.conf>> file:
+----
+schema:
+  some_suite_parameter: 'uint'
+  a_suite_test_foo:
+    one_test_parameter_for_test_foo: 'str'
+    another_test_parameter_for_test_foo: ['bool_str']
+----
+
+One could define a parametrized scenario 'myparamscenario@.conf' like this:
+----
+config:
+  suite:
+    mysuite:
+      some_suite_parameter: ${param1}
+      a_suite_test_foo:
+        one_test_parameter_for_test_foo: ${param2}
+        another_test_parameter_for_test_foo: ['true', 'false', 'false', 'true']
+----
+
+And use it in {app-name} this way:
+----
+mysuite:myparamscenario@4,hello.conf
+----
+
 [[resources_conf]]
 ==== 'resources.conf'
 
-- 
cgit v1.2.3