pytest-dev/pytest · critical · NotImplementedError

runtest must be implemented by Item subclass

Error message

runtest must be implemented by Item subclass

What it means

Item.runtest is abstract; the base implementation raises NotImplementedError to force every Item subclass to override it. Collection succeeds, but executing the item fails at runtest() because pytest has no way to run an arbitrary test object.

Source

Thrown at src/_pytest/nodes.py:721

        if problems:
            warnings.warn(
                f"{cls.__name__} is an Item subclass and should not be a collector, "
                f"however its bases {problems} are collectors.\n"
                "Please split the Collectors and the Item into separate node types.\n"
                "Pytest Doc example: https://docs.pytest.org/en/latest/example/nonpython.html\n"
                "example pull request on a plugin: https://github.com/asmeurer/pytest-flakes/pull/40/",
                PytestWarning,
            )

    @abc.abstractmethod
    def runtest(self) -> None:
        """Run the test case for this item.

        Must be implemented by subclasses.

        .. seealso:: :ref:`non-python tests`
        """
        raise NotImplementedError("runtest must be implemented by Item subclass")

    def add_report_section(self, when: str, key: str, content: str) -> None:
        """Add a new report section, similar to what's done internally to add
        stdout and stderr captured output::

            item.add_report_section("call", "stdout", "report section contents")

        :param str when:
            One of the possible capture states, ``"setup"``, ``"call"``, ``"teardown"``.
        :param str key:
            Name of the section, can be customized at will. Pytest uses ``"stdout"`` and
            ``"stderr"`` internally.
        :param str content:
            The full contents as a string.
        """
        if content:
            self._report_sections.append((when, key, content))

View on GitHub (pinned to 98b357f69e)

Solutions

1. Implement def runtest(self) -> None: in your Item subclass with the actual test execution logic
2. If subclassing for collection only, inherit from Collector instead of Item

Example fix

// before
class MyItem(pytest.Item):
    def collect(self): ...
// after
class MyItem(pytest.Item):
    def runtest(self):
        # run the actual test
        ...
    def collect(self): ...

def assert_item_has_runtest(item_cls):
    if 'runtest' not in item_cls.__dict__:
        raise NotImplementedError(f"{item_cls.__name__} must implement runtest()")

def implements_runtest(cls) -> bool:
    return 'runtest' in cls.__dict__

When it happens

Trigger: Defining a custom Item subclass (non-python test plugin) and forgetting to implement runtest; collection succeeds then the item errors during the call phase.

Common situations: Writing a pytest plugin for a non-Python language/tests per the 'nonpython' example; incomplete subclass; copy of an example with runtest deleted.

Related errors

• config or parent must be provided
• session or parent must be provided
• nodeid or parent must be provided
• config is not a valid argument for from_parent
• session is not a valid argument for from_parent

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/39291be2ad38e34d.json. Report an issue: GitHub.