diff options
Diffstat (limited to 'testing/web-platform/tests/tools/pytest/doc/en/builtin.rst')
| -rw-r--r-- | testing/web-platform/tests/tools/pytest/doc/en/builtin.rst | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/testing/web-platform/tests/tools/pytest/doc/en/builtin.rst b/testing/web-platform/tests/tools/pytest/doc/en/builtin.rst new file mode 100644 index 000000000..b18c3f828 --- /dev/null +++ b/testing/web-platform/tests/tools/pytest/doc/en/builtin.rst @@ -0,0 +1,134 @@ + +.. _`pytest helpers`: + +Pytest API and builtin fixtures +================================================ + +This is a list of ``pytest.*`` API functions and fixtures. + +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:: + + 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 + +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.runner.fail +.. autofunction:: _pytest.runner.skip +.. autofunction:: _pytest.runner.importorskip +.. autofunction:: _pytest.skipping.xfail +.. autofunction:: _pytest.runner.exit + +fixtures and requests +----------------------------------------------------- + +To mark a fixture function: + +.. autofunction:: _pytest.python.fixture + +Tutorial at :ref:`fixtures`. + +The ``request`` object that can be used from fixture functions. + +.. autoclass:: _pytest.python.FixtureRequest() + :members: + + +.. _builtinfixtures: +.. _builtinfuncargs: + +Builtin fixtures/function arguments +----------------------------------------- + +You can ask for available builtin or project-custom +:ref:`fixtures <fixtures>` by typing:: + + $ py.test -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 + enables capturing of writes to sys.stdout/sys.stderr and makes + captured output available via ``capsys.readouterr()`` method calls + which return a ``(out, err)`` tuple. + capfd + enables capturing of writes to file descriptors 1 and 2 and makes + captured output available via ``capfd.readouterr()`` method calls + which return a ``(out, err)`` tuple. + record_xml_property + Fixture that adds extra xml properties to the tag for the calling test. + The fixture is callable with (name, value), with value being automatically + xml-encoded. + monkeypatch + The returned ``monkeypatch`` funcarg 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 has finished. The ``raising`` + parameter determines if a KeyError or AttributeError + will be raised if the set/deletion operation has no target. + pytestconfig + the pytest config object with access to command line opts. + 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 |