Docs: Add Deprecations docs (#640)
This commit is contained in:
Jim Brännlund
GitHub
parent
412f01bc7c
commit
fb1590812a
|
|
@ -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, "<th>Description</th>")
|
||||
cells.insert(1, '<th class="sortable time" data-column-type="time">Time</th>')
|
||||
|
||||
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"))
|
||||
)
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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(["<p>foo: bar</p>"])
|
||||
|
||||
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('<div>Additional HTML</div>')``
|
||||
`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('<div>Additional HTML</div>')``
|
||||
`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,43 +147,45 @@ 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("<div>Additional HTML</div>"))
|
||||
report.extra = extra
|
||||
extras.append(pytest_html.extras.html("<div>Additional HTML</div>"))
|
||||
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(extra):
|
||||
extra.append(extras.text("some string"))
|
||||
def test_extra(extras):
|
||||
extras.append(pytest_html.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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue