[Mesa-dev] [PATCH] glsl: Add README describing how to run python unit tests manually

[Iago Toral Quiroga]

---

Developers writing new tests probably want to know how to do this and be aware
of things like the fact that some binaries are linking Mesa libraries
statically. That certainly had me scratching my head for a while when I was
working on a fix for a unit test that insisted in failing even though I was
completely sure that I had fixed the code in Mesa, only to end up realizing
that I had to rebuild the glsl_test program manually to incorporate the changes
I had made to Mesa into the test. I suppose this is likely to happen to most
newcomers, so better have it documented.

 src/glsl/tests/README | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 src/glsl/tests/README

diff --git a/src/glsl/tests/README b/src/glsl/tests/README
new file mode 100644
index 0000000..4b5d370
--- /dev/null
+++ b/src/glsl/tests/README
@@ -0,0 +1,56 @@
+Generally, tests for optimization passes are ran together with other tests
+via the 'make check' command. However, the output provided by this is very
+summarized, which is more useful when running sanity checks, but not enough
+if we are working on the tests themselves, where we usually want to run
+only the tests we are interested in and get more detailed information about
+the output of each one.
+
+This document describes how to run the Python unit tests for optimization
+passes that live in src/glsl/tests manually.
+
+1. Preparations
+
+Before these unit tests can be executed manually, we need to generate the
+program glsl_test in src/glsl/. Go to that directory and execute
+'make glsl_test'. If you have run 'make check' before, this program should
+already exist.
+
+IMPORTANT: Notice that glsl_test will link Mesa libraries statically, so it
+must be rebuilt every time that the Mesa code changes. Also, notice that
+glsl_test will not be automatically (re-)built when building Mesa (unless
+you run 'make check' specifically), so this needs to be done manually after
+any code changes to Mesa and before running the unit tests. Failure to do this
+will result in the tests running against an old version of the Mesa code that
+won't incorporate recent changes. If you are working on Mesa to fix a
+particular test, be sure to rebuild this binary before testing your changes.
+
+2. Generate unit tests
+
+With glsl_test already generated, go back to src/glsl/tests/. Unit tests
+for optimization passes are generated from the create_test_cases.py
+files in the various subdirectories. Each create_test_cases.py creates unit
+tests for a specific group of optimizations.
+
+The create_test_cases.py files must be run through a python runtime to generate
+the actual test cases (this should be done from inside the directory that
+contains the create_test_cases.py file). You need to do this every time you
+modify the create_test_cases.py file. If you have run 'make check' before this
+should have already been done.
+
+When a create_test_cases.py file is executed it creates 2 files for each test:
+
+- test_name.opt_test: The actual test. This is actually a shell script that
+will use the glsl_test program we built before to run the optimization pass
+on a given IR and obtain the result.
+
+- test_name.expected: The expected result of the test. This is a text file
+describing the IR that is expected to be generated for this test.
+
+3. Execution
+
+Once the tests have been generated the optimization-test script can be used
+to execute them. This will look for all the *.opt_test files, execute
+them and compare the resulting IR against the expected for each one. If the
+generated IR for a test does not match the expectation set by the test
+developer the test fails and reports the differences between both IRs in
+a diff-like format.
-- 
1.9.1