13.5. Adding Or Modifying Tests

Tests must be in a Python module whose name matches “suite_*.py”. The module must contain one or more subclasses of “SubprocessTestCase” or “unittest.TestCase”. “SubprocessTestCase” is recommended since it contains several convenience methods for running processes, normalizing and checking output, and displaying error information. Each test case method whose name starts with “test_” constitutes an individual test.

Success or failure conditions can be signalled using the “unittest.assertXXX()” or “subprocesstest.assertXXX()” methods.

Test dependencies (such as programs, directories, or the environment variables) are injected through method parameters. Commonly used fixtures include cmd_tshark and capture_file. See also Section 13.2.3, “pytest fixtures”.

The “subprocesstest” class contains the following methods for running processes. Stdout and stderr is written to “<test id>.log”:

Start a process without waiting for it to finish.
Start a process and wait for it to finish.
Start a process, wait for it to finish, and check its exit code.

All of the current tests run one or more of Wireshark’s suite of executables and either check their return code or their output. A simple example is “suite_clopts.case_basic_clopts.test_existing_file”, which reads a capture file using TShark and checks its exit code.

import subprocesstest
import fixtures

class case_basic_clopts(subprocesstest.SubprocessTestCase):
    def test_existing_file(self, cmd_tshark, capture_file):
        self.assertRun((cmd_tshark, '-r', capture_file('dhcp.pcap')))

Program output is decoded as UTF-8 and CRLF sequences (\r\n) are converted to LFs (\n). Output can be checked using SubprocessTestCase.grepOutput, SubprocessTestCase.countOutput or other unittest.assert* methods:

import subprocesstest
import fixtures

class case_decrypt_80211(subprocesstest.SubprocessTestCase):
    def test_80211_wpa_psk(self, cmd_tshark, capture_file):
        tshark_proc = self.assertRun((cmd_tshark,
                '-o', 'wlan.enable_decryption: TRUE',
                '-e', 'http.request.uri',
                '-r', capture_file('wpa-Induction.pcap.gz'),
                '-Y', 'http',
        self.assertIn('favicon.ico', tshark_proc.stdout_str)

Tests can be run in parallel. This means that any files you create must be unique for each test. “subprocesstest.filename_from_id” can be used to generate a filename based on the current test name. It also ensures that the file will be automatically removed after the test has run.