Understanding pytest Hook Functions: Lifecycle, Common Hooks, and Practical Examples

Hook functions, also known as callbacks, are executed when specific events occur in pytest, allowing developers to customize the testing process.

pytest provides a comprehensive lifecycle with phases such as the initialization stage, collection stage, execution stage, debugging, and reporting, each exposing various hook functions.

Key hooks in the initialization stage include pytest_load_initial_conftests , pytest_cmdline_preparse , pytest_cmdline_parse , pytest_cmdline_main , pytest_fixture_setup , and pytest_fixture_post_finalizer .

During the configuration stage, hooks like pytest_addoption , pytest_addhooks , pytest_configure , pytest_unconfigure , pytest_sessionstart , pytest_sessionfinish , and pytest_plugin_registered are available.

The collection stage offers hooks such as pytest_collection , pytest_collect_directory , pytest_collect_file , pytest_pycollect_makemodule , pytest_pycollect_makeitem , pytest_generate_tests , pytest_deselected , pytest_make_parametrize_id , pytest_collection_modifyitems , and pytest_collection_finish .

Execution‑stage hooks include pytest_runtestloop , pytest_runtest_protocol , pytest_runtest_logstart , pytest_runtest_logfinish , pytest_runtest_setup , pytest_runtest_call , pytest_runtest_teardown , pytest_runtest_makereport , and pytest_pyfunc_call .

Debugging and interaction hooks such as pytest_internalerror , pytest_keyboard_interrupt , pytest_exception_interact , and pytest_enter_pdb enable custom error handling.

Reporting hooks like pytest_collectstart , pytest_make_collect_report , pytest_itemcollected , pytest_collectreport , pytest_report_header , pytest_report_collectionfinish , pytest_report_teststatus , and pytest_terminal_summary allow modification of test output.

Common pytest objects used in hooks include session , Item , metafunc , and config .

Practical examples demonstrate adding custom command‑line options, dynamic parametrization, logging setup/teardown phases, custom marker filtering, and improving console output, with code snippets such as:

# conftest.py
import pytest

def pytest_addoption(parser):
    parser.addoption("--cmdopt", action="store", default="None",
                     help="Add '--cmdopt' value to pytest config")
    parser.addoption("--flag", action="store_true", default=False,
                     help="Add boolean '--flag' to pytest config")

@pytest.fixture(scope='function')
def cmdopt(pytestconfig):
    return pytestconfig.getoption('--cmdopt')

@pytest.fixture(scope='function')
def flag(pytestconfig):
    return pytestconfig.getoption('--flag')

# test_conftest.py
def test01(cmdopt, flag):
    print('\n --cmdopt value:', cmdopt)
    print('\n --flag value:', flag)

# conftest.py
test_data = [{"test_input": "3+5", "expected": 8, "id": "verify 3+5=8"},
             {"test_input": "2+4", "expected": 6, "id": "verify 2+4=6"},
             {"test_input": "6 * 9", "expected": 42, "id": "verify 6*9=42"}]

def pytest_generate_tests(metafunc):
    if "parameters" in metafunc.fixturenames:
        ids = [d['id'] for d in test_data]
        metafunc.parametrize("parameters", test_data, ids=ids, scope="function")

# conftest.py
@pytest.hookimpl(hookwrapper=True, tryfirst=True)
def pytest_runtest_makereport(item, call):
    out = yield
    report = out.get_result()
    print(report.when, report.nodeid, report.outcome)

These examples illustrate how hook functions can be leveraged for extensive pytest customization and extension.