113 lines
4.7 KiB
Plaintext
113 lines
4.7 KiB
Plaintext
This a test suite of small "unit tests" that verify individual pieces of ZeekCtl
|
|
functionality. They all utilize BTest, a simple framework/driver for
|
|
writing unit tests. More information about BTest can be found at
|
|
http://www.zeek.org/development/README.btest.html
|
|
|
|
The test suite's BTest configuration is handled through the
|
|
``btest.cfg`` file. Of particular interest is the "TestDirs" settings,
|
|
which specifies which directories BTest will recursively search for
|
|
test files.
|
|
|
|
Significant Subdirectories
|
|
==========================
|
|
|
|
* Baseline/
|
|
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.
|
|
|
|
* Traces/
|
|
Packet captures utilized by the various BTest tests.
|
|
|
|
* Cfg/
|
|
This is a collection of config files utilized by various BTest tests.
|
|
The directory hierarchy emulates the hierarchy of the Zeek installation
|
|
directory.
|
|
|
|
Running Tests
|
|
=============
|
|
|
|
In order to run the tests you must clone the entire Zeek repo (not just the
|
|
zeekctl repo). Next, either use the ``make all`` or ``make brief``
|
|
``Makefile`` targets to run all the tests (these will automatically build
|
|
Zeek before running any of the zeekctl tests). If Zeek fails to build, you can
|
|
define an environment variable ZEEKCTL_TEST_BUILDARGS which specifies
|
|
additional options that will be passed to Zeek's "configure" script.
|
|
If Zeek builds successfully, but one or more tests fail, then you can
|
|
re-run all failed tests with ``make rerun``.
|
|
|
|
If you want to run just a subset of the tests, then build Zeek with
|
|
``make buildzeek``, followed by ``btest`` directly with desired
|
|
options/arguments. Examples:
|
|
|
|
* 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.
|
|
|
|
|
|
* btest <btest options> 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 command" will run all of the zeekctl
|
|
command unit tests.
|
|
|
|
|
|
* btest <btest options> test_directory/test_file
|
|
You can specify a single test file to run just that test. This
|
|
is useful when testing a single failing test or when developing
|
|
a new test.
|
|
|
|
How The Tests Work
|
|
==================
|
|
|
|
The zeekctl testsuite uses btest, but not all test artifacts reside in each
|
|
test's subdirectory below .tmp/. Instead, the tests use the Zeek build created
|
|
as described above, copying it into per-test subdirectories to achieve isolation
|
|
of config tweaks. Those directories are $ZEEKCTLSRCDIR/build/testing/test.<num>,
|
|
where $ZEEKCTLSRCDIR is the parent of the directory this README resides
|
|
in. Inspect the generated cluster-layout.zeek and other resulting scripts in
|
|
those directory trees.
|
|
|
|
The tests normally wipe these temporary directories. btest.cfg provides a
|
|
"debug" environment ("btest -a debug" ...) that preserves them. The individual
|
|
test's .stdout/stderr files contain enough information to tell you which of
|
|
those temporary directories they relied on.
|
|
|
|
In many cases, zeekctl's tests don't actually run Zeek. Instead, they run a
|
|
Python stub script, ./Cfg/bin/zeek__test, to allow controlled injection of
|
|
failure modes. This is why you don't see rampant listening-port collisions when
|
|
running this testsuite.
|
|
|
|
A subset of tests is serialized at the btest level via @TEST-SERIALIZE -- those
|
|
are tests that require actual listening ports.
|
|
|
|
Adding Tests
|
|
============
|
|
|
|
See either the `BTest documentation
|
|
<http://www.zeek.org/development/README.btest.html>`_ or the existing unit
|
|
tests for examples of what they actually look like. The essential
|
|
components of a new test include:
|
|
|
|
* A test file in one of the subdirectories listed in the ``TestDirs``
|
|
of the ``btest.cfg`` file.
|
|
|
|
* If the unit test requires a known-good baseline output against which
|
|
future tests will be compared (via ``btest-diff``), then that baseline
|
|
output will need to live in the ``Baseline`` directory. Manually
|
|
adding that is possible, but it's easier to just use the ``-u`` or
|
|
``-U`` options of ``btest`` to do it for you (using ``btest -d`` on a
|
|
test for which no baseline exists will show you the output so it can
|
|
be verified first before adding/updating the baseline output).
|
|
|
|
If you create a new top-level testing directory for collecting related
|
|
tests, then 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.
|
|
|
|
Note that any new test you add this way will automatically be included
|
|
in the testing done in Zeek's central automated build & test
|
|
environment.
|