include the test.sh doc into the nobug book
authorChristian Thaeter <ct@pipapo.org>
Wed, 18 Aug 2010 13:42:42 +0000 (15:42 +0200)
committerChristian Thaeter <ct@pipapo.org>
Wed, 18 Aug 2010 13:42:42 +0000 (15:42 +0200)
temporary disables the standalone doc generation

Makefile.am
doc/nobug_manual.conf
tests/test.sh

index 8f06707..6386df8 100644 (file)
@@ -79,14 +79,15 @@ include tests/Makefile.am
 CLEANFILES     += nobug_manual.txt
 EXTRA_DIST     += pipadoc doc/nobug_manual.conf doc/asciidoc.pawk doc/verbatim.pawk
 
-manual_ASCIIDOCS = \
-       $(include_HEADERS) \
-       $(libnobugmt_la_SOURCES) \
+manual_ASCIIDOCS =                             \
+       tests/test.sh                           \
+       $(include_HEADERS)                      \
+       $(libnobugmt_la_SOURCES)                \
        $(nobug_rbdump_SOURCES)
 
-nobug_manual.txt: doc/nobug_manual.conf doc/asciidoc.pawk doc/verbatim.pawk $(manual_ASCIIDOCS) $(wildcard $(top_srcdir)/doc/*.txt) $(wildcard $(top_srcdir)/doc/*.conf)
+nobug_manual.txt: test_inc.txt doc/nobug_manual.conf doc/asciidoc.pawk doc/verbatim.pawk $(manual_ASCIIDOCS) $(wildcard $(top_srcdir)/doc/*.txt) $(wildcard $(top_srcdir)/doc/*.conf)
        @which gawk >/dev/null || ( echo "gawk not installed!"; exit 1; )
-       ( cd $(top_srcdir) ; ./pipadoc doc/nobug_manual.conf doc/asciidoc.pawk doc/verbatim.pawk        \
+       ( cd $(top_srcdir) ; COMRE='//' ./pipadoc doc/nobug_manual.conf doc/asciidoc.pawk doc/verbatim.pawk     \
                $(patsubst $(top_srcdir)/%,%,$(wildcard $(top_srcdir)/doc/*.txt))               \
                $(manual_ASCIIDOCS) ) >$(top_builddir)/nobug_manual.txt
 
@@ -102,10 +103,14 @@ nobug7.txt: doc/nobug7.conf doc/asciidoc.pawk doc/verbatim.pawk $(manual_ASCIIDO
 nobug.7: nobug7.txt
        a2x -f manpage nobug7.txt
 
-
-test_manual.txt: doc/asciidoc.pawk tests/test.sh
+test_inc.txt: doc/asciidoc.pawk doc/test_inc.conf tests/test.sh
        @which gawk >/dev/null || ( echo "gawk not installed!"; exit 1; )
-       ( cd $(top_srcdir); COM='#' ./pipadoc doc/asciidoc.pawk tests/test.sh ) >$(top_builddir)/test_manual.txt
+       ( cd $(top_srcdir);     \
+       COM='#' ./pipadoc doc/asciidoc.pawk doc/test_inc.conf tests/test.sh ) >$(top_builddir)/test_inc.txt
+
+#test_manual.txt: doc/asciidoc.pawk tests/test.sh
+#      @which gawk >/dev/null || ( echo "gawk not installed!"; exit 1; )
+#      ( cd $(top_srcdir); COM='#' ./pipadoc doc/asciidoc.pawk tests/test.sh ) >$(top_builddir)/test_manual.txt
 
 %.html: %.txt
        asciidoc -a toc $<
index bd7afed..af92260 100644 (file)
 
 //=rbdump
 
-//=testsuite
+NoBug maintains a `test.sh` script which drives extensive testsuites.
+Look at into the 'tests/' folder about how to apply this.
+
+//_ include::test_inc.txt[]
 
 //=bestpractices
 
index 884edb7..3d0dd36 100755 (executable)
 #intro A shell script driving software tests.
 #intro
 
-#=intro
-#=tests Writing tests
-# =run
-#=config
-#=configf
-# =make
-# =control
-#=valgrind
-#=libtool
-#_
-#_ Index
-#_ -----
-#_
-#=index
-#_
+# doc generation disabled here (temporary) for inclusion in the nobug manual
+# =intro
+# =tests Writing tests
+#  =run
+# =config
+# =configf
+#  =make
+#  =control
+# =valgrind
+# =libtool
+# _
+# _ Index
+# _ -----
+# _
+# =index
+# _
 
 LC_ALL=C
 
-#config HEAD- Configuration; configuration; configure tests
+#config HEAD~ Test Configuration; configuration, tests; configure tests
+#config
+#config Runtime behaviour of the testsuite can be configured by setting certain
+#config envirinment variables.
 #config
 #config PARA LOGSUPPRESS; LOGSUPPRESS; suppress certain lines from stderr
-#config  LOGSUPPRESS='^\(\*\*[0-9]*\*\* \)\?[0-9]\{10,\}: \(TRACE\|INFO\|NOTICE\|WARNING\|ERR\):'
+#config
+#config  LOGSUPPRESS='^[0-9]\{10,\}: \(TRACE\|INFO\|NOTICE\):'
 #config
 #config Programms sometimes emit additional diagnostics on stderr which is volatile and not necessary for
 #config validating the output the `LOGSUPRESS` variable can be set to a regex to filter this things out.
@@ -61,24 +66,33 @@ LC_ALL=C
 #config
 LOGSUPPRESS='^\(\*\*[0-9]*\*\* \)\?[0-9]\{10,\}[:!] \(TRACE\|INFO\|NOTICE\|WARNING\|ERR\):'
 
-#config PARA Resource Limits; ulimit; constrain resource limits
+#config HEAD^ Resource Limits; ulimit, tests; constrain test resource limits
+#config
 #config It is possible to set some limits for tests to protect the system against really broken cases.
 #config Since running under valgrind takes consinderable more resources there are separate variants for
 #config limits when running under valgrind.
+#config INDEX LIMIT_CPU; LIMIT_CPU; limit the cpu time
 #config
 #config  LIMIT_CPU=5
+#config
 #config Maximal CPU time the test may take after it will be killed with SIGXCPU. This protects agaist Lifelocks.
+#config INDEX LIMIT_TIME; LIMIT_TIME; limit the wall time
 #config
 #config  LIMIT_TIME=10
+#config
 #config Maximal wall-time a test may take after this it will be killed with SIGKILL. Protects against Deadlocks.
+#config INDEX LIMIT_VSZ; LIMIT_VSZ; limit virtual memory size
 #config
 #config  LIMIT_VSZ=524288
+#config
 #config Maximal virtual memory size the process may map, allocations/mappings will fail when this limit is reached.
 #config Protects against memory leaks.
+#config INDEX LIMIT_VG_*; LIMIT_VG_*; lmitation when running tests under valgrind
 #config
 #config  LIMIT_VG_CPU=20
 #config  LIMIT_VG_TIME=30
 #config  LIMIT_VG_VSZ=524288
+#config
 #config Same variables again with limits when running under valgrind.
 #config
 LIMIT_CPU=5
@@ -92,10 +106,11 @@ LIMIT_VG_VSZ=524288
 #configf HEAD~ Configuration Files; configuration files; define variables to configure the test
 #configf
 #configf `test.sh` reads config files from the following location if they are exist
-#configf * 'test.conf' from the current directory
-#configf * '$srcdir/test.conf' `$srcdir` is set by autotools
-#configf * '$srcdir/tests/test.conf' `tests/` is suspected as default directory for tests
-#configf * '$TEST_CONF' a user defineable variable to point to a config file
+#configf
+#configf  . 'test.conf' from the current directory
+#configf  . '$srcdir/test.conf' `$srcdir` is set by autotools
+#configf  . '$srcdir/tests/test.conf' `tests/` is suspected as default directory for tests
+#configf  . '$TEST_CONF' a user defineable variable to point to a config file
 #configf
 test -f 'test.conf' && source test.conf
 test -n "$srcdir" -a -e "$srcdir/test.conf" && source "$srcdir/test.conf"
@@ -109,6 +124,7 @@ TESTDIR="$(dirname "$arg0")"
 
 
 #libtool HEAD Libtool; libtool; support for libtool
+#libtool
 #libtool When test.sh detects the presence of './libtool' it runs all tests with
 #libtool `./libtool --mode=execute`.
 #libtool
@@ -117,17 +133,20 @@ if test -x ./libtool; then
     LIBTOOL_EX="./libtool --mode=execute"
 fi
 
-#valgrind HEAD- Valgrind; valgrind; valgrind support
+#valgrind HEAD~ Valgrind; valgrind; valgrind support
+#valgrind
 #valgrind Test are run under valgrind supervision by default, if not disabled.
 #valgrind
 #valgrind PARA VALGRINDFLAGS; VALGRINDFLAGS; control valgrind options
+#valgrind
 #valgrind  VALGRINDFLAGS="--leak-check=yes --show-reachable=yes"
 #valgrind
 #valgrind `VALGRINDFLAGS` define the options which are passed to valgrind. This can be used to override
 #valgrind the defaults or switching the valgrind tool. The special case `VALGRINDFLAGS=DISABLE` will disable
 #valgrind valgrind for the tests.
 #valgrind
-#valgrind HEAD~ Generating Valgrind Suppression Files; vgsuppression; ignore false positives
+#valgrind HEAD^ Generating Valgrind Suppression Files; vgsuppression; ignore false positives
+#valgrind
 #valgrind When there is a 'vgsuppression' executable in the current dir (build by something external) then
 #valgrind test.sh uses this to generate a local 'vgsuppression.supp' file and uses that to suppress
 #valgrind all errors generated by 'vgsuppression'. The Idea here is that one adds code which triggers known
@@ -230,20 +249,23 @@ function compare_template() # template plainfile
     } 3<"$1" 4<"$2"
 }
 
-#tests HEAD- Writing Tests; tests; how to write testsuites
+#tests HEAD- Testing; testing; how to write testsuites
+#tests
 #tests Tests are nothing more than bash scripts with some functions from the test.sh
 #tests framework defined. Test.sh looks in the current directory for all files which ending in .test
 #tests and runs them in alphabetical order. The selection of this tests can be constrained with the
 #tests `TESTSUITES` environment variable.
 #tests
 #tests HEAD~ Testsuites; test files; writing tests
-#tests It is common to start the name of the '.test' files with a 2 digi number to give them a proper
+#tests
+#tests It is common to start the name of the '.test' files with a 2 digit number to give them a proper
 #tests order: '10foo.test', '20bar.test' and so on. Each such test should only test a certain aspect of
 #tests the system. You have to select the testing binary with the `TESTING` function and then write
 #tests certain TEST's defining how the test should react. Since tests are shell scripts it is possible
 #tests to add some supplemental commands there to set and clean up the given test environment.
 #tests
-#tests HEAD^ TESTING; TESTING; set the test binary
+#tests PARA Select Test Executable; TESTING; set the test binary
+#tests
 #tests  TESTING "message" test_program
 #tests
 #tests Selects the test binary for the follwing tests, prints an informal message.
@@ -253,10 +275,6 @@ function compare_template() # template plainfile
 #tests  `test_program`::
 #tests    an existing program to drive the tests or a shell function
 #tests
-#tests ----
-#tests TESTING "Testing a.out" ./a.out
-#tests ----
-#tests
 function TESTING()
 {
     echo
@@ -266,10 +284,11 @@ function TESTING()
     TESTBIN="$2"
 }
 
-#tests HEAD^ TEST; TEST; single test
+#tests PARA Define a Test; TEST; single test
+#tests
 #tests  TEST "title" arguments.. <<END
 #tests
-#tests Runs a single test
+#tests Defines a single test
 #tests
 #tests  `title`::
 #tests    describes this test and is also used as identifier for this test,
@@ -283,86 +302,101 @@ function TESTING()
 #tests followed by a command, followed by a colon and a space, followed by additional arguments or
 #tests being an empty or comment line.
 #tests
-#tests
-#tests HEAD+ Test Commands; commands; define expected in and outputs
-#tests
-#tests PARA in; in; stdin data for a test
-#tests  in: text
-#tests
-#tests Send `text` to stdin of the test binary. If no `in:` commands are given, nothing is send to the
-#tests tests input.
-#tests
-#tests PARA out; out; expected stdout (regex) from a test
-#tests  out: regex
-#tests
-#tests Expect `regex` on stdout. This regexes have a 'triggering' semantic. That means it is tried to match
-#tests a given regex on as much lines as possible (`.*` will match any remaining output), if the match fails,
-#tests the next expected output line is tried. When that fails too the test is aborted and counted as failure.
-#tests
-#tests When no `out:` or `out-lit:` commands are given, then stdout is not checked, any output is ignored.
-#tests
-#tests PARA err; err; expected stderr (regex) from a test
-#tests  out: regex
-#tests
-#tests Same as 'out:' but expects data on stderr. When no `err:` or `err-lit:` commands are given, then stdout is
-#tests not checked, any output there is ignored.
-#tests
-#tests PARA out-lit; out-lit; expected stdout (literal) from a test
-#tests  out-lit: text
-#tests
-#tests Expect `text` on stdout, must match exactly or will fail.
-#tests
-#tests PARA err-lit; err-lit; expected stderr (literal) from a test
-#tests  err-lit: text
-#tests
-#tests Same as 'out-lit:' but expects data on stderr.
-#tests
-#tests PARA return; return; expected exit value of a test
-#tests  return: value
-#tests
-#tests Expects `value` as exit code of the tested program. The check can be negated by prepending the value with
-#tests an exclamation mark, `return: !0` expects any exist code except zero.
-#tests
-#tests If no `return:` command is given then a zero (success) return from the test program is expected.
-#tests
-#tests HEAD+ Conditional Tests; conditional tests; switch tests on conditions
-#tests Sometimes tests need to be adapted to the environment/platform they are running on. This can be archived
-#tests with common if-else-elseif-endif statements. This statements can be nested.
-#tests
-#tests PARA if; if; conditional test
-#tests  if: check
-#tests
-#tests Executes `check` as shell command, if its return is zero (success) then the following test parts are used.
-#tests
-#tests PARA else; else; conditional alternative
-#tests  else:
-#tests
-#tests If the previous `if` failed then the following test parts are included in the test, otherwise they
-#tests are excluded.
-#tests
-#tests PARA elseif; elseif; conditional alternative with test
-#tests  elseif: check
-#tests
-#tests Composition of else and if, only includes the following test parts if the if's and elseif's before failed
-#tests and `check` succeeded.
-#tests
-#tests PARA endif; endif; end of conditonal test part
-#tests  endif:
-#tests
-#tests Ends an `if` statement.
-#tests
-#tests HEAD+ Other Elements;;
-#tests
-#tests PARA msg; msg; print a diagnostic message
-#tests  msg: message..
-#tests
-#tests Prints `message` while processing the test suite.
-#tests
-#tests PARA comments; comments; adding comments to tests
-#tests  # anything
-#tests
-#tests Lines starting with the hash mark and empty lines count as comment and are not used.
-#tests
+#testcmds HEAD^ Test Commands; commands; define expected in and outputs
+#testcmds
+#testcmds
+#testcmds
+#testcmds
+#testcmds PARA in; in; stdin data for a test
+#testcmds
+#testcmds  in: text
+#testcmds
+#testcmds Send `text` to stdin of the test binary. If no `in:` commands are given, nothing is send to the
+#testcmds tests input.
+#testcmds
+#testcmds PARA out; out; expected stdout (regex) from a test
+#testcmds
+#testcmds  out: regex
+#testcmds
+#testcmds Expect `regex` on stdout. This regexes have a 'triggering' semantic. That means it is tried to match
+#testcmds a given regex on as much lines as possible (`.*` will match any remaining output), if the match fails,
+#testcmds the next expected output line is tried. When that fails too the test is aborted and counted as failure.
+#testcmds
+#testcmds When no `out:` or `out-lit:` commands are given, then stdout is not checked, any output is ignored.
+#testcmds
+#testcmds PARA err; err; expected stderr (regex) from a test
+#testcmds
+#testcmds  out: regex
+#testcmds
+#testcmds Same as 'out:' but expects data on stderr. When no `err:` or `err-lit:` commands are given, then stdout is
+#testcmds not checked, any output there is ignored.
+#testcmds
+#testcmds PARA out-lit; out-lit; expected stdout (literal) from a test
+#testcmds
+#testcmds  out-lit: text
+#testcmds
+#testcmds Expect `text` on stdout, must match exactly or will fail.
+#testcmds
+#testcmds PARA err-lit; err-lit; expected stderr (literal) from a test
+#testcmds
+#testcmds  err-lit: text
+#testcmds
+#testcmds Same as 'out-lit:' but expects data on stderr.
+#testcmds
+#testcmds PARA return; return; expected exit value of a test
+#testcmds
+#testcmds  return: value
+#testcmds
+#testcmds Expects `value` as exit code of the tested program. The check can be negated by prepending the value with
+#testcmds an exclamation mark, `return: !0` expects any exist code except zero.
+#testcmds
+#testcmds If no `return:` command is given then a zero (success) return from the test program is expected.
+#testcmds
+#testcmds HEAD^ Conditional Tests; conditional tests; switch tests on conditions
+#testcmds
+#testcmds Sometimes tests need to be adapted to the environment/platform they are running on. This can be archived
+#testcmds with common if-else-elseif-endif statements. This statements can be nested.
+#testcmds
+#testcmds PARA if; if; conditional test
+#testcmds
+#testcmds  if: check
+#testcmds
+#testcmds Executes `check` as shell command, if its return is zero (success) then the following test parts are used.
+#testcmds
+#testcmds PARA else; else; conditional alternative
+#testcmds
+#testcmds  else:
+#testcmds
+#testcmds If the previous `if` failed then the following test parts are included in the test, otherwise they
+#testcmds are excluded.
+#testcmds
+#testcmds PARA elseif; elseif; conditional alternative with test
+#testcmds
+#testcmds  elseif: check
+#testcmds
+#testcmds Composition of else and if, only includes the following test parts if the if's and elseif's before failed
+#testcmds and `check` succeeded.
+#testcmds
+#testcmds PARA endif; endif; end of conditonal test part
+#testcmds
+#testcmds  endif:
+#testcmds
+#testcmds Ends an `if` statement.
+#testcmds
+#testcmds HEAD^ Other Elements;;
+#testcmds
+#testcmds PARA msg; msg; print a diagnostic message
+#testcmds
+#testcmds  msg: message..
+#testcmds
+#testcmds Prints `message` while processing the test suite.
+#testcmds
+#testcmds PARA comments; comments; adding comments to tests
+#testcmds
+#testcmds  # anything
+#testcmds
+#testcmds Lines starting with the hash mark and empty lines count as comment and are not used.
+#testcmds
 function TEST()
 {
         name="$1"
@@ -571,7 +605,8 @@ function TEST()
         fi
 }
 
-#tests HEAD^ PLANNED; PLANNED; deactivated test
+#tests PARA Planned Tests; PLANNED; deactivated test
+#tests
 #tests  PLANNED "title" arguments.. <<END
 #tests
 #tests Skip a single test.