13.4. Adding Or Modifying Tests

Tests must be in a Python module whose name matches “suite_*.py”. The module must contain one or more subclasses with a name starting with "Test" something, for example "class TestDissectionHttp2:". Each test case method whose name starts with “test_” constitutes an individual test.

Success or failure conditions are signalled using regular assertions with the "assert" Python keyword.

Test dependencies (such as programs, directories, or the environment variables) are injected through method parameters. Commonly used fixtures include cmd_tshark and capture_file.

Processes (tshark, capinfos, etc.) are run using the "subprocess" Python module, or the Wireshark subprocesstest module with some convenience functions. Possible functions include subprocesstest.run(), subprocesstest.check_run() or creating subprocess.Popen object if the utility functions are not sufficient for some reason. Usually this is only required if two-way communication is performed with the child process. subprocesstest.check_run() is exactly the same as calling subprocesstest.run() with check=True as an argument, only a bit more expressive.

Check the documentation for the Python subprocess module for a full description of the arguments available to the subprocesstest.run() convenience wrapper and the subprocess.Popen object.

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.py::TestBasicClopts::test_existing_file”, which reads a capture file using TShark and checks its exit code.

import subprocesstest
import pytest

class TestBasicClopts:
    def test_existing_file(self, cmd_tshark, capture_file, test_env):
        subprocess.check_run((cmd_tshark, '-r', capture_file('dhcp.pcap')), env=test_env)

Output can be checked using assert subprocesstest.grep_output(), assert subprocesstest.count_output() or any other assert statement. subprocesstest.check_run() also asserts that the child process returns the value 0 as exit code.

import subprocesstest
import pytest

class TestDecrypt80211:
    def test_80211_wpa_psk(self, cmd_tshark, capture_file, test_env):
        tshark_proc = subprocesstest.run((cmd_tshark,
                '-o', 'wlan.enable_decryption: TRUE',
                '-e', 'http.request.uri',
                '-r', capture_file('wpa-Induction.pcap.gz'),
                '-Y', 'http',
            ), capture_output=True, env=test_env)
        assert 'favicon.ico' in tshark_proc.stdout

Tests can be run in parallel. This means that any files you create must be unique for each test. Filenames based on the current test name are generated using fixtures such as "capture_file" and "result_file". By default pytest generates paths in the system’s temporary directory and the last three pytest runs are kept. Temporary files from older runs are automatically deleted.