_pytest.pytester module¶
(disabled by default) support for testing pytest and pytest plugins.
-
__pytest
(request: _pytest.fixtures.FixtureRequest) → PytestArg[source]¶ Return a helper which offers a gethookrecorder(hook) method which returns a HookRecorder instance which helps to make assertions about called hooks.
-
class
PytestArg
(request: _pytest.fixtures.FixtureRequest)[source]¶ Bases:
object
-
gethookrecorder
(hook) → _pytest.pytester.HookRecorder[source]¶
-
-
get_public_names
(values)[source]¶ Only return names from iterator values without a leading underscore.
-
class
HookRecorder
(pluginmanager)[source]¶ Bases:
object
Record all hooks called in a plugin manager.
This wraps all the hook calls in the plugin manager, recording each call before propagating the normal calls.
-
getcalls
(names: Union[str, Iterable[str]]) → List[_pytest.pytester.ParsedCall][source]¶
-
popcall
(name: str) → _pytest.pytester.ParsedCall[source]¶
-
getcall
(name: str) → _pytest.pytester.ParsedCall[source]¶
-
getreports
(names: Union[str, Iterable[str]] = 'pytest_runtest_logreport pytest_collectreport') → List[_pytest.reports.TestReport][source]¶
-
matchreport
(inamepart: str = '', names: Union[str, Iterable[str]] = 'pytest_runtest_logreport pytest_collectreport', when=None)[source]¶ return a testreport whose dotted import path matches
-
getfailures
(names: Union[str, Iterable[str]] = 'pytest_runtest_logreport pytest_collectreport') → List[_pytest.reports.TestReport][source]¶
-
getfailedcollections
() → List[_pytest.reports.TestReport][source]¶
-
listoutcomes
() → Tuple[List[_pytest.reports.TestReport], List[_pytest.reports.TestReport], List[_pytest.reports.TestReport]][source]¶
-
-
linecomp
(request: _pytest.fixtures.FixtureRequest) → LineComp[source]¶
-
LineMatcher_fixture
(request: _pytest.fixtures.FixtureRequest) → Type[LineMatcher][source]¶
-
testdir
(request: _pytest.fixtures.FixtureRequest, tmpdir_factory) → Testdir[source]¶
-
class
RunResult
(ret: Union[int, _pytest.config.ExitCode], outlines: List[str], errlines: List[str], duration: float)[source]¶ Bases:
object
The result of running a command.
-
outlines
¶ list of lines captured from stdout
-
errlines
¶ list of lines captured from stderr
-
stdout
¶ LineMatcher
of stdout.Use e.g.
stdout.str()
to reconstruct stdout, or the commonly usedstdout.fnmatch_lines()
method.
-
stderr
¶ LineMatcher
of stderr
-
duration
¶ duration in seconds
-
-
for ... in
pytest_runtest_call
(item: _pytest.python.Function) → Generator[None, None, None][source]¶ Setup/activate testdir’s monkeypatching only during test calls.
When it would be done via the instance/fixture directly it would also be active during teardown (e.g. with the terminal plugin’s reporting), where it might mess with the column width etc.
-
class
Testdir
(*args, **kwds)[source]¶ Bases:
typing.Generic
Temporary test directory with tools to test/run pytest itself.
This is based on the
tmpdir fixture
, but provides a number of methods which aid with testing pytest itself. Unlesschdir()
is used all methods will usetmpdir
as their current working directory.-
CLOSE_STDIN
= 1¶ Sentinel to close stdin.
-
tmpdir
: py.path.local¶ The base temporary directory.
- Type
py.path.local
-
plugins
: List[Union[str, _PluggyPlugin]]¶ A list of plugins to use with
parseconfig()
andrunpytest()
.Initially this is an empty list but plugins can be added to the list. The type of items to add to the list depends on the method using them so refer to them for details.
-
finalize
()[source]¶ Clean up global state artifacts.
Some methods modify the global interpreter state and this tries to clean this up. It does not remove the temporary directory however so it can be looked at after the test run has finished.
-
make_hook_recorder
(pluginmanager)[source]¶ Create a new
HookRecorder
for a PluginManager.
-
_makefile
(ext: str, lines: Sequence[Union[bytes, str]], files: Mapping[str, Sequence[Union[bytes, str]]], encoding='utf-8') → py._path.local.LocalPath[source]¶
-
makefile
(ext, *args, **kwargs)[source]¶ Create new file(s) in the testdir.
- Parameters
ext (str) – The extension the file(s) should use, including the dot, e.g.
.py
.args (list[str]) – All args will be treated as strings and joined using newlines. The result will be written as contents to the file. The name of the file will be based on the test function requesting this fixture.
kwargs – Each keyword is the name of a file, while the value of it will be written as contents of the file.
Examples:
testdir.makefile(".txt", "line1", "line2") testdir.makefile(".ini", pytest="[pytest]\naddopts=-rs\n")
See also
makefiles()
.
-
makepyfile
(*args, **kwargs) → py._path.local.LocalPath[source]¶ Shortcut for .makefile() with a .py extension.
-
makefiles
(files: Mapping[str, str], *, base_path: Optional[Union[str, pathlib.Path]] = None, dedent: bool = True, strip_outer_newlines: bool = True, clobber: bool = False) → List[pathlib.Path][source]¶ Create the given set of files.
This is a more straight-forward API than the other helpers (e.g.
makepyfile()
).- Parameters
Mapping of filenames to file contents.
Absolute paths are handled, but have to be inside of
tmpdir
.base_path – Optional base path for relative paths (defaults to current working directory).
dedent (bool) – Dedent the contents (via
textwrap.dedent()
).strip_outer_newlines (bool) – Strip leading and trailing newlines from contents.
clobber (bool) –
Overwrite existing files or (dangling) symlinks.
(Dangling) symlinks are replaced with regular files.
- Returns
List[_pytest.pathlib.Path]
-
syspathinsert
(path=None)[source]¶ Prepend a directory to sys.path, defaults to
tmpdir
.This is undone automatically at the end of each test.
-
mkpydir
(name)[source]¶ Create a new python package.
This creates a (sub)directory with an empty
__init__.py
file so it gets recognised as a python package.
-
copy_example
(name=None)[source]¶ Copy file from project’s directory into the testdir.
- Parameters
name (str) – The name of the file to copy.
- Returns
path to the copied directory (inside
self.tmpdir
).
-
class
Session
(*k, **kw)¶ Bases:
_pytest.nodes.FSCollector
-
exception
Interrupted
¶ Bases:
KeyboardInterrupt
signals an interrupted test run.
-
for ... in
_collect
(argpath, names)¶
-
_fixturemanager
= None¶
-
_matchnodes
(matching, names)¶
-
_parsearg
(arg)¶ return (fspath, names) tuple after checking the file exists.
-
_perform_collect
(args, genitems)¶
-
_setupstate
= None¶
-
_tryconvertpyarg
(x)¶ Convert a dotted module name to path.
-
staticmethod
_visit_filter
(f)¶
-
for ... in
collect
()¶ returns a list of children (items and collectors) for this collection node.
-
exitstatus
= None¶
-
classmethod
from_config
(config)¶
-
for ... in
genitems
(node)¶
-
gethookproxy
(fspath: py._path.local.LocalPath)¶
-
isinitpath
(path)¶
-
matchnodes
(matching, names)¶
-
perform_collect
(args=None, genitems=True)¶
-
pytest_collectreport
(report)¶
-
pytest_collectstart
()¶
-
pytest_deselected
(items)¶ Keep track of explicitly deselected items.
-
pytest_ignore_collect
(path: py._path.local.LocalPath, config: _pytest.config.Config) → Optional[Tuple[Literal[True], Optional[str]]]¶
-
pytest_runtest_logreport
(report)¶
-
exception
-
getnode
(config, arg)[source]¶ Return the collection node of a file.
- Parameters
config –
_pytest.config.Config
instance, seeparseconfig()
andparseconfigure()
to create the configurationarg – a py.path.local instance of the file
-
getpathnode
(path)[source]¶ Return the collection node of a file.
This is like
getnode()
but usesparseconfigure()
to create the (configured) pytest Config instance.- Parameters
path (py.path.local) – the file
-
genitems
(colitems)[source]¶ Generate all test items from a collection node.
This recurses into the collection node and returns a list of all the test items contained within.
-
runitem
(source)[source]¶ Run the “test_func” Item.
The calling test instance (class containing the test method) must provide a
.getrunner()
method which should return a runner which can run the test protocol for a single item, e.g._pytest.runner.runtestprotocol()
.
-
inline_runsource
(source, *cmdlineargs)[source]¶ Run a test module in process using
pytest.main()
.This run writes “source” into a temporary file and runs
pytest.main()
on it, returning aHookRecorder
instance for the result.- Parameters
source – the source code of the test module
cmdlineargs – any extra command line arguments to use
- Returns
HookRecorder
instance of the result
-
inline_genitems
(*args)[source]¶ Run
pytest.main(['--collectonly'])
in-process.Runs the
pytest.main()
function to run all of pytest inside the test process itself likeinline_run()
, but returns a tuple of the collected items and aHookRecorder
instance.
-
inline_run
(*args, plugins=(), no_reraise_ctrlc: bool = False)[source]¶ Run
pytest.main()
in-process, returning a HookRecorder.Runs the
pytest.main()
function to run all of pytest inside the test process itself. This means it can return aHookRecorder
instance which gives more detailed results from that run than can be done by matching stdout/stderr fromrunpytest()
.- Parameters
args – command line arguments to pass to
pytest.main()
plugins – extra plugin instances the
pytest.main()
instance should use.no_reraise_ctrlc – typically we reraise keyboard interrupts from the child run. If True, the KeyboardInterrupt exception is captured.
- Returns
a
HookRecorder
instance
-
runpytest_inprocess
(*args, tty=None, **kwargs) → _pytest.pytester.RunResult[source]¶ Return result of running pytest in-process, providing a similar interface to what self.runpytest() provides.
-
runpytest
(*args_, tty=None, **kwargs) → _pytest.pytester.RunResult[source]¶ Run pytest inline or in a subprocess, depending on the command line option “–runpytest” and return a
RunResult
.
-
_ensure_basetemp
(args: Sequence[Union[str, py._path.local.LocalPath]]) → List[Union[str, py._path.local.LocalPath]][source]¶
-
parseconfig
(*args_: Union[str, py._path.local.LocalPath]) → _pytest.config.Config[source]¶ Return a new pytest Config instance from given commandline args.
This invokes the pytest bootstrapping code in _pytest.config to create a new
_pytest.core.PluginManager
and call the pytest_cmdline_parse hook to create a new_pytest.config.Config
instance.If
plugins
has been populated they should be plugin modules to be registered with the PluginManager.
-
parseconfigure
(*args)[source]¶ Return a new pytest configured Config instance.
This returns a new
_pytest.config.Config
instance likeparseconfig()
, but also calls the pytest_configure hook.
-
getitem
(source, funcname='test_func')[source]¶ Return the test item for a test function.
This writes the source to a python file and runs pytest’s collection on the resulting module, returning the test item for the requested function name.
- Parameters
source – the module source
funcname – the name of the test function for which to return a test item
-
getitems
(source)[source]¶ Return all test items collected from the module.
This writes the source to a python file and runs pytest’s collection on the resulting module, returning all test items contained within.
-
getmodulecol
(source, configargs=(), withinit=False)[source]¶ Return the module collection node for
source
.This writes
source
to a file usingmakepyfile()
and then runs the pytest collection on it, returning the collection node for the test module.- Parameters
source – the source code of the module to collect
configargs – any extra arguments to pass to
parseconfigure()
withinit – whether to also write an
__init__.py
file to the same directory to ensure it is a package
-
collect_by_name
(modcol: _pytest.python.Module, name: str) → Optional[Union[_pytest.nodes.Item, _pytest.nodes.Collector]][source]¶ Return the collection node for name from the module collection.
This will search a module collection node for a collection node matching the given name.
- Parameters
modcol – a module collection node; see
getmodulecol()
name – the name of the node to return
-
popen
(cmdargs, stdout: Optional[Union[int, IO]] = -1, stderr: Optional[Union[int, IO]] = -1, stdin: Optional[Union[_pytest.capture.CloseStdinType, bytes, str, int, IO]] = <CloseStdinType.CLOSE_STDIN: 1>, *, encoding: Optional[str] = None, **kw) → Union[subprocess.Popen[bytes], subprocess.Popen[str]][source]¶ Invoke subprocess.Popen.
This calls subprocess.Popen making sure the current working directory is in the PYTHONPATH.
encoding
is only supported with Python 3.6+.You probably want to use
run()
instead.
-
run
(*cmdargs, timeout=None, stdin: Optional[Union[_pytest.capture.CloseStdinType, bytes, str, int, IO]] = <CloseStdinType.CLOSE_STDIN: 1>) → _pytest.pytester.RunResult[source]¶ Run a command with arguments.
Run a process using :class:<python:subprocess.Popen> saving the stdout and stderr.
- Parameters
args – the sequence of arguments to pass to
subprocess.Popen()
timeout – the period in seconds after which to timeout and raise
Testdir.TimeoutExpired
stdin –
optional standard input. Bytes/strings are being send, closing the pipe, otherwise it is passed through to
popen
.Defaults to
CLOSE_STDIN
, which translates to using a pipe (subprocess.PIPE
) that gets closed.
Returns a
RunResult
.
-
runpython
(script) → _pytest.pytester.RunResult[source]¶ Run a python script using sys.executable as interpreter.
Returns a
RunResult
.
-
runpytest_subprocess
(*args, stdin=<CloseStdinType.CLOSE_STDIN: 1>, timeout=None) → _pytest.pytester.RunResult[source]¶ Run pytest as a subprocess with given arguments.
Any plugins added to the
plugins
list will be added using the-p
command line option. Additionally--basetemp
is used to put any temporary files and directories in a numbered directory prefixed with “runpytest-” to not conflict with the normal numbered pytest location for temporary files and directories.- Parameters
args – the sequence of arguments to pass to the pytest subprocess
timeout – the period in seconds after which to timeout and raise
Testdir.TimeoutExpired
stdin – optional standard input. Passed through to
run()
.
Returns a
RunResult
.
-
spawn_pytest
(*args: str, **kwargs) → pexpect.spawn[source]¶ Run pytest using pexpect.
This makes sure to use the right pytest and sets up the temporary directory locations.
The pexpect child is returned.
-
spawn
(*args: str, **kwargs) → pexpect.spawn[source]¶ Run a command using pexpect.
The pexpect child is returned.
-
_Testdir__take_sys_modules_snapshot
()¶
-
-
exception
LineMatcherFailed
(*, msg: str, log_output: List[str])[source]¶ Bases:
_pytest.outcomes.Failed
-
class
LineMatcher
(lines: List[str])[source]¶ Bases:
object
Flexible matching of text.
This is a convenience class to test large texts like the output of commands.
- Parameters
lines (List[str]) – a list of lines without their trailing newlines, e.g. from
text.splitlines()
.
-
fnmatch_lines_random
(lines2: Sequence[str]) → None[source]¶ Check lines exist in the output in any order (using
fnmatch.fnmatch()
).
-
re_match_lines_random
(lines2: Sequence[str]) → None[source]¶ Check lines exist in the output in any order (using
re.match()
).
-
get_lines_after
(fnline: str) → Sequence[str][source]¶ Return all lines following the given line in the text.
The given line can contain glob wildcards.
-
_log_text
¶
-
fnmatch_lines
(lines2: Sequence[str], *, consecutive: bool = False, complete: bool = False) → None[source]¶ Check lines exist in the output (using
fnmatch.fnmatch()
).The argument is a list of lines which have to match and can use glob wildcards. If they do not match a pytest.fail() is called. The matches and non-matches are also shown as part of the error message.
-
re_match_lines
(lines2: Sequence[str], *, consecutive: bool = False, complete: bool = False) → None[source]¶ Check lines exist in the output (using
re.match()
).The argument is a list of lines which have to match using
re.match
. If they do not match a pytest.fail() is called.The matches and non-matches are also shown as part of the error message.
-
_match_lines
(lines2: Sequence[str], match_func: Callable[[str, str], bool], match_nickname: str, *, consecutive: bool = False, complete: bool = False) → None[source]¶ Underlying implementation of
fnmatch_lines
andre_match_lines
.- Parameters
lines2 (list[str]) – list of string patterns to match. The actual format depends on
match_func
match_func – a callable
match_func(line, pattern)
where line is the captured line from stdout/stderr and pattern is the matching patternmatch_nickname (str) – the nickname for the match function that will be logged to stdout when a match occurs
consecutive (bool) – match lines consecutively?
complete (bool) – require all lines to be matched in total
-
no_fnmatch_line
(pat: str) → None[source]¶ Ensure captured lines do not match the given pattern, using
fnmatch.fnmatch
.- Parameters
pat (str) – the pattern to match lines.
-
no_re_match_line
(pat: str) → None[source]¶ Ensure captured lines do not match the given pattern, using
re.match
.- Parameters
pat (str) – the regular expression to match lines.