zeek/testing/btest

BTest is simple framework for writing unit tests. Each test consists of a set
of command lines that will be executed, and success is determined based on
their exit codes. In addition, output can optionally be compared against a
previously established baseline.

More information about BTest can be found at http://www.icir.org/robin/btest/


This README contains the following sections:
	* Contents of the testing/btest/ directory
	* Running tests
	* Adding tests


Contents of the testing/btest/ directory:

Baseline/*/
	The validated baselines for comparison against the output of each test on
	future runs. If the new output differs from the Baseline output, then the
	test fails.

Scripts/
	Shell scripts invoked by BTest to support testing.

Traces/
	Packet captures utilized by the various BTest tests.

logging/
	Tests to validate the logging framework.

policy/
	Tests of the functionality of Bro's bundled policy scripts.

software/
	Tests to validate Bro software not tested elsewhere.

btest.cfg
	Configuration file that specifies run-time settings for BTest. Of particular
	interest is the "TestDirs" settings, which specifies which directories BTest
	will recursively search for test files.


Running tests:

btest  <no arguments>
	If you simply execute btest in this directory with no arguments, then all
	directories listed as "TestDirs" in btest.cfg will be searched recursively
	for	test files. This is how the NMI automated build & test environment
	invokes BTest to run all tests.


btest  test_directory
	You can specify a directory on the command line to run just the tests
	contained in that directory. This is useful if you wish to run all of a
	given type of test, without running all the tests there are. For example,
	"btest policy" will run all of the tests for Bro's bundled policy scripts.


btest  test_directory/test_file
	You can specify a single test file to run just that test. This is useful
	when testing a single aspect of Bro functionality, and also when developing
	a new test.



Adding tests:

See the documentation at http://www.icir.org/robin/btest/ for information on
what BTests actually look like.

The essential components of a new test include:
* A test file in a subdirectory of /testing/btest. This can be a sub-sub-
	directory, as the search for test files is recursive from the directories
	listed as "TestDirs" in btest.cfg
* A baseline for the output of your test. Although the baseline will be stored
	in testing/btest/Baseline/ you should allow btest to copy the correct files
	to that location, rather than copying them manually (see below).

If you create a new subdirectory from testing/btest you'll need to add it to the
list of "TestDirs" in btest.cfg. Do this only if your test really doesn't fit
logically in any of the extant directories.

While developing your test, you can specify the "-t" command-line option to make
BTest preserve the testing/btest/.tmp directory. This directory holds the output
from your test run; you can inspect it in place to ensure it is correct and as
expected.

Once you are satisfied with the results in testing/btest/.tmp you can make BTest
store this output as the Baseline for the test by specifying the "-U" command-
line option.

When you are ready to commit your test to git, be sure the testing/btest/.tmp
directory is deleted, and use "git status" to ensure you correctly identify all
of the files that should be committed to the repository.

Note that any new test you add this way will automatically be included in the
testing done in the NMI automated build & test environment.