From 91faeeeba1480af986a451306076286a510a10da Mon Sep 17 00:00:00 2001 From: Carl Worth Date: Tue, 7 Aug 2012 15:47:53 -0700 Subject: [PATCH] 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. --- apps/README.markdown | 34 ++++++++++++++++++++++++++++++++++ traces/README.markdown | 18 ++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 apps/README.markdown diff --git a/apps/README.markdown b/apps/README.markdown new file mode 100644 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 2fd26af..2d5d675 100644 --- 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). -- 2.43.0