diff --git a/changelog/11307.doc.rst b/changelog/11307.doc.rst new file mode 100644 index 00000000000..fd9702e3d23 --- /dev/null +++ b/changelog/11307.doc.rst @@ -0,0 +1 @@ +Document that ``@pytest.hookimpl(specname=...)`` only works for function names starting with ``pytest_``. diff --git a/doc/en/how-to/writing_hook_functions.rst b/doc/en/how-to/writing_hook_functions.rst index d5d6d2ae4f7..784e0e164eb 100644 --- a/doc/en/how-to/writing_hook_functions.rst +++ b/doc/en/how-to/writing_hook_functions.rst @@ -161,6 +161,16 @@ Here is the order of execution: It's possible to use ``tryfirst`` and ``trylast`` also on hook wrappers in which case it will influence the ordering of hook wrappers among each other. +.. note:: + + pytest only searches for hook implementations whose names start with + ``pytest_``. The ``specname`` argument to ``@pytest.hookimpl`` can be used + to give an implementation a different suffix, for example + ``pytest_collection_modifyitems_tryfirst``, but the function name still + needs to start with ``pytest_``. A hook implementation named + ``my_collection_modifyitems`` is ignored even if it is decorated with + ``@pytest.hookimpl(specname="pytest_collection_modifyitems")``. + .. _`declaringhooks`: Declaring new hooks