Automated regression tests for librdkafka
=========================================


Using trivup to bring up a cluster
----------------------------------

    make trunk

or:

   ./interactive_broker_version.py trunk
   make


Old way using an existing cluster
--------------------------------
A local configuration file needs to be created to specify the broker address,
and possibly other rdkafka configuration properties:

    cp test.conf.example test.conf
    $EDITOR test.conf


Run specific tests
------------------

To run tests:

   # Run tests in parallel (quickest, but harder to troubleshoot)
   make

   # Run tests in sequence
   make run_seq

   # Run specific test
   TESTS=0004 make

   # Run test(s) with helgrind, valgrind, gdb
   TESTS=0009 ./run-test.sh ./merged valgrind|helgrind|gdb


All tests in the 0000-0999 series are run automatically with 'make'.

Tests 1000-1999 are subject to specific non-standard setups or broker
configuration, these tests are run with "TESTS=1xxx-yyyyy.test make".
See comments in the test's source file for specific requirements.


To insert test results into SQLite database make sure the 'sqlite3' utility
is installed, then add this to test.conf:

test.sql.command=sqlite3 rdktests



Automated broker cluster setup using trivup
===========================================

A local broker cluster can be set up using
[trivup](https://github.com/edenhill/trivup).
These self-contained clusters are used to run the librdkafka test suite
on a number of different broker versions or with specific broker configs.

trivup is a python package, either check out and install it
using `python setup.py install` in your virtualenv or grab it from PyPi.

The following sections rely on trivup being installed.


Compatbility tests with multiple broker versions
================================================

To ensure compatibility across all supported broker versions the entire
test suite is run in a trivup based cluster, one test run for each
relevant broker version.

 `./broker_version_tests.py`




SASL tests
==========

Testing SASL requires a bit of configuration on the brokers, to automate
this the entire test suite is run on a trivup based cluster.

 `./sasl_tests.py`



Full test suite(s) run
======================

To run all tests, including the broker version and SASL tests, etc, use

 `make full`

**NOTE**: Passing the full test run is a prerequisite to
          checking in any code / filing a PR.



Manual testing notes
====================

The following manual tests are currently performed manually, they should be
implemented as automatic tests.

LZ4 interop
-----------

 `./interactive_broker_version.py -c ./lz4_manual_test.py 0.8.2.2 0.9.0.1 trunk`

 Check the output and follow the instructions.



Trivup root path
================

The trivup download and run-time root defaults to 'tmp' (in current directory),
the interactive_broker_version.py script takes a '-root <dir>' option and
all trivup based scripts (in tests/) honour the TRIVUP_ROOT environment
variable.