Add more README documentation on how existing test drivers are structured.

More than once, I've reverse-engineered how the test suite uses test
drivers (app_driver.py and tool_driver.py) to invoke scripts within
the apps/ and traces/ directory. In order to save my future-self some
work in doing this yet again, I've written some documentation in
README.markdown in each directory.

Hopefully this documentation will be useful for anyone wanting to
write additional tests.

diff --git a/apps/README.markdown b/apps/README.markdown
new file mode 100644 (file)
index 0000000..3820630
--- /dev/null
+++ b/apps/README.markdown
@@ -0,0 +1,34 @@
+These directories contain many drawing-api-specific test applications.
+
+Within each directory's CMakeLists.txt file are you will see
+definitions of tests such as the following:
+
+    add_app_test (
+        NAME "gl_default_sb"
+        TARGET gl_tri
+        ARGS -sb
+        REF default_sb.ref.txt
+    )
+
+This block specifies a test with NAME "gl_default_sb" that involves
+executing the TARGET program "gl_tri" with ARGS of "-sb". The REF
+script contains a reference trance that should result from tracing the
+given program, along with specifications for additional checks to be
+peformed.
+
+The actual execution of the test (and parsing of the REF script) is
+performed by the python program in ../app_driver.py. This driver
+program runs the application with the given arguments, performs a
+trace of the application, checks the trace against the reference
+script, and then run a "retrace" of the application (replaying the
+commands in the trace).
+
+In addition to a dump of the expected trace content, the reference
+file can contain directives to cause the driver program to perform
+additional checking. Some of the available directives are:
+
+  #image: Dump the current framebuffer image and compare against the
+          given file.
+
+  #state: Dump the current state in JSON format and compare against
+          the given file.

diff --git a/traces/README.markdown b/traces/README.markdown
index 2fd26af7360e8497f0a670663a6e8bb3a629f4a5..2d5d6751bcb790c35d24970017983c5ebfccff64 100644 (file)
--- a/traces/README.markdown
+++ b/traces/README.markdown
@@ -1,3 +1,21 @@
+This directory tests various operations of the apitrace command-line
+interface (cli) operating on existings.
+
+All files with a .script extension specify a simple script for
+testing. The test driver (in ../tool_driver.py) will parse the script
+file line-by-line, interpreting each line as arguments to the apitrace
+cli interface and invoking the cli with the given arguments. This
+continues until the first line of the script beginning with the "dump"
+command.
+
+After a "dump" command in the script, the remainder of the script file
+provides the expected output of the given dump command. The tool
+driver will report a test failure if the actual dump output differs
+from that given in the.
+
+Here are descriptions of some of the trace files contained here which
+are used by the test scripts:
+
 *   zlib-no-eof.trace:  is a short, zlib compressed trace, with an unexpected end of
     file because the application terminated abnormally (which is actual very
     normal).