diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 06e6b16c..68a5f2f2 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -12,7 +12,7 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: ${{ github.ref != github.event.repository.default_branch }} + cancel-in-progress: ${{ ! contains(github.ref, github.event.repository.default_branch) }} jobs: build_docs: diff --git a/docs/deprecations.rst b/docs/deprecations.rst new file mode 100644 index 00000000..eaa8d07a --- /dev/null +++ b/docs/deprecations.rst @@ -0,0 +1,163 @@ +User Guide +========== + +Deprecation policy +------------------ + +If not otherwise explicitly stated, deprecations are removed in the next major version. + +Deprecations +------------------------------------- + +duration_formatter +~~~~~~~~~~~~~~~~~~ + +Deprecated in ``4.0.0`` + +*'duration_formatter' has been removed and no longer has any effect!* + +Reason +^^^^^^ + +With the rewrite of the plugin where most of the logic was moved to javascript, +the disconnect between time formatting between python and javascript made it +untenable to support dynamically setting the format. + +The decision was made to have ``ms`` for durations under 1 second, +and ``HH:mm:ss`` for 1 second and above. + +Mitigation +^^^^^^^^^^ + +Currently none. + +render_collapsed +~~~~~~~~~~~~~~~~ + +Deprecated in ``4.0.0`` + +*'render_collapsed = True' is deprecated and support will be removed in the next major release. +Please use 'render_collapsed = all' instead.* + +Reason +^^^^^^ + +We've changed the ini-config to better match the query param, so now the ini-config takes the same +values as the query param. For valid values please see :ref:`render-collapsed`. + +Mitigation +^^^^^^^^^^ + +Setting ``render_collapsed`` to ``all`` is equivalent to previously setting it to ``True``. + +.. _report-extra: + +report.extra +~~~~~~~~~~~~ + +Deprecated in ``4.0.0`` + +*The 'report.extra' attribute is deprecated and will be removed in a future release, +use 'report.extras' instead.* + +Reason +^^^^^^ + +The ``extra`` attribute is of type ``list``, hence more appropriately named ``extras``. + +Mitigation +^^^^^^^^^^ + +Rename ``extra`` to ``extras``. + +extra fixture +~~~~~~~~~~~~~ + +Deprecated in ``4.0.0`` + +*The 'extra' fixture is deprecated and will be removed in a future release, +use 'extras' instead.* + +Reason +^^^^^^ + +See :ref:`report-extra` + +Mitigation +^^^^^^^^^^ + +Rename ``extra`` to ``extras``. + +cell list assignment +~~~~~~~~~~~~~~~~~~~~ + +Deprecated in ``4.0.0`` + +*list-type assignment is deprecated and support will be removed in a future release. +Please use 'insert()' instead.* + +Reason +^^^^^^ + +The `cells` argument in the table manipulation hooks (see :ref:`modifying-results-table`) was +previously of type `list` but is now an object. + +Mitigation +^^^^^^^^^^ + +Replace ``cells[4] = value`` with ``cells.insert(4, value)``. + +py module +~~~~~~~~~ + +Deprecated in ``4.0.0`` + +*The 'py' module is deprecated and support will be removed in a future release.* + +Reason +^^^^^^ + +The ``py`` module is in maintenance mode and has been removed as a dependency. + +Mitigation +^^^^^^^^^^ + +Any usage of the ``html`` module from ``py.xml``, should be replaced with something +that returns the HTML as a string. + +From: + +.. code-block:: python + + import pytest + from py.xml import html + + + def pytest_html_results_table_header(cells): + cells.insert(2, html.th("Description")) + cells.insert(1, html.th("Time", class_="sortable time", data_column_type="time")) + +To: + +.. code-block:: python + + import pytest + + + def pytest_html_results_table_header(cells): + cells.insert(2, "Description") + cells.insert(1, 'Time') + +Note that you can keep using the `py` module by simple wrapping it in ``str``: + +.. code-block:: python + + import pytest + from py.xml import html + + + def pytest_html_results_table_header(cells): + cells.insert(2, str(html.th("Description"))) + cells.insert( + 1, str(html.th("Time", class_="sortable time", data_column_type="time")) + ) diff --git a/docs/index.rst b/docs/index.rst index fde8d81b..876f70c7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,5 +17,6 @@ pytest-html is a plugin for `pytest`_ that generates a HTML report for test resu api_reference development changelog + deprecations .. _pytest: http://pytest.org diff --git a/docs/user_guide.rst b/docs/user_guide.rst index c60ed9e7..8c8741b0 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -102,28 +102,25 @@ You can edit the *Summary* section by using the :code:`pytest_html_results_summa .. code-block:: python - from py.xml import html - - def pytest_html_results_summary(prefix, summary, postfix): prefix.extend(["

