[PATCH] Document for how to write a test case

[Masatake YAMATO]

* doc/HACKING-testcase: new file.
---
 doc/HACKING-testcase | 88 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 doc/HACKING-testcase

diff --git a/doc/HACKING-testcase b/doc/HACKING-testcase
new file mode 100644
index 000000000..e6f8c666b
--- /dev/null
+++ b/doc/HACKING-testcase
@@ -0,0 +1,88 @@
+How to write a case testing strace
+========================================================================
+1. write a test case.
+
+   The case is run under strace when testing.
+
+   Test driver evaluates output of the case and output of the
+   strace. The default driver, run_strace_match_diff() defined init.sh
+   just compares the two outputs; it reports "successfully" if the outputs
+   are the same.
+
+   Assume "mytest" is the name of the test case.
+   You must write "mytest.c" as its source code.
+
+   Functions defined in tests/tests.h help you write a test case.
+   You should know at least following functions:
+
+   For reporting an error
+
+      * perror_msg_and_fail()
+      * error_msg_and_fail()
+
+   For skipping the test case
+
+      * error_msg_and_skip()
+      * perror_msg_and_skip()
+
+   A test case returns 0 when it runs without an error.
+
+   A typical test case does two things once or more: calling a system
+   call and printing the expected output of strace that traces the
+   call. The test driver compares the expected output and actual
+   output of strace.
+
+2. put "mytest" to tests/pure_executables.list for building "mytest"
+   from "mytest.c".
+
+3. write the way to how to run "mytest" to tests/gen_tests.in.
+
+   The line in the file has the following format:
+
+      NAME<tab>[+TEST-DRIVER] [-STRACE-OPT...]
+
+   NAME is the name of the test case, "mytest" here.
+   TEST-DRIVER is the name of a test driver program. run_strace_match_diff(),
+   a shell function defined in init.sh, is used if +TEST-DRIVER is omitted.
+   STRACE-OPTs are passed to strace.
+
+4. build the test case
+
+   Maybe you must run bootstrap and configure as you do for building strace.
+   Then do (cd tests; make mytest mytest.gen.test).
+   mytest.gen.test is the test driver runs mytest under strace.
+
+5. run the test case
+
+   Do (cd tests; ./mytest.gen.test; echo $?)
+
+   "0" means successful.
+
+Related files
+========================================================================
+
+tests/mytest
+	the test case
+
+tests/mytest.c
+	the source of the test case
+
+tests/mytest.gen.test
+	the test driver running the test case
+	strace's build system may generate this one.
+
+tests/mytest.gen.dir/exp
+	the file where the strace's output goes
+
+tests/mytest.gen.dir/log
+	the file where the case's output goes
+
+tests/mytest.gen.dir/out
+	the file where the driver's output goes
+
+tests/init.sh
+	a library of shell functions used in the driver
+
+tests/tests.h
+	a header file declaring C functions for helping
+	writing a test case
-- 
2.35.1