* src/tests/examples.README,examples.Makefile: out of date, removed.

* src/tests/README: details on running tests.
* cpp/README: Point to src/tests/README
* src/tests/ .valgrind.supp, .valgrindrc-default: moved valgrind options to file, easier to modify locally updated suppressions (see README)
* src/tests/test_env, run-unit-tests: more flexible test running (see README)


git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk@524913 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 71 insertions, 0 deletions

diff --git a/qpid/cpp/src/tests/README b/qpid/cpp/src/tests/README
new file mode 100644
index 0000000000..d0552a2ddd
--- /dev/null
+++ b/qpid/cpp/src/tests/README
@@ -0,0 +1,71 @@
+= Running Qpid C++ tests =
+
+General philosophy is that "make check" run all tests by default, but
+developers can run tests selectively as explained below.
+
+== Valgrind ==
+
+By default we run tests under valgrind to detect memory errors if valgrind
+is present. ./configure --disable-valgrind will disable it.
+
+Default valgrind options are specified in .valgrindrc-default, which a
+checked-in file. The actual options used are in .valgrindrc which is a
+local file. Normally it is a copy of valgrindrc-default but you can
+modify at will.
+
+Supressed errors are listed in .valgrind.supp. If you want to change
+suppressions for local testing, just modify .valgrindrc to point to a
+different file. Do NOT add suppressions to .valgrindrc.supp unless
+they are known problems outside of Qpid that can't reasonably be
+worked around in Qpid.
+
+
+== Unit Tests ==
+
+Unit tests shared libraries containing CppUnit test plug-ins, run by
+the CppUnit DllPlugInTester program.
+
+run-unit-tests runs tests under valgrind, you can run it directly.
+Library names (without path or .so) and CppUnit test paths can be
+specified on the command line or in env var UNIT_TESTS. For example:
+
+Selected test classes:
+./run-unit-tests ValueTest ClientChannelTest
+
+Individual test method
+./run-unit-tests ValueTest :ValueTest::testStringValueEquals
+
+You can also Build and run selected tests via make:
+make check TESTS=run-unit-tests UNIT_TESTS=ClientChannelTest
+
+NOTE: If you use DllPlugInTester directly note that if foobar.so is in
+the current directory then this will fail with "can't load plugin":
+ # DllPluginTester foobar.so
+
+Instead you need to say:
+ # DllPluginTester ./foobar.so
+
+DllPluginTester uses dlopen() which only searches for shlibs
+in the standard places unless the filename contains a "/".  In that
+case it just tries to open the filename.
+
+== System Tests ==
+
+System tests are self contained AMQP client executables or scripts.
+They are listed in the TESTS make variable, which can be over-ridden.
+
+The ./start_broker "test" launches the broker, ./kill_broker" kills it.
+Tests in between assume the broker is running.
+
+./run-python-tests: runs ../python/run_tests. This is the main set of
+system testss for the broker.
+
+Other C++ client test executables and scripts under client/test are
+system tests for the client.
+
+By setting TESTS in a make command you can run a different subset of tests
+against an already-running broker.
+
+
+
+