foo: bar

"]) Extra content ~~~~~~~~~~~~~ -You can add details to the HTML report by creating an 'extra' list on the +You can add details to the HTML report by creating an 'extras' list on the report object. Here are the types of extra content that can be added: ========== ============================================ Type Example ========== ============================================ -Raw HTML ``extra.html('
Additional HTML
')`` -`JSON`_ ``extra.json({'name': 'pytest'})`` -Plain text ``extra.text('Add some simple Text')`` -URL ``extra.url('http://www.example.com/')`` -Image ``extra.image(image, mime_type='image/gif', extension='gif')`` -Image ``extra.image('/path/to/file.png')`` -Image ``extra.image('http://some_image.png')`` +Raw HTML ``extras.html('
Additional HTML
')`` +`JSON`_ ``extras.json({'name': 'pytest'})`` +Plain text ``extras.text('Add some simple Text')`` +URL ``extras.url('http://www.example.com/')`` +Image ``extras.image(image, mime_type='image/gif', extension='gif')`` +Image ``extras.image('/path/to/file.png')`` +Image ``extras.image('http://some_image.png')`` ========== ============================================ **Note**: When adding an image from file, the path can be either absolute @@ -138,9 +135,9 @@ There are also convenient types for several image formats: ============ ==================== Image format Example ============ ==================== -PNG ``extra.png(image)`` -JPEG ``extra.jpg(image)`` -SVG ``extra.svg(image)`` +PNG ``extras.png(image)`` +JPEG ``extras.jpg(image)`` +SVG ``extras.svg(image)`` ============ ==================== The following example adds the various types of extras using a @@ -150,42 +147,44 @@ conftest.py file: .. code-block:: python import pytest + import pytest_html @pytest.hookimpl(hookwrapper=True) def pytest_runtest_makereport(item, call): - pytest_html = item.config.pluginmanager.getplugin("html") outcome = yield report = outcome.get_result() - extra = getattr(report, "extra", []) + extras = getattr(report, "extras", []) if report.when == "call": # always add url to report - extra.append(pytest_html.extras.url("http://www.example.com/")) + extras.append(pytest_html.extras.url("http://www.example.com/")) xfail = hasattr(report, "wasxfail") if (report.skipped and xfail) or (report.failed and not xfail): # only add additional html on failure - extra.append(pytest_html.extras.html("
Additional HTML
")) - report.extra = extra + extras.append(pytest_html.extras.html("
Additional HTML
")) + report.extras = extras You can also specify the :code:`name` argument for all types other than :code:`html` which will change the title of the created hyper link: .. code-block:: python - extra.append(pytest_html.extras.text("some string", name="Different title")) + extras.append(pytest_html.extras.text("some string", name="Different title")) -It is also possible to use the fixture :code:`extra` to add content directly +It is also possible to use the fixture :code:`extras` to add content directly in a test function without implementing hooks. These will generally end up before any extras added by plugins. .. code-block:: python - from pytest_html import extras + import pytest_html + + def test_extra(extras): + extras.append(pytest_html.extras.text("some string")) - def test_extra(extra): - extra.append(extras.text("some string")) +.. _modifying-results-table: Modifying the results table ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -196,7 +195,6 @@ adds a sortable time column, and removes the links column: .. code-block:: python - from datetime import datetime import pytest @@ -232,9 +230,6 @@ additional HTML and log output with a notice that the log is empty: .. code-block:: python - from py.xml import html - - def pytest_html_results_table_html(report, data): if report.passed: del data[:] @@ -243,6 +238,8 @@ additional HTML and log output with a notice that the log is empty: Display options --------------- +.. _render-collapsed: + Auto Collapsing Table Rows ~~~~~~~~~~~~~~~~~~~~~~~~~~