13.2. Test suite structure

The following sections describes how the test suite is organized.

13.2.1. Test Coverage And Availability

The testing framework can run programs and check their stdout, stderr, and exit codes. It cannot interact with the Wireshark UI. Tests cover capture, command line options, decryption, file format support and conversion, Lua scripting, and other functionality.

Available tests depend on the libraries with which Wireshark was built. For example, some decryption tests depend on a minimum version of Libgcrypt and Lua tests depend on Lua.

Capture tests depend on the permissions of the user running the test script. We assume that the test user has capture permissions on Windows and macOS and capture tests are enabled by default on those platforms.

If a feature is unavailable, the test will be skipped. For example, if an old version of Libgcrypt is in use, then some decryption tests will be skipped while other tests can still run to completion.

13.2.2. Suites, Cases, and Tests

The test/test.py script uses Python’s “unittest” module. Our tests are patterned after it, and individual tests are organized according to suites, cases, and individual tests. Suites correspond to python modules that match the pattern “suite_*.py”. Cases correspond to one or more classes in each module, and case class methods matching the pattern ”test_*” correspond to individual tests. For example, the invalid capture filter test in the TShark capture command line options test case in the command line options suite has the ID “suite_clopts.case_tshark_capture_clopts.test_tshark_invalid_capfilter”.

13.2.3. pytest fixtures

A test has typically additional dependencies, like the path to an executable, the path to a capture file, a configuration directory, the availability of an optional library, and so on. The Python unittest library is quite limited in expressing test dependencies, these are typically specified on the class instance itself (self) or via globals.

pytest is a better test framework which has full parallelization support (test-level instead of just suite-level), provides nicer test reports, and allows modular fixtures. Ideally the test suite should fully switch to pytest, but in meantime a compatibility layer is provided via the “fixtures” module.

A fixture is a function decorated with @fixtures.fixture and can either call fixtures.skip("reason") to skip tests that depend on the fixture, or return/yield a value. Test functions (and other fixture functions) can receive the fixture value by using the name of the fixture function as function parameters. Common fixtures are available in fixtures_ws.py and includes cmd_tshark for the path to the tshark executable and capture_file for a factory function that produces the path to a capture file.

Each unittest test case must be decorated with @fixtures.uses_fixtures to ensure that unittest test classes can actually request fixture dependencies.