From b6bfb80debba692868d8ea2831511db42ac5b397 Mon Sep 17 00:00:00 2001
From: Carl Worth <cworth@cworth.org>
Date: Wed, 8 Aug 2012 17:18:32 -0700
Subject: [PATCH] Add some comments to the recently-added cli tests.

It's easy enough to ignore lines starting with a '#' and that lets us
make these tests more self-documenting.
---
 cli/README.markdown                 |  2 ++
 cli/cli-diff-images-mismatch.script | 14 ++++++++++++++
 cli/cli-diff-images.script          | 14 ++++++++++++++
 cli_driver.py                       |  4 +++-
 4 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/cli/README.markdown b/cli/README.markdown
index 6be80a9..4f49822 100644
--- a/cli/README.markdown
+++ b/cli/README.markdown
@@ -28,6 +28,8 @@ line):
                 interpreted locally. If this fails for any reason
                 other than "file does not exist" the test will fail.
 
+Note: Blank lines and lines beginning with '#' are ignored.
+
 Commands can be prefixed with "EXPECT_FAILURE:" to indicate that a
 command is expected to return a non-zero value. In this case, a return
 value of zero from the command will cause the test to fail.
diff --git a/cli/cli-diff-images-mismatch.script b/cli/cli-diff-images-mismatch.script
index 9c97fa3..a325479 100644
--- a/cli/cli-diff-images-mismatch.script
+++ b/cli/cli-diff-images-mismatch.script
@@ -1,4 +1,18 @@
+# The first two steps are just as in cli-diff-images. Dump images from
+# a trace into an empty directory.
+
 rm_and_mkdir ./tri-out
 apitrace dump-images -o ./tri-out/tri tri.trace
+
+# Compare the dumped image with a doctored image to provoke a failure.
+# The EXPECT_FAILURE attribute causes the test driver to look for a
+# non-zero return value from apitrace and fail the test if it is not
+# seen.
+
 EXPECT_FAILURE: apitrace diff-images -v ./tri-ref-mismatch ./tri-out
+
+# In addition to getting the return value indicating an error, let's
+# also require that "apitrace diff-images" gave us the output we
+# expect.
+
 expect "Comparing ./tri-ref-mismatch/tri0000000027.png and ./tri-out/tri0000000027.png ... MISMATCH\n"
diff --git a/cli/cli-diff-images.script b/cli/cli-diff-images.script
index cb4630f..e575f1a 100644
--- a/cli/cli-diff-images.script
+++ b/cli/cli-diff-images.script
@@ -1,4 +1,18 @@
+# Make a directory for the output images
+
 rm_and_mkdir ./tri-out
+
+# Generate images for every frame (only 1) of a trace
+
 apitrace dump-images -o ./tri-out/tri tri.trace
+
+# Compare the result of "apitrace dump-images" with our reference
+
 apitrace diff-images -v ./tri-ref ./tri-out
+
+# Ensure that the "apitrace diff-images" actually did something.  This
+# is important since if it couldn't find images in one directory or
+# the other then it would just silently return 0 and this test would
+# incorrectly pass.
+
 expect "Comparing ./tri-ref/tri0000000027.png and ./tri-out/tri0000000027.png ... MATCH\n"
diff --git a/cli_driver.py b/cli_driver.py
index a7f4b3d..53bd100 100644
--- a/cli_driver.py
+++ b/cli_driver.py
@@ -83,12 +83,14 @@ class CliDriver(Driver):
 
             line = script.readline()
 
+            # Exit loop on EOF
             if (line == ''):
                 break
 
             cmd = line.split()
 
-            if (len(cmd) == 0):
+            # Ignore blank lines and comments
+            if (len(cmd) == 0 or line[0] == '#'):
                 continue
 
             if (cmd[0] == 'EXPECT_FAILURE:'):
-- 
2.43.0