diff --git a/AUTHORS b/AUTHORS index b61969ff4..fd9422053 100644 --- a/AUTHORS +++ b/AUTHORS @@ -107,6 +107,7 @@ Kale Kundert Katarzyna Jachim Kevin Cox Kodi B. Arfer +Kostis Anagnostopoulos Lawrence Mitchell Lee Kamentsky Lev Maximov diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 040c91118..a0e8897df 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,4 +1,4 @@ -.. +.. You should *NOT* be adding new change log entries to this file, this file is managed by towncrier. You *may* edit previous change logs to fix problems like typo corrections or such. @@ -377,7 +377,7 @@ Features - Match ``warns`` signature to ``raises`` by adding ``match`` keyword. (`#2708 `_) -- Pytest now captures and displays output from the standard `logging` module. +- Pytest now captures and displays output from the standard ``logging`` module. The user can control the logging level to be captured by specifying options in ``pytest.ini``, the command line and also during individual tests using markers. Also, a ``caplog`` fixture is available that enables users to test diff --git a/_pytest/capture.py b/_pytest/capture.py index 36658acce..9f4f41c41 100644 --- a/_pytest/capture.py +++ b/_pytest/capture.py @@ -197,9 +197,9 @@ def _ensure_only_one_capture_fixture(request, name): @pytest.fixture def capsys(request): - """Enable capturing of writes to sys.stdout/sys.stderr and make + """Enable capturing of writes to ``sys.stdout`` and ``sys.stderr`` and make captured output available via ``capsys.readouterr()`` method calls - which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``text`` + which return a ``(out, err)`` namedtuple. ``out`` and ``err`` will be ``text`` objects. """ _ensure_only_one_capture_fixture(request, 'capsys') @@ -209,7 +209,7 @@ def capsys(request): @pytest.fixture def capsysbinary(request): - """Enable capturing of writes to sys.stdout/sys.stderr and make + """Enable capturing of writes to ``sys.stdout`` and ``sys.stderr`` and make captured output available via ``capsys.readouterr()`` method calls which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``bytes`` objects. @@ -225,7 +225,7 @@ def capsysbinary(request): @pytest.fixture def capfd(request): - """Enable capturing of writes to file descriptors 1 and 2 and make + """Enable capturing of writes to file descriptors ``1`` and ``2`` and make captured output available via ``capfd.readouterr()`` method calls which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``text`` objects. @@ -272,6 +272,10 @@ def _install_capture_fixture_on_item(request, capture_class): class CaptureFixture(object): + """ + Object returned by :py:func:`capsys`, :py:func:`capsysbinary`, :py:func:`capfd` and :py:func:`capfdbinary` + fixtures. + """ def __init__(self, captureclass, request): self.captureclass = captureclass self.request = request @@ -288,6 +292,10 @@ class CaptureFixture(object): cap.stop_capturing() def readouterr(self): + """Read and return the captured output so far, resetting the internal buffer. + + :return: captured content as a namedtuple with ``out`` and ``err`` string attributes + """ try: return self._capture.readouterr() except AttributeError: @@ -295,6 +303,7 @@ class CaptureFixture(object): @contextlib.contextmanager def disabled(self): + """Temporarily disables capture while inside the 'with' block.""" self._capture.suspend_capturing() capmanager = self.request.config.pluginmanager.getplugin('capturemanager') capmanager.suspend_global_capture(item=None, in_=False) @@ -476,7 +485,7 @@ class FDCaptureBinary(object): os.dup2(targetfd_save, self.targetfd) os.close(targetfd_save) self.syscapture.done() - self.tmpfile.close() + _attempt_to_close_capture_file(self.tmpfile) def suspend(self): self.syscapture.suspend() @@ -530,7 +539,7 @@ class SysCapture(object): def done(self): setattr(sys, self.name, self._old) del self._old - self.tmpfile.close() + _attempt_to_close_capture_file(self.tmpfile) def suspend(self): setattr(sys, self.name, self._old) @@ -551,7 +560,7 @@ class SysCaptureBinary(SysCapture): return res -class DontReadFromInput(object): +class DontReadFromInput(six.Iterator): """Temporary stub class. Ideally when stdin is accessed, the capturing should be turned off, with possibly all data captured so far sent to the screen. This should be configurable, though, @@ -565,7 +574,10 @@ class DontReadFromInput(object): raise IOError("reading from stdin while output is captured") readline = read readlines = read - __iter__ = read + __next__ = read + + def __iter__(self): + return self def fileno(self): raise UnsupportedOperation("redirected stdin is pseudofile, " @@ -681,3 +693,14 @@ def _py36_windowsconsoleio_workaround(stream): sys.__stdin__ = sys.stdin = _reopen_stdio(sys.stdin, 'rb') sys.__stdout__ = sys.stdout = _reopen_stdio(sys.stdout, 'wb') sys.__stderr__ = sys.stderr = _reopen_stdio(sys.stderr, 'wb') + + +def _attempt_to_close_capture_file(f): + """Suppress IOError when closing the temporary file used for capturing streams in py27 (#2370)""" + if six.PY2: + try: + f.close() + except IOError: + pass + else: + f.close() diff --git a/_pytest/config.py b/_pytest/config.py index 63c7dc3bb..4087d6e9f 100644 --- a/_pytest/config.py +++ b/_pytest/config.py @@ -171,7 +171,7 @@ class PytestPluginManager(PluginManager): Overwrites :py:class:`pluggy.PluginManager ` to add pytest-specific functionality: - * loading plugins from the command line, ``PYTEST_PLUGIN`` env variable and + * loading plugins from the command line, ``PYTEST_PLUGINS`` env variable and ``pytest_plugins`` global variables found in plugins being loaded; * ``conftest.py`` loading during start-up; """ diff --git a/_pytest/doctest.py b/_pytest/doctest.py index 03775a09a..131109cba 100644 --- a/_pytest/doctest.py +++ b/_pytest/doctest.py @@ -462,6 +462,6 @@ def _fix_spoof_python2(runner, encoding): @pytest.fixture(scope='session') def doctest_namespace(): """ - Inject names into the doctest namespace. + Fixture that returns a :py:class:`dict` that will be injected into the namespace of doctests. """ return dict() diff --git a/_pytest/fixtures.py b/_pytest/fixtures.py index df0d1a41a..e2ea84e30 100644 --- a/_pytest/fixtures.py +++ b/_pytest/fixtures.py @@ -858,7 +858,7 @@ class FixtureFunctionMarker(object): def fixture(scope="function", params=None, autouse=False, ids=None, name=None): - """ (return a) decorator to mark a fixture factory function. + """Decorator to mark a fixture factory function. This decorator can be used (with or without parameters) to define a fixture function. The name of the fixture function can later be @@ -923,7 +923,15 @@ defaultfuncargprefixmarker = fixture() @fixture(scope="session") def pytestconfig(request): - """ the pytest config object with access to command line opts.""" + """Session-scoped fixture that returns the :class:`_pytest.config.Config` object. + + Example:: + + def test_foo(pytestconfig): + if pytestconfig.getoption("verbose"): + ... + + """ return request.config diff --git a/_pytest/junitxml.py b/_pytest/junitxml.py index 98b2d13cf..5207c2514 100644 --- a/_pytest/junitxml.py +++ b/_pytest/junitxml.py @@ -237,7 +237,13 @@ def record_property(request): """Add an extra properties the calling test. User properties become part of the test report and are available to the configured reporters, like JUnit XML. - The fixture is callable with ``(name, value)``. + The fixture is callable with ``(name, value)``, with value being automatically + xml-encoded. + + Example:: + + def test_function(record_property): + record_property("example_key", 1) """ request.node.warn( code='C3', diff --git a/_pytest/logging.py b/_pytest/logging.py index 7234bdeb0..902872e45 100644 --- a/_pytest/logging.py +++ b/_pytest/logging.py @@ -176,6 +176,10 @@ class LogCaptureHandler(logging.StreamHandler): self.records.append(record) logging.StreamHandler.emit(self, record) + def reset(self): + self.records = [] + self.stream = py.io.TextIO() + class LogCaptureFixture(object): """Provides access and control of log capturing.""" @@ -197,6 +201,9 @@ class LogCaptureFixture(object): @property def handler(self): + """ + :rtype: LogCaptureHandler + """ return self._item.catch_log_handler def get_records(self, when): @@ -239,8 +246,8 @@ class LogCaptureFixture(object): return [(r.name, r.levelno, r.getMessage()) for r in self.records] def clear(self): - """Reset the list of log records.""" - self.handler.records = [] + """Reset the list of log records and the captured log text.""" + self.handler.reset() def set_level(self, level, logger=None): """Sets the level for capturing of logs. The level will be restored to its previous value at the end of @@ -285,6 +292,7 @@ def caplog(request): * caplog.text() -> string containing formatted log output * caplog.records() -> list of logging.LogRecord instances * caplog.record_tuples() -> list of (logger_name, level, message) tuples + * caplog.clear() -> clear captured records and formatted log output string """ result = LogCaptureFixture(request.node) yield result diff --git a/_pytest/mark/__init__.py b/_pytest/mark/__init__.py index f22db5820..51540dbd7 100644 --- a/_pytest/mark/__init__.py +++ b/_pytest/mark/__init__.py @@ -20,6 +20,21 @@ class MarkerError(Exception): def param(*values, **kw): + """Specify a parameter in a `pytest.mark.parametrize`_ call. + + .. code-block:: python + + @pytest.mark.parametrize("test_input,expected", [ + ("3+5", 8), + pytest.param("6*9", 42, marks=pytest.mark.xfail), + ]) + def test_eval(test_input, expected): + assert eval(test_input) == expected + + :param values: variable args of the values of the parameter set, in order. + :keyword marks: a single mark or a list of marks to be applied to this parameter set. + :keyword str id: the id to attribute to this parameter set. + """ return ParameterSet.param(*values, **kw) diff --git a/_pytest/monkeypatch.py b/_pytest/monkeypatch.py index c402213e8..c82ffd053 100644 --- a/_pytest/monkeypatch.py +++ b/_pytest/monkeypatch.py @@ -113,7 +113,7 @@ class MonkeyPatch(object): For convenience you can specify a string as ``target`` which will be interpreted as a dotted import path, with the last part being the attribute name. Example: - ``monkeypatch.setattr("os.getcwd", lambda x: "/")`` + ``monkeypatch.setattr("os.getcwd", lambda: "/")`` would set the ``getcwd`` function of the ``os`` module. The ``raising`` value determines if the setattr should fail diff --git a/_pytest/python.py b/_pytest/python.py index cdcfed49b..f9f17afd7 100644 --- a/_pytest/python.py +++ b/_pytest/python.py @@ -717,7 +717,7 @@ class CallSpec2(object): class Metafunc(fixtures.FuncargnamesCompatAttr): """ - Metafunc objects are passed to the ``pytest_generate_tests`` hook. + Metafunc objects are passed to the :func:`pytest_generate_tests <_pytest.hookspec.pytest_generate_tests>` hook. They help to inspect a test function and to generate tests according to test configuration or values specified in the class or module where a test function is defined. diff --git a/_pytest/python_api.py b/_pytest/python_api.py index 3dce7f6b4..3f9d49477 100644 --- a/_pytest/python_api.py +++ b/_pytest/python_api.py @@ -548,8 +548,9 @@ def raises(expected_exception, *args, **kwargs): The string will be evaluated using the same ``locals()`` and ``globals()`` at the moment of the ``raises`` call. - .. autoclass:: _pytest._code.ExceptionInfo - :members: + .. currentmodule:: _pytest._code + + Consult the API of ``excinfo`` objects: :class:`ExceptionInfo`. .. note:: Similar to caught exception objects in Python, explicitly clearing diff --git a/_pytest/recwarn.py b/_pytest/recwarn.py index 4fceb10a7..ab0f79c75 100644 --- a/_pytest/recwarn.py +++ b/_pytest/recwarn.py @@ -16,10 +16,7 @@ from _pytest.outcomes import fail @yield_fixture def recwarn(): - """Return a WarningsRecorder instance that provides these methods: - - * ``pop(category=None)``: return last warning matching the category. - * ``clear()``: clear list of warnings + """Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions. See http://docs.python.org/library/warnings.html for information on warning categories. @@ -88,11 +85,11 @@ class _DeprecatedCallContext(object): def warns(expected_warning, *args, **kwargs): """Assert that code raises a particular class of warning. - Specifically, the input @expected_warning can be a warning class or - tuple of warning classes, and the code must return that warning - (if a single class) or one of those warnings (if a tuple). + Specifically, the parameter ``expected_warning`` can be a warning class or + sequence of warning classes, and the inside the ``with`` block must issue a warning of that class or + classes. - This helper produces a list of ``warnings.WarningMessage`` objects, + This helper produces a list of :class:`warnings.WarningMessage` objects, one for each warning raised. This function can be used as a context manager, or any of the other ways diff --git a/_pytest/tmpdir.py b/_pytest/tmpdir.py index 66b4a2d2f..315ead302 100644 --- a/_pytest/tmpdir.py +++ b/_pytest/tmpdir.py @@ -116,6 +116,8 @@ def tmpdir(request, tmpdir_factory): created as a sub directory of the base temporary directory. The returned object is a `py.path.local`_ path object. + + .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html """ name = request.node.name name = re.sub(r"[\W]", "_", name) diff --git a/changelog/1713.doc.rst b/changelog/1713.doc.rst new file mode 100644 index 000000000..291ee3c74 --- /dev/null +++ b/changelog/1713.doc.rst @@ -0,0 +1 @@ +Added a `reference `_ page to the docs. diff --git a/changelog/2370.bugfix.rst b/changelog/2370.bugfix.rst new file mode 100644 index 000000000..937acb471 --- /dev/null +++ b/changelog/2370.bugfix.rst @@ -0,0 +1 @@ +Suppress ``IOError`` when closing the temporary file used for capturing streams in Python 2.7. diff --git a/changelog/3245.trivial.rst b/changelog/3245.trivial.rst new file mode 100644 index 000000000..b61d9804f --- /dev/null +++ b/changelog/3245.trivial.rst @@ -0,0 +1 @@ +Added ``doc`` to norecursedirs in tox.ini \ No newline at end of file diff --git a/changelog/3297.bugfix.rst b/changelog/3297.bugfix.rst new file mode 100644 index 000000000..f3cbc2c9c --- /dev/null +++ b/changelog/3297.bugfix.rst @@ -0,0 +1,2 @@ +Fixed ``clear()`` method on ``caplog`` fixture which cleared ``records``, +but not the ``text`` property. \ No newline at end of file diff --git a/changelog/3308.trivial.rst b/changelog/3308.trivial.rst new file mode 100644 index 000000000..693384836 --- /dev/null +++ b/changelog/3308.trivial.rst @@ -0,0 +1 @@ +Fix a python example when calling a fixture in doc/en/usage.rst diff --git a/changelog/3314.bugfix.rst b/changelog/3314.bugfix.rst new file mode 100644 index 000000000..4b671ec21 --- /dev/null +++ b/changelog/3314.bugfix.rst @@ -0,0 +1,3 @@ +During test collection, when stdin is not allowed to be read, the +``DontReadFromStdin`` object still allow itself to be iterable and +resolved to an iterator without crashing. diff --git a/doc/en/_templates/globaltoc.html b/doc/en/_templates/globaltoc.html index fdd4dd59b..0e088d67e 100644 --- a/doc/en/_templates/globaltoc.html +++ b/doc/en/_templates/globaltoc.html @@ -2,15 +2,16 @@ {%- if display_toc %} diff --git a/doc/en/_templates/links.html b/doc/en/_templates/links.html index d855a013f..91157dfb7 100644 --- a/doc/en/_templates/links.html +++ b/doc/en/_templates/links.html @@ -1,7 +1,5 @@

Useful Links

    -
  • The pytest Website
    • -
  • Contribution Guide
  • pytest @ PyPI
  • pytest @ GitHub
  • 3rd party plugins
    • diff --git a/doc/en/builtin.rst b/doc/en/builtin.rst index ba033849c..a3bdb145e 100644 --- a/doc/en/builtin.rst +++ b/doc/en/builtin.rst @@ -1,166 +1,24 @@ +:orphan: .. _`pytest helpers`: Pytest API and builtin fixtures ================================================ -This is a list of ``pytest.*`` API functions and fixtures. + +Most of the information of this page has been moved over to :ref:`reference`. For information on plugin hooks and objects, see :ref:`plugins`. For information on the ``pytest.mark`` mechanism, see :ref:`mark`. -For the below objects, you can also interactively ask for help, e.g. by -typing on the Python interactive prompt something like:: +For information about fixtures, see :ref:`fixtures`. To see a complete list of available fixtures, type:: + + $ pytest -q --fixtures + + +You can also interactively ask for help, e.g. by typing on the Python interactive prompt something like:: import pytest help(pytest) -.. currentmodule:: pytest - -Invoking pytest interactively ---------------------------------------------------- - -.. autofunction:: main - -More examples at :ref:`pytest.main-usage` - - -Helpers for assertions about Exceptions/Warnings --------------------------------------------------------- - -.. autofunction:: raises - -Examples at :ref:`assertraises`. - -.. autofunction:: deprecated_call - -Comparing floating point numbers --------------------------------- - -.. autofunction:: approx - -Raising a specific test outcome --------------------------------------- - -You can use the following functions in your test, fixture or setup -functions to force a certain test outcome. Note that most often -you can rather use declarative marks, see :ref:`skipping`. - -.. autofunction:: _pytest.outcomes.fail -.. autofunction:: _pytest.outcomes.skip -.. autofunction:: _pytest.outcomes.importorskip -.. autofunction:: _pytest.outcomes.xfail -.. autofunction:: _pytest.outcomes.exit - -Fixtures and requests ------------------------------------------------------ - -To mark a fixture function: - -.. autofunction:: _pytest.fixtures.fixture - -Tutorial at :ref:`fixtures`. - -The ``request`` object that can be used from fixture functions. - -.. autoclass:: _pytest.fixtures.FixtureRequest() - :members: - - -.. _builtinfixtures: -.. _builtinfuncargs: - -Builtin fixtures/function arguments ------------------------------------------ - -You can ask for available builtin or project-custom -:ref:`fixtures ` by typing:: - - $ pytest -q --fixtures - cache - Return a cache object that can persist state between testing sessions. - - cache.get(key, default) - cache.set(key, value) - - Keys must be a ``/`` separated value, where the first part is usually the - name of your plugin or application to avoid clashes with other cache users. - - Values can be any object handled by the json stdlib module. - capsys - Enable capturing of writes to sys.stdout/sys.stderr and make - captured output available via ``capsys.readouterr()`` method calls - which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``text`` - objects. - capsysbinary - Enable capturing of writes to sys.stdout/sys.stderr and make - captured output available via ``capsys.readouterr()`` method calls - which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``bytes`` - objects. - capfd - Enable capturing of writes to file descriptors 1 and 2 and make - captured output available via ``capfd.readouterr()`` method calls - which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``text`` - objects. - capfdbinary - Enable capturing of write to file descriptors 1 and 2 and make - captured output available via ``capfdbinary.readouterr`` method calls - which return a ``(out, err)`` tuple. ``out`` and ``err`` will be - ``bytes`` objects. - doctest_namespace - Inject names into the doctest namespace. - pytestconfig - the pytest config object with access to command line opts. - record_property - Add an extra properties the calling test. - User properties become part of the test report and are available to the - configured reporters, like JUnit XML. - The fixture is callable with ``(name, value)``. - record_xml_attribute - Add extra xml attributes to the tag for the calling test. - The fixture is callable with ``(name, value)``, with value being automatically - xml-encoded - caplog - Access and control log capturing. - - Captured logs are available through the following methods:: - - * caplog.text() -> string containing formatted log output - * caplog.records() -> list of logging.LogRecord instances - * caplog.record_tuples() -> list of (logger_name, level, message) tuples - monkeypatch - The returned ``monkeypatch`` fixture provides these - helper methods to modify objects, dictionaries or os.environ:: - - monkeypatch.setattr(obj, name, value, raising=True) - monkeypatch.delattr(obj, name, raising=True) - monkeypatch.setitem(mapping, name, value) - monkeypatch.delitem(obj, name, raising=True) - monkeypatch.setenv(name, value, prepend=False) - monkeypatch.delenv(name, value, raising=True) - monkeypatch.syspath_prepend(path) - monkeypatch.chdir(path) - - All modifications will be undone after the requesting - test function or fixture has finished. The ``raising`` - parameter determines if a KeyError or AttributeError - will be raised if the set/deletion operation has no target. - recwarn - Return a WarningsRecorder instance that provides these methods: - - * ``pop(category=None)``: return last warning matching the category. - * ``clear()``: clear list of warnings - - See http://docs.python.org/library/warnings.html for information - on warning categories. - tmpdir_factory - Return a TempdirFactory instance for the test session. - tmpdir - Return a temporary directory path object - which is unique to each test function invocation, - created as a sub directory of the base temporary - directory. The returned object is a `py.path.local`_ - path object. - - no tests ran in 0.12 seconds diff --git a/doc/en/cache.rst b/doc/en/cache.rst index db72249f9..9f71a9d6a 100644 --- a/doc/en/cache.rst +++ b/doc/en/cache.rst @@ -216,7 +216,7 @@ the cache and this will be quick:: test_caching.py:14: AssertionError 1 failed in 0.12 seconds -See the `cache-api`_ for more details. +See the :ref:`cache-api` for more details. Inspecting Cache content @@ -251,22 +251,3 @@ servers where isolation and correctness is more important than speed. -.. _`cache-api`: - -config.cache API ------------------- - -The ``config.cache`` object allows other plugins, -including ``conftest.py`` files, -to safely and flexibly store and retrieve values across -test runs because the ``config`` object is available -in many places. - -Under the hood, the cache plugin uses the simple -dumps/loads API of the json stdlib module - -.. currentmodule:: _pytest.cacheprovider - -.. automethod:: Cache.get -.. automethod:: Cache.set -.. automethod:: Cache.makedir diff --git a/doc/en/conf.py b/doc/en/conf.py index 40f1e4165..f5c17404b 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -18,8 +18,11 @@ # The full version, including alpha/beta/rc tags. # The short X.Y version. -import os, sys +import os +import sys + from _pytest import __version__ as version + release = ".".join(version.split(".")[:2]) # If extensions (or modules to document with autodoc) are in another directory, @@ -38,7 +41,7 @@ todo_include_todos = 1 # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode'] + 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', 'sphinxcontrib_trio'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -310,9 +313,7 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'python': ('http://docs.python.org/', None), -# 'lib': ("http://docs.python.org/2.7library/", None), - } +intersphinx_mapping = {'python': ('http://docs.python.org/3', None)} def setup(app): diff --git a/doc/en/contents.rst b/doc/en/contents.rst index 7a6570e0b..79c4fce3e 100644 --- a/doc/en/contents.rst +++ b/doc/en/contents.rst @@ -14,7 +14,6 @@ Full pytest documentation usage existingtestsuite assert - builtin fixture monkeypatch tmpdir @@ -31,6 +30,7 @@ Full pytest documentation plugins writing_plugins logging + reference goodpractices pythonpath diff --git a/doc/en/customize.rst b/doc/en/customize.rst index f819c5974..e89cdc002 100644 --- a/doc/en/customize.rst +++ b/doc/en/customize.rst @@ -156,222 +156,4 @@ above will show verbose output because ``-v`` overwrites ``-q``. Builtin configuration file options ---------------------------------------------- -Here is a list of builtin configuration options that may be written in a ``pytest.ini``, ``tox.ini`` or ``setup.cfg`` -file, usually located at the root of your repository. All options must be under a ``[pytest]`` section -(``[tool:pytest]`` for ``setup.cfg`` files). - -Configuration file options may be overwritten in the command-line by using ``-o/--override``, which can also be -passed multiple times. The expected format is ``name=value``. For example:: - - pytest -o console_output_style=classic -o cache_dir=/tmp/mycache - - -.. confval:: minversion - - Specifies a minimal pytest version required for running tests. - - .. code-block:: ini - - # content of pytest.ini - [pytest] - minversion = 3.0 # will fail if we run with pytest-2.8 - -.. confval:: addopts - - Add the specified ``OPTS`` to the set of command line arguments as if they - had been specified by the user. Example: if you have this ini file content: - - .. code-block:: ini - - # content of pytest.ini - [pytest] - addopts = --maxfail=2 -rf # exit after 2 failures, report fail info - - issuing ``pytest test_hello.py`` actually means:: - - pytest --maxfail=2 -rf test_hello.py - - Default is to add no options. - -.. confval:: norecursedirs - - Set the directory basename patterns to avoid when recursing - for test discovery. The individual (fnmatch-style) patterns are - applied to the basename of a directory to decide if to recurse into it. - Pattern matching characters:: - - * matches everything - ? matches any single character - [seq] matches any character in seq - [!seq] matches any char not in seq - - Default patterns are ``'.*', 'build', 'dist', 'CVS', '_darcs', '{arch}', '*.egg', 'venv'``. - Setting a ``norecursedirs`` replaces the default. Here is an example of - how to avoid certain directories: - - .. code-block:: ini - - # content of pytest.ini - [pytest] - norecursedirs = .svn _build tmp* - - This would tell ``pytest`` to not look into typical subversion or - sphinx-build directories or into any ``tmp`` prefixed directory. - - Additionally, ``pytest`` will attempt to intelligently identify and ignore a - virtualenv by the presence of an activation script. Any directory deemed to - be the root of a virtual environment will not be considered during test - collection unless ``‑‑collect‑in‑virtualenv`` is given. Note also that - ``norecursedirs`` takes precedence over ``‑‑collect‑in‑virtualenv``; e.g. if - you intend to run tests in a virtualenv with a base directory that matches - ``'.*'`` you *must* override ``norecursedirs`` in addition to using the - ``‑‑collect‑in‑virtualenv`` flag. - -.. confval:: testpaths - - .. versionadded:: 2.8 - - Sets list of directories that should be searched for tests when - no specific directories, files or test ids are given in the command line when - executing pytest from the :ref:`rootdir ` directory. - Useful when all project tests are in a known location to speed up - test collection and to avoid picking up undesired tests by accident. - - .. code-block:: ini - - # content of pytest.ini - [pytest] - testpaths = testing doc - - This tells pytest to only look for tests in ``testing`` and ``doc`` - directories when executing from the root directory. - -.. confval:: python_files - - One or more Glob-style file patterns determining which python files - are considered as test modules. By default, pytest will consider - any file matching with ``test_*.py`` and ``*_test.py`` globs as a test - module. - -.. confval:: python_classes - - One or more name prefixes or glob-style patterns determining which classes - are considered for test collection. By default, pytest will consider any - class prefixed with ``Test`` as a test collection. Here is an example of how - to collect tests from classes that end in ``Suite``: - - .. code-block:: ini - - # content of pytest.ini - [pytest] - python_classes = *Suite - - Note that ``unittest.TestCase`` derived classes are always collected - regardless of this option, as ``unittest``'s own collection framework is used - to collect those tests. - -.. confval:: python_functions - - One or more name prefixes or glob-patterns determining which test functions - and methods are considered tests. By default, pytest will consider any - function prefixed with ``test`` as a test. Here is an example of how - to collect test functions and methods that end in ``_test``: - - .. code-block:: ini - - # content of pytest.ini - [pytest] - python_functions = *_test - - Note that this has no effect on methods that live on a ``unittest - .TestCase`` derived class, as ``unittest``'s own collection framework is used - to collect those tests. - - See :ref:`change naming conventions` for more detailed examples. - -.. confval:: doctest_optionflags - - One or more doctest flag names from the standard ``doctest`` module. - :doc:`See how pytest handles doctests `. - -.. confval:: confcutdir - - Sets a directory where search upwards for ``conftest.py`` files stops. - By default, pytest will stop searching for ``conftest.py`` files upwards - from ``pytest.ini``/``tox.ini``/``setup.cfg`` of the project if any, - or up to the file-system root. - - -.. confval:: filterwarnings - - .. versionadded:: 3.1 - - Sets a list of filters and actions that should be taken for matched - warnings. By default all warnings emitted during the test session - will be displayed in a summary at the end of the test session. - - .. code-block:: ini - - # content of pytest.ini - [pytest] - filterwarnings = - error - ignore::DeprecationWarning - - This tells pytest to ignore deprecation warnings and turn all other warnings - into errors. For more information please refer to :ref:`warnings`. - -.. confval:: cache_dir - - .. versionadded:: 3.2 - - Sets a directory where stores content of cache plugin. Default directory is - ``.cache`` which is created in :ref:`rootdir `. Directory may be - relative or absolute path. If setting relative path, then directory is created - relative to :ref:`rootdir `. Additionally path may contain environment - variables, that will be expanded. For more information about cache plugin - please refer to :ref:`cache_provider`. - - -.. confval:: console_output_style - - .. versionadded:: 3.3 - - Sets the console output style while running tests: - - * ``classic``: classic pytest output. - * ``progress``: like classic pytest output, but with a progress indicator. - - The default is ``progress``, but you can fallback to ``classic`` if you prefer or - the new mode is causing unexpected problems: - - .. code-block:: ini - - # content of pytest.ini - [pytest] - console_output_style = classic - - -.. confval:: empty_parameter_set_mark - - .. versionadded:: 3.4 - - Allows to pick the action for empty parametersets in parameterization - - * ``skip`` skips tests with a empty parameterset (default) - * ``xfail`` marks tests with a empty parameterset as xfail(run=False) - - .. code-block:: ini - - # content of pytest.ini - [pytest] - empty_parameter_set_mark = xfail - - .. note:: - - The default value of this option is planned to change to ``xfail`` in future releases - as this is considered less error prone, see `#3155`_ for more details. - - - -.. _`#3155`: https://github.com/pytest-dev/pytest/issues/3155 +For the full list of options consult the :ref:`reference documentation `. diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index cdbc34682..2ee7110b3 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -121,6 +121,8 @@ you want to continue the test even when you have failures, do:: pytest --doctest-modules --doctest-continue-on-failure +.. _`doctest_namespace`: + The 'doctest_namespace' fixture ------------------------------- diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index ec9b628c2..44e5726fb 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -3,6 +3,8 @@ Basic patterns and examples ========================================================== +.. _request example: + Pass different values to a test function, depending on command line options ---------------------------------------------------------------------------- @@ -764,6 +766,8 @@ and run it:: You'll see that the fixture finalizers could use the precise reporting information. +.. _pytest current test env: + ``PYTEST_CURRENT_TEST`` environment variable -------------------------------------------- diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index 31af29da8..0965c2a61 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -172,9 +172,10 @@ Continue reading Check out additional pytest resources to help you customize tests for your unique workflow: * ":ref:`cmdline`" for command line invocation examples -* ":ref:`goodpractices`" for virtualenv and test layouts * ":ref:`existingtestsuite`" for working with pre-existing tests +* ":ref:`mark`" for information on the ``pytest.mark`` mechanism * ":ref:`fixtures`" for providing a functional baseline to your tests * ":ref:`plugins`" for managing and writing plugins +* ":ref:`goodpractices`" for virtualenv and test layouts .. include:: links.inc diff --git a/doc/en/logging.rst b/doc/en/logging.rst index ad59be83f..44cfaaa28 100644 --- a/doc/en/logging.rst +++ b/doc/en/logging.rst @@ -144,11 +144,9 @@ the records for the ``setup`` and ``call`` stages during teardown like so: pytest.fail('warning messages encountered during testing: {}'.format(messages)) -caplog fixture API -~~~~~~~~~~~~~~~~~~ -.. autoclass:: _pytest.logging.LogCaptureFixture - :members: +The full API is available at :class:`_pytest.logging.LogCaptureFixture`. + .. _live_logs: diff --git a/doc/en/mark.rst b/doc/en/mark.rst index 0b0e072a0..e4858bf83 100644 --- a/doc/en/mark.rst +++ b/doc/en/mark.rst @@ -4,7 +4,6 @@ Marking test functions with attributes ================================================================= -.. currentmodule:: _pytest.mark By using the ``pytest.mark`` helper you can easily set metadata on your test functions. There are @@ -27,15 +26,3 @@ which also serve as documentation. :ref:`fixtures `. -API reference for mark related objects ------------------------------------------------- - -.. autoclass:: MarkGenerator - :members: - -.. autoclass:: MarkDecorator - :members: - -.. autoclass:: MarkInfo - :members: - diff --git a/doc/en/monkeypatch.rst b/doc/en/monkeypatch.rst index 0c07b2f44..a2327d4fa 100644 --- a/doc/en/monkeypatch.rst +++ b/doc/en/monkeypatch.rst @@ -63,13 +63,9 @@ so that any attempts within tests to create http requests will fail. help although there's no guarantee. -Method reference of the monkeypatch fixture -------------------------------------------- +.. currentmodule:: _pytest.monkeypatch -.. autoclass:: MonkeyPatch - :members: - -``monkeypatch.setattr/delattr/delitem/delenv()`` all -by default raise an Exception if the target does not exist. -Pass ``raising=False`` if you want to skip this check. +API Reference +------------- +Consult the docs for the :class:`MonkeyPatch` class. diff --git a/doc/en/parametrize.rst b/doc/en/parametrize.rst index 991dd4b1e..ba2cd3cce 100644 --- a/doc/en/parametrize.rst +++ b/doc/en/parametrize.rst @@ -33,7 +33,7 @@ pytest enables test parametrization at several levels: .. versionchanged:: 2.4 Several improvements. -The builtin ``pytest.mark.parametrize`` decorator enables +The builtin :ref:`pytest.mark.parametrize ref` decorator enables parametrization of arguments for a test function. Here is a typical example of a test function that implements checking that a certain input leads to an expected output:: @@ -206,12 +206,3 @@ More examples For further examples, you might want to look at :ref:`more parametrization examples `. - -.. _`metafunc object`: - -The **metafunc** object -------------------------------------------- - -.. currentmodule:: _pytest.python -.. autoclass:: Metafunc - :members: diff --git a/doc/en/plugins.rst b/doc/en/plugins.rst index 2a9fff81b..4089b9b28 100644 --- a/doc/en/plugins.rst +++ b/doc/en/plugins.rst @@ -61,10 +61,11 @@ status against different pytest and Python versions, please visit You may also discover more plugins through a `pytest- pypi.python.org search`_. -.. _`available installable plugins`: .. _`pytest- pypi.python.org search`: http://pypi.python.org/pypi?%3Aaction=search&term=pytest-&submit=search +.. _`available installable plugins`: + Requiring/Loading plugins in a test module or conftest file ----------------------------------------------------------- @@ -120,36 +121,3 @@ CI server), you can set ``PYTEST_ADDOPTS`` environment variable to See :ref:`findpluginname` for how to obtain the name of a plugin. .. _`builtin plugins`: - -Pytest default plugin reference -------------------------------- - - -You can find the source code for the following plugins -in the `pytest repository `_. - -.. autosummary:: - - _pytest.assertion - _pytest.cacheprovider - _pytest.capture - _pytest.config - _pytest.doctest - _pytest.helpconfig - _pytest.junitxml - _pytest.mark - _pytest.monkeypatch - _pytest.nose - _pytest.pastebin - _pytest.debugging - _pytest.pytester - _pytest.python - _pytest.recwarn - _pytest.resultlog - _pytest.runner - _pytest.main - _pytest.logging - _pytest.skipping - _pytest.terminal - _pytest.tmpdir - _pytest.unittest diff --git a/doc/en/reference.rst b/doc/en/reference.rst new file mode 100644 index 000000000..298afae13 --- /dev/null +++ b/doc/en/reference.rst @@ -0,0 +1,1255 @@ + +Reference +========= + +This page contains the full reference to pytest's API. + +.. contents:: + :depth: 3 + :local: + +Functions +--------- + +pytest.approx +~~~~~~~~~~~~~ + +.. autofunction:: _pytest.python_api.approx + +pytest.fail +~~~~~~~~~~~ + +**Tutorial**: :ref:`skipping` + +.. autofunction:: _pytest.outcomes.fail + +pytest.skip +~~~~~~~~~~~ + +.. autofunction:: _pytest.outcomes.skip(msg, [allow_module_level=False]) + +pytest.importorskip +~~~~~~~~~~~~~~~~~~~ + +.. autofunction:: _pytest.outcomes.importorskip + +pytest.xfail +~~~~~~~~~~~~ + +.. autofunction:: _pytest.outcomes.xfail + +pytest.exit +~~~~~~~~~~~ + +.. autofunction:: _pytest.outcomes.exit + +pytest.main +~~~~~~~~~~~ + +.. autofunction:: _pytest.config.main + +pytest.param +~~~~~~~~~~~~~ + +.. autofunction:: pytest.param(*values, [id], [marks]) + +pytest.raises +~~~~~~~~~~~~~ + +**Tutorial**: :ref:`assertraises`. + +.. autofunction:: pytest.raises(expected_exception: Exception, [match], [message]) + :with: excinfo + +pytest.deprecated_call +~~~~~~~~~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`ensuring_function_triggers`. + +.. autofunction:: pytest.deprecated_call() + :with: + +pytest.register_assert_rewrite +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`assertion-rewriting`. + +.. autofunction:: pytest.register_assert_rewrite + +pytest.warns +~~~~~~~~~~~~ + +**Tutorial**: :ref:`assertwarnings` + +.. autofunction:: pytest.warns(expected_warning: Exception, [match]) + :with: + + +.. _`marks ref`: + +Marks +----- + +Marks can be used apply meta data to *test functions* (but not fixtures), which can then be accessed by +fixtures or plugins. + + +.. _`pytest.mark.parametrize ref`: + +pytest.mark.parametrize +~~~~~~~~~~~~~~~~~~~~~~~ + +**Tutorial**: :doc:`parametrize`. + +.. automethod:: _pytest.python.Metafunc.parametrize + + +.. _`pytest.mark.skip ref`: + +pytest.mark.skip +~~~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`skip`. + +Unconditionally skip a test function. + +.. py:function:: pytest.mark.skip(*, reason=None) + + :keyword str reason: Reason why the test function is being skipped. + + +.. _`pytest.mark.skipif ref`: + +pytest.mark.skipif +~~~~~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`xfail`. + +Skip a test function if a condition is ``True``. + +.. py:function:: pytest.mark.skipif(condition, *, reason=None) + + :type condition: bool or str + :param condition: ``True/False`` if the condition should be skipped or a :ref:`condition string `. + :keyword str reason: Reason why the test function is being skipped. + + +.. _`pytest.mark.xfail ref`: + +pytest.mark.xfail +~~~~~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`xfail`. + +Marks a test function as *expected to fail*. + +.. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=False) + + :type condition: bool or str + :param condition: ``True/False`` if the condition should be marked as xfail or a :ref:`condition string `. + :keyword str reason: Reason why the test function is marked as xfail. + :keyword Exception raises: Exception subclass expected to be raised by the test function; other exceptions will fail the test. + :keyword bool run: + If the test function should actually be executed. If ``False``, the function will always xfail and will + not be executed (useful a function is segfaulting). + :keyword bool strict: + * If ``False`` (the default) the function will be shown in the terminal output as ``xfailed`` if it fails + and as ``xpass`` if it passes. In both cases this will not cause the test suite to fail as a whole. This + is particularly useful to mark *flaky* tests (tests that random at fail) to be tackled later. + * If ``True``, the function will be shown in the terminal output as ``xfailed`` if it fails, but if it + unexpectedly passes then it will **fail** the test suite. This is particularly useful to mark functions + that are always failing and there should be a clear indication if they unexpectedly start to pass (for example + a new release of a library fixes a known bug). + + +custom marks +~~~~~~~~~~~~ + +Marks are created dynamically using the factory object ``pytest.mark`` and applied as a decorator. + +For example: + +.. code-block:: python + + @pytest.mark.timeout(10, 'slow', method='thread') + def test_function(): + ... + +Will create and attach a :class:`MarkInfo <_pytest.mark.MarkInfo>` object to the collected +:class:`Item <_pytest.nodes.Item>`, which can then be accessed by fixtures or hooks with +:meth:`Node.get_marker <_pytest.nodes.Node.get_marker>`. The ``mark`` object will have the following attributes: + +.. code-block:: python + + mark.args == (10, 'slow') + mark.kwargs == {'method': 'thread'} + + +Fixtures +-------- + +**Tutorial**: :ref:`fixture`. + +Fixtures are requested by test functions or other fixtures by declaring them as argument names. + + +Example of a test requiring a fixture: + +.. code-block:: python + + def test_output(capsys): + print('hello') + out, err = capsys.readouterr() + assert out == 'hello\n' + + +Example of a fixture requiring another fixture: + +.. code-block:: python + + @pytest.fixture + def db_session(tmpdir): + fn = tmpdir / 'db.file' + return connect(str(fn)) + +For more details, consult the full :ref:`fixtures docs `. + + +@pytest.fixture +~~~~~~~~~~~~~~~ + +.. autofunction:: pytest.fixture + :decorator: + + +.. _`cache-api`: + +config.cache +~~~~~~~~~~~~ + +**Tutorial**: :ref:`cache`. + +The ``config.cache`` object allows other plugins and fixtures +to store and retrieve values across test runs. To access it from fixtures +request ``pytestconfig`` into your fixture and get it with ``pytestconfig.cache``. + +Under the hood, the cache plugin uses the simple +``dumps``/``loads`` API of the :py:mod:`json` stdlib module. + +.. currentmodule:: _pytest.cacheprovider + +.. automethod:: Cache.get +.. automethod:: Cache.set +.. automethod:: Cache.makedir + + +capsys +~~~~~~ + +**Tutorial**: :doc:`capture`. + +.. currentmodule:: _pytest.capture + +.. autofunction:: capsys() + :no-auto-options: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_output(capsys): + print("hello") + captured = capsys.readouterr() + assert captured.out == "hello\n" + +.. autoclass:: CaptureFixture() + :members: + + +capsysbinary +~~~~~~~~~~~~ + +**Tutorial**: :doc:`capture`. + +.. autofunction:: capsysbinary() + :no-auto-options: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_output(capsysbinary): + print("hello") + captured = capsysbinary.readouterr() + assert captured.out == b"hello\n" + + +capfd +~~~~~~ + +**Tutorial**: :doc:`capture`. + +.. autofunction:: capfd() + :no-auto-options: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_system_echo(capfd): + os.system('echo "hello"') + captured = capsys.readouterr() + assert captured.out == "hello\n" + + +capfdbinary +~~~~~~~~~~~~ + +**Tutorial**: :doc:`capture`. + +.. autofunction:: capfdbinary() + :no-auto-options: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_system_echo(capfdbinary): + os.system('echo "hello"') + captured = capfdbinary.readouterr() + assert captured.out == b"hello\n" + + +doctest_namespace +~~~~~~~~~~~~~~~~~ + +**Tutorial**: :doc:`doctest`. + +.. autofunction:: _pytest.doctest.doctest_namespace() + + Usually this fixture is used in conjunction with another ``autouse`` fixture: + + .. code-block:: python + + @pytest.fixture(autouse=True) + def add_np(doctest_namespace): + doctest_namespace['np'] = numpy + + For more details: :ref:`doctest_namespace`. + + +request +~~~~~~~ + +**Tutorial**: :ref:`request example`. + +The ``request`` fixture is a special fixture providing information of the requesting test function. + +.. autoclass:: _pytest.fixtures.FixtureRequest() + :members: + + +pytestconfig +~~~~~~~~~~~~ + +.. autofunction:: _pytest.fixtures.pytestconfig() + + +record_property +~~~~~~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`record_property example`. + +.. autofunction:: _pytest.junitxml.record_property() + +caplog +~~~~~~ + +**Tutorial**: :doc:`logging`. + +.. autofunction:: _pytest.logging.caplog() + :no-auto-options: + + This returns a :class:`_pytest.logging.LogCaptureFixture` instance. + +.. autoclass:: _pytest.logging.LogCaptureFixture + :members: + + +monkeypatch +~~~~~~~~~~~ + +.. currentmodule:: _pytest.monkeypatch + +**Tutorial**: :doc:`monkeypatch`. + +.. autofunction:: _pytest.monkeypatch.monkeypatch() + :no-auto-options: + + This returns a :class:`MonkeyPatch` instance. + +.. autoclass:: _pytest.monkeypatch.MonkeyPatch + :members: + +testdir +~~~~~~~ + +.. currentmodule:: _pytest.pytester + +This fixture provides a :class:`Testdir` instance useful for black-box testing of test files, making it ideal to +test plugins. + +To use it, include in your top-most ``conftest.py`` file:: + + pytest_plugins = 'pytester' + + + +.. autoclass:: Testdir() + :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile + +.. autoclass:: RunResult() + :members: + +.. autoclass:: LineMatcher() + :members: + + +recwarn +~~~~~~~ + +**Tutorial**: :ref:`assertwarnings` + +.. currentmodule:: _pytest.recwarn + +.. autofunction:: recwarn() + :no-auto-options: + +.. autoclass:: _pytest.recwarn.WarningsRecorder() + :members: + +Each recorded warning is an instance of :class:`warnings.WarningMessage`. + +.. note:: + :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1 + +.. note:: + ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated + differently; see :ref:`ensuring_function_triggers`. + + +tmpdir +~~~~~~ + +**Tutorial**: :doc:`tmpdir` + +.. currentmodule:: _pytest.tmpdir + +.. autofunction:: tmpdir() + :no-auto-options: + + +tmpdir_factory +~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`tmpdir factory example` + +.. _`tmpdir factory api`: + +``tmpdir_factory`` instances have the following methods: + +.. currentmodule:: _pytest.tmpdir + +.. automethod:: TempdirFactory.mktemp +.. automethod:: TempdirFactory.getbasetemp + + +.. _`hook-reference`: + +Hooks +----- + +**Tutorial**: :doc:`writing_plugins`. + +.. currentmodule:: _pytest.hookspec + +Reference to all hooks which can be implemented by :ref:`conftest.py files ` and :ref:`plugins `. + +Bootstrapping hooks +~~~~~~~~~~~~~~~~~~~ + +Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins). + +.. autofunction:: pytest_load_initial_conftests +.. autofunction:: pytest_cmdline_preparse +.. autofunction:: pytest_cmdline_parse +.. autofunction:: pytest_cmdline_main + +Initialization hooks +~~~~~~~~~~~~~~~~~~~~ + +Initialization hooks called for plugins and ``conftest.py`` files. + +.. autofunction:: pytest_addoption +.. autofunction:: pytest_addhooks +.. autofunction:: pytest_configure +.. autofunction:: pytest_unconfigure + +Test running hooks +~~~~~~~~~~~~~~~~~~ + +All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object. + +.. autofunction:: pytest_runtestloop +.. autofunction:: pytest_runtest_protocol +.. autofunction:: pytest_runtest_logstart +.. autofunction:: pytest_runtest_logfinish +.. autofunction:: pytest_runtest_setup +.. autofunction:: pytest_runtest_call +.. autofunction:: pytest_runtest_teardown +.. autofunction:: pytest_runtest_makereport + +For deeper understanding you may look at the default implementation of +these hooks in :py:mod:`_pytest.runner` and maybe also +in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture` +and its input/output capturing in order to immediately drop +into interactive debugging when a test failure occurs. + +The :py:mod:`_pytest.terminal` reported specifically uses +the reporting hook to print information about a test run. + +Collection hooks +~~~~~~~~~~~~~~~~ + +``pytest`` calls the following hooks for collecting files and directories: + +.. autofunction:: pytest_collection +.. autofunction:: pytest_ignore_collect +.. autofunction:: pytest_collect_directory +.. autofunction:: pytest_collect_file + +For influencing the collection of objects in Python modules +you can use the following hook: + +.. autofunction:: pytest_pycollect_makeitem +.. autofunction:: pytest_generate_tests +.. autofunction:: pytest_make_parametrize_id + +After collection is complete, you can modify the order of +items, delete or otherwise amend the test items: + +.. autofunction:: pytest_collection_modifyitems + +Reporting hooks +~~~~~~~~~~~~~~~ + +Session related reporting hooks: + +.. autofunction:: pytest_collectstart +.. autofunction:: pytest_itemcollected +.. autofunction:: pytest_collectreport +.. autofunction:: pytest_deselected +.. autofunction:: pytest_report_header +.. autofunction:: pytest_report_collectionfinish +.. autofunction:: pytest_report_teststatus +.. autofunction:: pytest_terminal_summary +.. autofunction:: pytest_fixture_setup +.. autofunction:: pytest_fixture_post_finalizer + +And here is the central hook for reporting about +test execution: + +.. autofunction:: pytest_runtest_logreport + +You can also use this hook to customize assertion representation for some +types: + +.. autofunction:: pytest_assertrepr_compare + + +Debugging/Interaction hooks +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are few hooks which can be used for special +reporting or interaction with exceptions: + +.. autofunction:: pytest_internalerror +.. autofunction:: pytest_keyboard_interrupt +.. autofunction:: pytest_exception_interact +.. autofunction:: pytest_enter_pdb + + +Objects +------- + +Full reference to objects accessible from :ref:`fixtures ` or :ref:`hooks `. + + +CallInfo +~~~~~~~~ + +.. autoclass:: _pytest.runner.CallInfo() + :members: + + +Class +~~~~~ + +.. autoclass:: _pytest.python.Class() + :members: + :show-inheritance: + +Collector +~~~~~~~~~ + +.. autoclass:: _pytest.nodes.Collector() + :members: + :show-inheritance: + +Config +~~~~~~ + +.. autoclass:: _pytest.config.Config() + :members: + +ExceptionInfo +~~~~~~~~~~~~~ + +.. autoclass:: _pytest._code.ExceptionInfo + :members: + +FixtureDef +~~~~~~~~~~ + +.. autoclass:: _pytest.fixtures.FixtureDef() + :members: + :show-inheritance: + +FSCollector +~~~~~~~~~~~ + +.. autoclass:: _pytest.nodes.FSCollector() + :members: + :show-inheritance: + +Function +~~~~~~~~ + +.. autoclass:: _pytest.python.Function() + :members: + :show-inheritance: + +Item +~~~~ + +.. autoclass:: _pytest.nodes.Item() + :members: + :show-inheritance: + +MarkDecorator +~~~~~~~~~~~~~ + +.. autoclass:: _pytest.mark.MarkDecorator + :members: + +MarkGenerator +~~~~~~~~~~~~~ + +.. autoclass:: _pytest.mark.MarkGenerator + :members: + +MarkInfo +~~~~~~~~ + +.. autoclass:: _pytest.mark.MarkInfo + :members: + +Metafunc +~~~~~~~~ + +.. autoclass:: _pytest.python.Metafunc + :members: + +Module +~~~~~~ + +.. autoclass:: _pytest.python.Module() + :members: + :show-inheritance: + +Node +~~~~ + +.. autoclass:: _pytest.nodes.Node() + :members: + +Parser +~~~~~~ + +.. autoclass:: _pytest.config.Parser() + :members: + +PluginManager +~~~~~~~~~~~~~ + +.. autoclass:: pluggy.PluginManager() + :members: + + +PytestPluginManager +~~~~~~~~~~~~~~~~~~~ + +.. autoclass:: _pytest.config.PytestPluginManager() + :members: + :undoc-members: + :show-inheritance: + +Session +~~~~~~~ + +.. autoclass:: _pytest.main.Session() + :members: + :show-inheritance: + +TestReport +~~~~~~~~~~ + +.. autoclass:: _pytest.runner.TestReport() + :members: + :inherited-members: + +_Result +~~~~~~~ + +.. autoclass:: pluggy._Result + :members: + +Special Variables +----------------- + +pytest treats some global variables in a special manner when defined in a test module. + + +pytest_plugins +~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`available installable plugins` + +Can be declared at the **global** level in *test modules* and *conftest.py files* to register additional plugins. +Can be either a ``str`` or ``Sequence[str]``. + +.. code-block:: python + + pytest_plugins = "myapp.testsupport.myplugin" + +.. code-block:: python + + pytest_plugins = ("myapp.testsupport.tools", "myapp.testsupport.regression") + + +pytest_mark +~~~~~~~~~~~ + +**Tutorial**: :ref:`scoped-marking` + +Can be declared at the **global** level in *test modules* to apply one or more :ref:`marks ` to all +test functions and methods. Can be either a single mark or a sequence of marks. + +.. code-block:: python + + import pytest + pytestmark = pytest.mark.webtest + + +.. code-block:: python + + import pytest + pytestmark = (pytest.mark.integration, pytest.mark.slow) + +PYTEST_DONT_REWRITE (module docstring) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The text ``PYTEST_DONT_REWRITE`` can be add to any **module docstring** to disable +:ref:`assertion rewriting ` for that module. + + +Environment Variables +--------------------- + +Environment variables that can be used to change pytest's behavior. + +PYTEST_ADDOPTS +~~~~~~~~~~~~~~ + +This contains a command-line (parsed by the py:mod:`shlex` module) that will be **prepended** to the command line given +by the user, see :ref:`adding default options` for more information. + +PYTEST_DEBUG +~~~~~~~~~~~~ + +When set, pytest will print tracing and debug information. + +PYTEST_PLUGINS +~~~~~~~~~~~~~~ + +Contains comma-separated list of modules that should be loaded as plugins: + +.. code-block:: bash + + export PYTEST_PLUGINS=mymodule.plugin,xdisst + + +PYTEST_CURRENT_TEST +~~~~~~~~~~~~~~~~~~~ + +This is not meant to be set by users, but is set by pytest internally with the name of the current test so other +processes can inspect it, see :ref:`pytest current test env` for more information. + + +.. _`ini options ref`: + +Configuration Options +--------------------- + +Here is a list of builtin configuration options that may be written in a ``pytest.ini``, ``tox.ini`` or ``setup.cfg`` +file, usually located at the root of your repository. All options must be under a ``[pytest]`` section +(``[tool:pytest]`` for ``setup.cfg`` files). + +Configuration file options may be overwritten in the command-line by using ``-o/--override``, which can also be +passed multiple times. The expected format is ``name=value``. For example:: + + pytest -o console_output_style=classic -o cache_dir=/tmp/mycache + + +.. confval:: addopts + + Add the specified ``OPTS`` to the set of command line arguments as if they + had been specified by the user. Example: if you have this ini file content: + + .. code-block:: ini + + # content of pytest.ini + [pytest] + addopts = --maxfail=2 -rf # exit after 2 failures, report fail info + + issuing ``pytest test_hello.py`` actually means:: + + pytest --maxfail=2 -rf test_hello.py + + Default is to add no options. + + +.. confval:: cache_dir + + .. versionadded:: 3.2 + + Sets a directory where stores content of cache plugin. Default directory is + ``.cache`` which is created in :ref:`rootdir `. Directory may be + relative or absolute path. If setting relative path, then directory is created + relative to :ref:`rootdir `. Additionally path may contain environment + variables, that will be expanded. For more information about cache plugin + please refer to :ref:`cache_provider`. + + +.. confval:: confcutdir + + Sets a directory where search upwards for ``conftest.py`` files stops. + By default, pytest will stop searching for ``conftest.py`` files upwards + from ``pytest.ini``/``tox.ini``/``setup.cfg`` of the project if any, + or up to the file-system root. + + +.. confval:: console_output_style + + .. versionadded:: 3.3 + + Sets the console output style while running tests: + + * ``classic``: classic pytest output. + * ``progress``: like classic pytest output, but with a progress indicator. + + The default is ``progress``, but you can fallback to ``classic`` if you prefer or + the new mode is causing unexpected problems: + + .. code-block:: ini + + # content of pytest.ini + [pytest] + console_output_style = classic + + +.. confval:: doctest_encoding + + .. versionadded:: 3.1 + + Default encoding to use to decode text files with docstrings. + :doc:`See how pytest handles doctests `. + + +.. confval:: doctest_optionflags + + One or more doctest flag names from the standard ``doctest`` module. + :doc:`See how pytest handles doctests `. + + +.. confval:: empty_parameter_set_mark + + .. versionadded:: 3.4 + + Allows to pick the action for empty parametersets in parameterization + + * ``skip`` skips tests with a empty parameterset (default) + * ``xfail`` marks tests with a empty parameterset as xfail(run=False) + + .. code-block:: ini + + # content of pytest.ini + [pytest] + empty_parameter_set_mark = xfail + + .. note:: + + The default value of this option is planned to change to ``xfail`` in future releases + as this is considered less error prone, see `#3155 `_ + for more details. + + +.. confval:: filterwarnings + + .. versionadded:: 3.1 + + Sets a list of filters and actions that should be taken for matched + warnings. By default all warnings emitted during the test session + will be displayed in a summary at the end of the test session. + + .. code-block:: ini + + # content of pytest.ini + [pytest] + filterwarnings = + error + ignore::DeprecationWarning + + This tells pytest to ignore deprecation warnings and turn all other warnings + into errors. For more information please refer to :ref:`warnings`. + + +.. confval:: junit_suite_name + + .. versionadded:: 3.1 + + To set the name of the root test suite xml item, you can configure the ``junit_suite_name`` option in your config file: + + .. code-block:: ini + + [pytest] + junit_suite_name = my_suite + + +.. confval:: log_cli_date_format + + .. versionadded:: 3.3 + + Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for live logging. + + .. code-block:: ini + + [pytest] + log_cli_date_format = %Y-%m-%d %H:%M:%S + + For more information, see :ref:`live_logs`. + +.. confval:: log_cli_format + + .. versionadded:: 3.3 + + Sets a :py:mod:`logging`-compatible string used to format live logging messages. + + .. code-block:: ini + + [pytest] + log_cli_format = %(asctime)s %(levelname)s %(message)s + + For more information, see :ref:`live_logs`. + + +.. confval:: log_cli_level + + .. versionadded:: 3.3 + + Sets the minimum log message level that should be captured for live logging. The integer value or + the names of the levels can be used. + + .. code-block:: ini + + [pytest] + log_cli_level = INFO + + For more information, see :ref:`live_logs`. + + +.. confval:: log_date_format + + .. versionadded:: 3.3 + + Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for logging capture. + + .. code-block:: ini + + [pytest] + log_date_format = %Y-%m-%d %H:%M:%S + + For more information, see :ref:`logging`. + + +.. confval:: log_file + + .. versionadded:: 3.3 + + Sets a file name relative to the ``pytest.ini`` file where log messages should be written to, in addition + to the other logging facilities that are active. + + .. code-block:: ini + + [pytest] + log_file = logs/pytest-logs.txt + + For more information, see :ref:`logging`. + + +.. confval:: log_file_date_format + + .. versionadded:: 3.3 + + Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for the logging file. + + .. code-block:: ini + + [pytest] + log_file_date_format = %Y-%m-%d %H:%M:%S + + For more information, see :ref:`logging`. + +.. confval:: log_file_format + + .. versionadded:: 3.3 + + Sets a :py:mod:`logging`-compatible string used to format logging messages redirected to the logging file. + + .. code-block:: ini + + [pytest] + log_file_format = %(asctime)s %(levelname)s %(message)s + + For more information, see :ref:`logging`. + +.. confval:: log_file_level + + .. versionadded:: 3.3 + + Sets the minimum log message level that should be captured for the logging file. The integer value or + the names of the levels can be used. + + .. code-block:: ini + + [pytest] + log_file_level = INFO + + For more information, see :ref:`logging`. + + +.. confval:: log_format + + .. versionadded:: 3.3 + + Sets a :py:mod:`logging`-compatible string used to format captured logging messages. + + .. code-block:: ini + + [pytest] + log_format = %(asctime)s %(levelname)s %(message)s + + For more information, see :ref:`logging`. + + +.. confval:: log_level + + .. versionadded:: 3.3 + + Sets the minimum log message level that should be captured for logging capture. The integer value or + the names of the levels can be used. + + .. code-block:: ini + + [pytest] + log_level = INFO + + For more information, see :ref:`logging`. + + +.. confval:: log_print + + .. versionadded:: 3.3 + + If set to ``False``, will disable displaying captured logging messages for failed tests. + + .. code-block:: ini + + [pytest] + log_print = False + + For more information, see :ref:`logging`. + + +.. confval:: markers + + List of markers that are allowed in test functions, enforced when ``--strict`` command-line argument is used. + You can use a marker name per line, indented from the option name. + + .. code-block:: ini + + [pytest] + markers = + slow + serial + +.. confval:: minversion + + Specifies a minimal pytest version required for running tests. + + .. code-block:: ini + + # content of pytest.ini + [pytest] + minversion = 3.0 # will fail if we run with pytest-2.8 + + +.. confval:: norecursedirs + + Set the directory basename patterns to avoid when recursing + for test discovery. The individual (fnmatch-style) patterns are + applied to the basename of a directory to decide if to recurse into it. + Pattern matching characters:: + + * matches everything + ? matches any single character + [seq] matches any character in seq + [!seq] matches any char not in seq + + Default patterns are ``'.*', 'build', 'dist', 'CVS', '_darcs', '{arch}', '*.egg', 'venv'``. + Setting a ``norecursedirs`` replaces the default. Here is an example of + how to avoid certain directories: + + .. code-block:: ini + + [pytest] + norecursedirs = .svn _build tmp* + + This would tell ``pytest`` to not look into typical subversion or + sphinx-build directories or into any ``tmp`` prefixed directory. + + Additionally, ``pytest`` will attempt to intelligently identify and ignore a + virtualenv by the presence of an activation script. Any directory deemed to + be the root of a virtual environment will not be considered during test + collection unless ``‑‑collect‑in‑virtualenv`` is given. Note also that + ``norecursedirs`` takes precedence over ``‑‑collect‑in‑virtualenv``; e.g. if + you intend to run tests in a virtualenv with a base directory that matches + ``'.*'`` you *must* override ``norecursedirs`` in addition to using the + ``‑‑collect‑in‑virtualenv`` flag. + + +.. confval:: python_classes + + One or more name prefixes or glob-style patterns determining which classes + are considered for test collection. By default, pytest will consider any + class prefixed with ``Test`` as a test collection. Here is an example of how + to collect tests from classes that end in ``Suite``: + + .. code-block:: ini + + [pytest] + python_classes = *Suite + + Note that ``unittest.TestCase`` derived classes are always collected + regardless of this option, as ``unittest``'s own collection framework is used + to collect those tests. + + +.. confval:: python_files + + One or more Glob-style file patterns determining which python files + are considered as test modules. By default, pytest will consider + any file matching with ``test_*.py`` and ``*_test.py`` globs as a test + module. + + +.. confval:: python_functions + + One or more name prefixes or glob-patterns determining which test functions + and methods are considered tests. By default, pytest will consider any + function prefixed with ``test`` as a test. Here is an example of how + to collect test functions and methods that end in ``_test``: + + .. code-block:: ini + + [pytest] + python_functions = *_test + + Note that this has no effect on methods that live on a ``unittest + .TestCase`` derived class, as ``unittest``'s own collection framework is used + to collect those tests. + + See :ref:`change naming conventions` for more detailed examples. + + +.. confval:: testpaths + + .. versionadded:: 2.8 + + Sets list of directories that should be searched for tests when + no specific directories, files or test ids are given in the command line when + executing pytest from the :ref:`rootdir ` directory. + Useful when all project tests are in a known location to speed up + test collection and to avoid picking up undesired tests by accident. + + .. code-block:: ini + + [pytest] + testpaths = testing doc + + This tells pytest to only look for tests in ``testing`` and ``doc`` + directories when executing from the root directory. + + +.. confval:: usefixtures + + List of fixtures that will be applied to all test functions; this is semantically the same to apply + the ``@pytest.mark.usefixtures`` marker to all test functions. + + + .. code-block:: ini + + [pytest] + usefixtures = + clean_db + + +.. confval:: xfail_strict + + If set to ``True``, tests marked with ``@pytest.mark.xfail`` that actually succeed will by default fail the + test suite. + For more information, see :ref:`xfail strict tutorial`. + + + .. code-block:: ini + + [pytest] + xfail_strict = True diff --git a/doc/en/requirements.txt b/doc/en/requirements.txt index 72bb60a81..e3cc47ed5 100644 --- a/doc/en/requirements.txt +++ b/doc/en/requirements.txt @@ -1,3 +1,4 @@ # pinning sphinx to 1.4.* due to search issues with rtd: # https://github.com/rtfd/readthedocs-sphinx-ext/issues/25 sphinx ==1.4.* +sphinxcontrib-trio diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst index 7e001929b..9bac02c8c 100644 --- a/doc/en/skipping.rst +++ b/doc/en/skipping.rst @@ -71,6 +71,8 @@ It is also possible to skip the whole module using The imperative method is useful when it is not possible to evaluate the skip condition during import time. +**Reference**: :ref:`pytest.mark.skip ref` + ``skipif`` ~~~~~~~~~~ @@ -116,6 +118,8 @@ Alternatively, you can use :ref:`condition strings ` instead of booleans, but they can't be shared between modules easily so they are supported mainly for backward compatibility reasons. +**Reference**: :ref:`pytest.mark.skipif ref` + Skip all test functions of a class or module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -232,15 +236,10 @@ This will unconditionally make ``test_function`` ``XFAIL``. Note that no other c after ``pytest.xfail`` call, differently from the marker. That's because it is implemented internally by raising a known exception. -Here's the signature of the ``xfail`` **marker** (not the function), using Python 3 keyword-only -arguments syntax: - -.. code-block:: python - - def xfail(condition=None, *, reason=None, raises=None, run=True, strict=False): - +**Reference**: :ref:`pytest.mark.xfail ref` +.. _`xfail strict tutorial`: ``strict`` parameter ~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/en/tmpdir.rst b/doc/en/tmpdir.rst index b9c371e40..e01d359e0 100644 --- a/doc/en/tmpdir.rst +++ b/doc/en/tmpdir.rst @@ -51,6 +51,9 @@ Running this would result in a passed test except for the last test_tmpdir.py:7: AssertionError ========================= 1 failed in 0.12 seconds ========================= + +.. _`tmpdir factory example`: + The 'tmpdir_factory' fixture ---------------------------- @@ -81,12 +84,8 @@ to save time: img = load_image(image_file) # compute and test histogram -``tmpdir_factory`` instances have the following methods: +See :ref:`tmpdir_factory API ` for details. -.. currentmodule:: _pytest.tmpdir - -.. automethod:: TempdirFactory.mktemp -.. automethod:: TempdirFactory.getbasetemp .. _`base temporary directory`: diff --git a/doc/en/usage.rst b/doc/en/usage.rst index 2b86420bb..174954ce4 100644 --- a/doc/en/usage.rst +++ b/doc/en/usage.rst @@ -220,8 +220,10 @@ To set the name of the root test suite xml item, you can configure the ``junit_s [pytest] junit_suite_name = my_suite +.. _record_property example: + record_property -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^ .. versionadded:: 2.8 .. versionchanged:: 3.5 @@ -306,7 +308,7 @@ To add an additional xml attribute to a testcase element, you can use print('hello world') assert True -Unlike ``record_xml_property``, this will not add a new child element. +Unlike ``record_property``, this will not add a new child element. Instead, this will add an attribute ``assertions="REQ-1234"`` inside the generated ``testcase`` tag and override the default ``classname`` with ``"classname=custom_classname"``: @@ -371,7 +373,7 @@ to all testcases you can use ``LogXML.add_global_properties`` my_junit.add_global_property('ARCH', 'PPC') my_junit.add_global_property('STORAGE_TYPE', 'CEPH') - @pytest.mark.usefixtures(log_global_env_facts) + @pytest.mark.usefixtures(log_global_env_facts.__name__) def start_and_prepare_env(): pass diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst index d5a627aea..df61e1f38 100644 --- a/doc/en/warnings.rst +++ b/doc/en/warnings.rst @@ -250,23 +250,11 @@ The ``recwarn`` fixture will record warnings for the whole function:: Both ``recwarn`` and ``pytest.warns`` return the same interface for recorded warnings: a WarningsRecorder instance. To view the recorded warnings, you can iterate over this instance, call ``len`` on it to get the number of recorded -warnings, or index into it to get a particular recorded warning. It also -provides these methods: +warnings, or index into it to get a particular recorded warning. -.. autoclass:: _pytest.recwarn.WarningsRecorder() - :members: +.. currentmodule:: _pytest.warnings -Each recorded warning has the attributes ``message``, ``category``, -``filename``, ``lineno``, ``file``, and ``line``. The ``category`` is the -class of the warning. The ``message`` is the warning itself; calling -``str(message)`` will return the actual message of the warning. - -.. note:: - :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1 - -.. note:: - ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated - differently; see :ref:`ensuring_function_triggers`. +Full API: :class:`WarningsRecorder`. .. _`ensuring a function triggers a deprecation warning`: diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst index d88bb8f15..dab88da22 100644 --- a/doc/en/writing_plugins.rst +++ b/doc/en/writing_plugins.rst @@ -12,9 +12,9 @@ only want to use but not write plugins. A plugin contains one or multiple hook functions. :ref:`Writing hooks ` explains the basics and details of how you can write a hook function yourself. ``pytest`` implements all aspects of configuration, collection, running and -reporting by calling `well specified hooks`_ of the following plugins: +reporting by calling :ref:`well specified hooks ` of the following plugins: -* :ref:`builtin plugins`: loaded from pytest's internal ``_pytest`` directory. +* builtin plugins: loaded from pytest's internal ``_pytest`` directory. * :ref:`external plugins `: modules discovered through `setuptools entry points`_ @@ -109,10 +109,10 @@ If you want to write a plugin, there are many real-life examples you can copy from: * a custom collection example plugin: :ref:`yaml plugin` -* around 20 :ref:`builtin plugins` which provide pytest's own functionality +* builtin plugins which provide pytest's own functionality * many `external plugins `_ providing additional features -All of these plugins implement the documented `well specified hooks`_ +All of these plugins implement :ref:`hooks ` and/or :ref:`fixtures ` to extend and add functionality. .. note:: @@ -167,7 +167,7 @@ it in your setuptools-invocation: If a package is installed this way, ``pytest`` will load ``myproject.pluginmodule`` as a plugin which can define -`well specified hooks`_. +:ref:`hooks `. .. note:: @@ -176,6 +176,8 @@ If a package is installed this way, ``pytest`` will load to make it easy for users to find your plugin. +.. _assertion-rewriting: + Assertion Rewriting ------------------- @@ -196,6 +198,7 @@ assertion rewriting to be enabled you need to ask ``pytest`` explicitly to rewrite this module before it gets imported. .. autofunction:: pytest.register_assert_rewrite + :noindex: This is especially important when you write a pytest plugin which is created using a package. The import hook only treats ``conftest.py`` @@ -540,6 +543,7 @@ implemented by other plugins in order to alter behaviour or interact with the new plugin: .. autofunction:: pytest_addhooks + :noindex: Hooks are usually declared as do-nothing functions that contain only documentation describing when the hook will be called and what return values @@ -577,191 +581,7 @@ declaring the hook functions directly in your plugin module, for example:: This has the added benefit of allowing you to conditionally install hooks depending on which plugins are installed. -.. _`well specified hooks`: - -.. currentmodule:: _pytest.hookspec - -pytest hook reference -===================== -Initialization, command line and configuration hooks ----------------------------------------------------- - -Bootstrapping hooks -~~~~~~~~~~~~~~~~~~~ - -Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins). - -.. autofunction:: pytest_load_initial_conftests -.. autofunction:: pytest_cmdline_preparse -.. autofunction:: pytest_cmdline_parse -.. autofunction:: pytest_cmdline_main - -Initialization hooks -~~~~~~~~~~~~~~~~~~~~ - -Initialization hooks called for plugins and ``conftest.py`` files. - -.. autofunction:: pytest_addoption -.. autofunction:: pytest_configure -.. autofunction:: pytest_unconfigure - -Generic "runtest" hooks ------------------------ - -All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object. - -.. autofunction:: pytest_runtestloop -.. autofunction:: pytest_runtest_protocol -.. autofunction:: pytest_runtest_logstart -.. autofunction:: pytest_runtest_logfinish -.. autofunction:: pytest_runtest_setup -.. autofunction:: pytest_runtest_call -.. autofunction:: pytest_runtest_teardown -.. autofunction:: pytest_runtest_makereport - -For deeper understanding you may look at the default implementation of -these hooks in :py:mod:`_pytest.runner` and maybe also -in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture` -and its input/output capturing in order to immediately drop -into interactive debugging when a test failure occurs. - -The :py:mod:`_pytest.terminal` reported specifically uses -the reporting hook to print information about a test run. - -Collection hooks ----------------- - -``pytest`` calls the following hooks for collecting files and directories: - -.. autofunction:: pytest_collection -.. autofunction:: pytest_ignore_collect -.. autofunction:: pytest_collect_directory -.. autofunction:: pytest_collect_file - -For influencing the collection of objects in Python modules -you can use the following hook: - -.. autofunction:: pytest_pycollect_makeitem -.. autofunction:: pytest_generate_tests -.. autofunction:: pytest_make_parametrize_id - -After collection is complete, you can modify the order of -items, delete or otherwise amend the test items: - -.. autofunction:: pytest_collection_modifyitems - -Reporting hooks ---------------- - -Session related reporting hooks: - -.. autofunction:: pytest_collectstart -.. autofunction:: pytest_itemcollected -.. autofunction:: pytest_collectreport -.. autofunction:: pytest_deselected -.. autofunction:: pytest_report_header -.. autofunction:: pytest_report_collectionfinish -.. autofunction:: pytest_report_teststatus -.. autofunction:: pytest_terminal_summary -.. autofunction:: pytest_fixture_setup -.. autofunction:: pytest_fixture_post_finalizer - -And here is the central hook for reporting about -test execution: - -.. autofunction:: pytest_runtest_logreport - -You can also use this hook to customize assertion representation for some -types: - -.. autofunction:: pytest_assertrepr_compare -Debugging/Interaction hooks ---------------------------- - -There are few hooks which can be used for special -reporting or interaction with exceptions: - -.. autofunction:: pytest_internalerror -.. autofunction:: pytest_keyboard_interrupt -.. autofunction:: pytest_exception_interact -.. autofunction:: pytest_enter_pdb - - -Reference of objects involved in hooks -====================================== - -.. autoclass:: _pytest.config.Config() - :members: - -.. autoclass:: _pytest.config.Parser() - :members: - -.. autoclass:: _pytest.nodes.Node() - :members: - -.. autoclass:: _pytest.nodes.Collector() - :members: - :show-inheritance: - -.. autoclass:: _pytest.nodes.FSCollector() - :members: - :show-inheritance: - -.. autoclass:: _pytest.main.Session() - :members: - :show-inheritance: - -.. autoclass:: _pytest.nodes.Item() - :members: - :show-inheritance: - -.. autoclass:: _pytest.python.Module() - :members: - :show-inheritance: - -.. autoclass:: _pytest.python.Class() - :members: - :show-inheritance: - -.. autoclass:: _pytest.python.Function() - :members: - :show-inheritance: - -.. autoclass:: _pytest.fixtures.FixtureDef() - :members: - :show-inheritance: - -.. autoclass:: _pytest.runner.CallInfo() - :members: - -.. autoclass:: _pytest.runner.TestReport() - :members: - :inherited-members: - -.. autoclass:: pluggy._Result - :members: - -.. autofunction:: _pytest.config.get_plugin_manager() - -.. autoclass:: _pytest.config.PytestPluginManager() - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: pluggy.PluginManager() - :members: - -.. currentmodule:: _pytest.pytester - -.. autoclass:: Testdir() - :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile - -.. autoclass:: RunResult() - :members: - -.. autoclass:: LineMatcher() - :members: diff --git a/testing/logging/test_fixture.py b/testing/logging/test_fixture.py index 204472c80..24576719d 100644 --- a/testing/logging/test_fixture.py +++ b/testing/logging/test_fixture.py @@ -95,8 +95,10 @@ def test_clear(caplog): caplog.set_level(logging.INFO) logger.info(u'bū') assert len(caplog.records) + assert caplog.text caplog.clear() assert not len(caplog.records) + assert not caplog.text @pytest.fixture diff --git a/testing/test_capture.py b/testing/test_capture.py index 69afa0f9c..7fccc055d 100644 --- a/testing/test_capture.py +++ b/testing/test_capture.py @@ -751,7 +751,8 @@ def test_dontreadfrominput(): assert not f.isatty() pytest.raises(IOError, f.read) pytest.raises(IOError, f.readlines) - pytest.raises(IOError, iter, f) + iter_f = iter(f) + pytest.raises(IOError, next, iter_f) pytest.raises(UnsupportedOperation, f.fileno) f.close() # just for completeness @@ -764,7 +765,8 @@ def test_dontreadfrominput_buffer_python3(): assert not fb.isatty() pytest.raises(IOError, fb.read) pytest.raises(IOError, fb.readlines) - pytest.raises(IOError, iter, fb) + iter_f = iter(f) + pytest.raises(IOError, next, iter_f) pytest.raises(ValueError, fb.fileno) f.close() # just for completeness @@ -1265,6 +1267,30 @@ def test_dontreadfrominput_has_encoding(testdir): reprec.assertoutcome(passed=1) +def test_crash_on_closing_tmpfile_py27(testdir): + testdir.makepyfile(''' + from __future__ import print_function + import time + import threading + import sys + + def spam(): + f = sys.stderr + while True: + print('.', end='', file=f) + + def test_silly(): + t = threading.Thread(target=spam) + t.daemon = True + t.start() + time.sleep(0.5) + + ''') + result = testdir.runpytest_subprocess() + assert result.ret == 0 + assert 'IOError' not in result.stdout.str() + + def test_pickling_and_unpickling_encoded_file(): # See https://bitbucket.org/pytest-dev/pytest/pull-request/194 # pickle.loads() raises infinite recursion if diff --git a/tox.ini b/tox.ini index b90bd432d..c4f3516a6 100644 --- a/tox.ini +++ b/tox.ini @@ -125,12 +125,13 @@ deps = [testenv:docs] skipsdist = True usedevelop = True -basepython = python changedir = doc/en deps = - sphinx attrs + more_itertools PyYAML + sphinx + sphinxcontrib-trio commands = sphinx-build -W -b html . _build @@ -204,7 +205,7 @@ rsyncdirs = tox.ini pytest.py _pytest testing python_files = test_*.py *_test.py testing/*/*.py python_classes = Test Acceptance python_functions = test -norecursedirs = .tox ja .hg cx_freeze_source +norecursedirs = .tox ja .hg cx_freeze_source doc xfail_strict=true filterwarnings = error