:py:mod:`pytest_flakefighters.plugin`
=====================================

.. py:module:: pytest_flakefighters.plugin

.. autoapi-nested-parse::

   This module implements the DeFlaker algorithm [Bell et al. 10.1145/3180155.3180164] as a pytest plugin.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   pytest_flakefighters.plugin.RerunStrategy
   pytest_flakefighters.plugin.FlakeFighterPlugin




.. py:class:: RerunStrategy


   Bases: :py:obj:`enum.Enum`

   Enum for supported test rerunning strategies.
   :cvar ALL: Rerun all tests, regardless of outcome.
   :cvar FLAKY_FAILURE: Rerun failing tests marked as flaky.
   :cvar PREVIOUS_FLAKY: Rerun tests that have previously been marked as flaky as well as newly failing flaky tests.

   .. py:attribute:: ALL
      :value: 'ALL'

      

   .. py:attribute:: FLAKY_FAILURE
      :value: 'FLAKY_FAILURE'

      

   .. py:attribute:: PREVIOUSLY_FLAKY
      :value: 'PREVIOUSLY_FLAKY'

      


.. py:class:: FlakeFighterPlugin(root: str, database: pytest_flakefighters.database_management.Database, cov: Union[coverage.Coverage, pytest_flakefighters.function_coverage.Profiler], flakefighters: list[pytest_flakefighters.flakefighters.abstract_flakefighter.FlakeFighter], save_run: bool = True, rerun_strategy: RerunStrategy = RerunStrategy.FLAKY_FAILURE, display_outcomes: int = 0, display_verdicts: bool = False)


   The main plugin to manage the various FlakeFighter tools.

   .. py:method:: pytest_sessionstart(session: pytest.Session)

      Start the coverage measurement before tests are collected so we measure class and method definitions as covered.
      :param session: The session.


   .. py:method:: pytest_collection_finish(session: pytest.Session)

      Stop the coverage measurement after tests are collected.
      :param session: The session.


   .. py:method:: pytest_runtest_call(item: pytest.Item)

      Start the coverage measurement and label the coverage for the current test, run the test,
      then stop coverage measurement.

      :param item: The item.


   .. py:method:: pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo)

      Called after a test execution call (setup, call, teardown)
      to create a TestReport.

      :param item: The item.
      :param call: The call info.


   .. py:method:: pytest_runtest_protocol(item: pytest.Item, nextitem: pytest.Item) -> bool

      Rerun flaky tests. Follows a similar control logic to the pytest-rerunfailures plugin.

      :param item: The item.
      :param nextitem: The next item.

      :return: The return value is not used, but only stops further processing.


   .. py:method:: pytest_report_teststatus(report: pytest.TestReport, config: pytest.Config) -> tuple[str, str, str]

      Report flaky failures as such.
      :param report: The report object whose status is to be returned.
      :param config: The pytest config object.
      :returns: The test status.


   .. py:method:: pytest_runtestloop(session: pytest.Session)

      Run postprocessing flakefighters.
      :param session: The pytest session object.


   .. py:method:: pytest_json_modifyreport(json_report: dict)

      Add flakefighter results to the pytest-json-report report.

      :param json_report: The report dict.


   .. py:method:: build_outcome_string(test: pytest_flakefighters.database_management.Test) -> str

      Construct a string to represent previous flakefighter outcomes for a given test and its associated executions.

      :param test: The test case.


   .. py:method:: modify_xml(xml_path: str)

      Modify the JUnitXML file to add the flakefighter results for each test.

      :param xml_path: The path of the saved XML file.


   .. py:method:: pytest_html_results_summary(prefix: list, summary: list, postfix: list)

      Add the test-level flakefighter results.
      :param prefix: The prefix content. UNUSED.
      :param summary: The summary content. UNUSED.
      :param postfix: The postfix content.


   .. py:method:: pytest_sessionfinish(session: pytest.Session, exitstatus: pytest.ExitCode) -> None

      Called after whole test run finished, right before returning the exit status to the system.
      :param session: The pytest session object.
      :param exitstatus: The status which pytest will return to the system.