Megatest

A item based waiton will start items in a test when the same-named
item is COMPLETED and PASS, CHECK or WAIVED in the prior test. This
was historically called "itemwait" mode. The terms "itemwait" and
"itemmatch" are synonyms.

-------------------
[requirements]
waiton precedingtest
mode itemmatch
-------------------

Overriding Enviroment Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Override variables before starting the test. Can include files (perhaps generated by megatest -envdelta or similar).

#{scheme (unsetenv "FOOBAR")}
--------------------

Itemmap Handling
~~~~~~~~~~~~~~~~

For cases were the dependent test has a similar but not identical
itempath to the downstream test an itemmap can allow for itemwait/itemmatch
mode by specifying rules on how to map the waiton's item name to the current test's item name.

.example for removing part of itemmap for waiton test (eg: item +foo-x/bar+ depends on waiton's item +y/bar+)
-------------------
[requirements]
mode itemwait
waiton precedingtest
# itemmap <item pattern for this test>  <item replacement pattern for waiton test>
itemmap .*x/ y/

-------------------

.example for removing part of itemmap for waiton test (eg: item +foo/bar/baz+ in this test depends on waiton's item +baz+)
-------------------

# ## pattern replacement notes
#
# ## Example
# ## Remove everything up to the last /
[requirements]
mode itemwait
waiton precedingtest
# itemmap <item pattern for this test> <nothing here indicates removal>
itemmap .*/
-------------------

.example replacing part of itemmap for (eg: item +foo/1234+ will imply waiton's item +bar/1234+)
-------------------

#
# ## Example
# ## Replace foo/ with bar/
[requirements]
mode itemwait
waiton precedingtest
# itemmap <item pattern for this test>  <item replacement pattern for waiton test>
itemmap foo/ bar/

-------------------

.example for backreference (eg: item +foo23/thud+ will imply waiton's item +num-23/bar/thud+
-------------------
#
# ## Example
# ## can use \{number} in replacement pattern to backreference a (capture) from matching pattern similar to sed or perl
[requirements]
mode itemwait
waiton precedingtest
# itemmap <item pattern for this test>  <item replacement pattern for waiton test>
itemmap foo(\d+)/ num-\1/bar/

-------------------

.example multiple itemmaps
-------------------

# multi-line; matches are applied in the listed order
# The following would map:
#   a123b321 to b321fooa123 then to 321fooa123p
#
[requirements]
modw itemwait
waiton precedingtest
itemmap (a\d+)(b\d+) \2foo\1
  b(.*) \1p
-------------------


Complex mapping
^^^^^^^^^^^^^^^

We accomplish this by configuring the testconfigs of our tests C D and E as follows:

.Testconfig for Test E has
----------------------
[requirements]
waiton C
mode itemwait
itemmap (\d+)/res \1/bb
----------------------

.Testconfig for Test D has
----------------------
[requirements]
waiton C
mode itemwait
itemmap (\d+)/res \1/aa
----------------------

.Testconfig for Test C has
----------------------
[requirements]
waiton A B
mode itemwait

[itemmap]
A (\d+)/aa aa/\1
B (\d+)/bb bb/\1
----------------------

.Testconfigs for Test B and Test A have no waiton or itemmap configured