From d7a5f281213e9987e1d44fd4045a1e67100539b8 Mon Sep 17 00:00:00 2001
From: John Chilton <jmchilton@gmail.com>
Date: Mon, 3 Feb 2014 10:11:31 -0600
Subject: [PATCH] Improve examples of newer tool functional test features.

---
 test/functional/tools/README.txt              |  2 +-
 test/functional/tools/disambiguate_cond.xml   | 33 +++++++-----
 .../functional/tools/disambiguate_repeats.xml | 52 +++++++++++++------
 3 files changed, 56 insertions(+), 31 deletions(-)

diff --git a/test/functional/tools/README.txt b/test/functional/tools/README.txt
index 52671e96143..447c4df0f2f 100644
--- a/test/functional/tools/README.txt
+++ b/test/functional/tools/README.txt
@@ -1,3 +1,3 @@
 This directory contains tools only useful for testing the tool test framework
 and demonstrating it features. Run the driver script 'run_functional_tests.sh'
-with '-installed' as first argument to run through these tests.
+with '-framework' as first argument to run through these tests.
diff --git a/test/functional/tools/disambiguate_cond.xml b/test/functional/tools/disambiguate_cond.xml
index f55b98edec1..5279083495d 100644
--- a/test/functional/tools/disambiguate_cond.xml
+++ b/test/functional/tools/disambiguate_cond.xml
@@ -46,19 +46,8 @@
         <data name="out_file1" format="txt" />
     </outputs>
     <tests>
-        <test>
-            <param name="p1|use" value="True"/>
-            <param name="p2|use" value="False"/>
-            <param name="p3|use" value="True"/>
-            <param name="p4|use" value="True" />
-            <param name="p4|file" value="simple_line.txt" />
-            <output name="out_file1">
-                <assert_contents>
-                    <has_line line="4 7 4" />
-                    <has_line line="This is a line of text." />
-                </assert_contents>
-            </output>
-        </test>
+        <!-- Can use nested conditional blocks as shown below to disambiguate
+             various nested parameters. -->
         <test>
             <conditional name="p1">
                 <param name="use" value="False"/>
@@ -83,5 +72,23 @@
                 </assert_contents>
             </output>
         </test>
+        <!-- Can also use a more concise, flat verison of this, but it the
+             above version is more clear and should be considered preferable.
+        -->
+        <test>
+            <param name="p1|use" value="True"/>
+            <param name="p2|use" value="False"/>
+            <param name="p3|use" value="True"/>
+            <param name="p4|use" value="True" />
+            <!-- Only need to specify enough of a suffix to disambiguate,
+                 but don't do this - it is too clever. -->
+            <param name="p4|file" value="simple_line.txt" />
+            <output name="out_file1">
+                <assert_contents>
+                    <has_line line="4 7 4" />
+                    <has_line line="This is a line of text." />
+                </assert_contents>
+            </output>
+        </test>
     </tests>
 </tool>
diff --git a/test/functional/tools/disambiguate_repeats.xml b/test/functional/tools/disambiguate_repeats.xml
index a97f7510c86..7537a1f1e8c 100644
--- a/test/functional/tools/disambiguate_repeats.xml
+++ b/test/functional/tools/disambiguate_repeats.xml
@@ -14,7 +14,41 @@
         <data name="out_file1" format="txt" />
     </outputs>
     <tests>
-        <!-- Can use prefixes to disambiguate inputs or force order. -->
+        <!-- Can disambiguate repeats and specify multiple blocks using,
+             nested structure. -->
+        <test>
+            <repeat name="queries">
+                <param name="input" value="simple_line.txt"/>
+            </repeat>
+            <repeat name="more_queries">
+                <param name="input" value="simple_line_alternative.txt"/>
+            </repeat>
+            <output name="out_file1">
+                <assert_contents>
+                    <has_line line="This is a line of text." />
+                    <has_line line="This is a different line of text." />
+                </assert_contents>
+            </output>
+        </test>
+        <!-- Multiple such blocks can be specified but only with newer API
+             driven tests. -->
+        <test>
+            <repeat name="queries">
+                <param name="input" value="simple_line.txt"/>
+            </repeat>
+            <repeat name="queries">
+                <param name="input" value="simple_line_alternative.txt"/>
+            </repeat>
+            <repeat name="more_queries">
+                <param name="input" value="simple_line.txt"/>
+            </repeat>
+            <repeat name="more_queries">
+                <param name="input" value="simple_line_alternative.txt"/>
+            </repeat>
+            <output name="out_file1" file="simple_lines_interleaved.txt"/>
+        </test>
+        <!-- Can also use prefixes to disambiguate inputs or force order, but
+             the above nested structure is preferable. -->
         <test>
             <param name="queries_1|input" value="simple_line_alternative.txt"/>
             <param name="queries_0|input" value="simple_line.txt"/>
@@ -25,21 +59,5 @@
             <output name="out_file1" file="simple_lines_interleaved.txt"/>
         </test>
 
-        <test>
-            <repeat name="queries">
-                <param name="input" value="simple_line.txt"/>
-            </repeat>
-            <repeat name="queries">
-                <param name="input" value="simple_line_alternative.txt"/>
-            </repeat>
-            <repeat name="more_queries">
-                <param name="input" value="simple_line.txt"/>
-            </repeat>
-            <repeat name="more_queries">
-                <param name="input" value="simple_line_alternative.txt"/>
-            </repeat>
-            <output name="out_file1" file="simple_lines_interleaved.txt"/>
-        </test>
-
     </tests>
 </tool>