_pytest.pytester module

(disabled by default) support for testing pytest and pytest plugins.

pytest_addoption(parser)

pytest_configure(config)

class LsofFdLeakChecker

Bases: object

get_open_files()

_exec_lsof()

_parse_lsof_output(out)

matching_platform()

for ... in pytest_runtest_protocol(item)

__pytest(request: _pytest.fixtures.FixtureRequest) → PytestArg

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)

Bases: object

gethookrecorder(hook) → _pytest.pytester.HookRecorder

get_public_names(values)

Only return names from iterator values without a leading underscore.

class ParsedCall(name, kwargs)

Bases: object

class HookRecorder(pluginmanager)

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.

finish_recording() → None

getcalls(names: Union[str, Iterable[str]]) → List[_pytest.pytester.ParsedCall]

assert_contains(entries) → None

popcall(name: str) → _pytest.pytester.ParsedCall

getcall(name: str) → _pytest.pytester.ParsedCall

getreports(names: Union[str, Iterable[str]] = 'pytest_runtest_logreport pytest_collectreport') → List[_pytest.reports.TestReport]

matchreport(inamepart: str = '', names: Union[str, Iterable[str]] = 'pytest_runtest_logreport pytest_collectreport', when=None)

return a testreport whose dotted import path matches

getfailures(names: Union[str, Iterable[str]] = 'pytest_runtest_logreport pytest_collectreport') → List[_pytest.reports.TestReport]

getfailedcollections() → List[_pytest.reports.TestReport]

listoutcomes() → Tuple[List[_pytest.reports.TestReport], List[_pytest.reports.TestReport], List[_pytest.reports.TestReport]]

countoutcomes() → List[int]

assertoutcome(passed: int = 0, skipped: int = 0, failed: int = 0) → None

clear() → None

linecomp(request: _pytest.fixtures.FixtureRequest) → LineComp

LineMatcher_fixture(request: _pytest.fixtures.FixtureRequest) → Type[LineMatcher]

testdir(request: _pytest.fixtures.FixtureRequest, tmpdir_factory) → Testdir

for ... in _sys_snapshot()

for ... in _config_for_test()

class RunResult(ret: Union[int, _pytest.config.ExitCode], outlines: List[str], errlines: List[str], duration: float)

Bases: object

The result of running a command.

ret: Union[int, ExitCode]

the return value

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 used stdout.fnmatch_lines() method.

stderr

LineMatcher of stderr

duration

duration in seconds

parseoutcomes() → Dict[str, int]

Return a dictionary of outcomestring->num from parsing the terminal output that the test process produced.

assert_outcomes(passed: int = 0, skipped: int = 0, failed: int = 0, error: int = 0, xpassed: int = 0, xfailed: int = 0) → None

Assert that the specified outcomes appear with the respective numbers (0 means it didn’t occur) in the text output from a test run.

class CwdSnapshot

Bases: object

restore() → None

class SysModulesSnapshot(preserve: Optional[Callable[[str], bool]] = None)

Bases: object

restore() → None

class SysPathsSnapshot

Bases: object

restore() → None

_display_running(header: str, *args: str) → None

for ... in pytest_runtest_call(item: _pytest.python.Function) → Generator[None, None, None]

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)

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. Unless chdir() is used all methods will use tmpdir as their current working directory.

CLOSE_STDIN = 1

Sentinel to close stdin.

exception TimeoutExpired

Bases: Exception

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() and runpytest().

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()

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)

Create a new HookRecorder for a PluginManager.

chdir()

Cd into the temporary directory.

This is done automatically upon instantiation.

_makefile(ext: str, lines: Sequence[Union[bytes, str]], files: Mapping[str, Sequence[Union[bytes, str]]], encoding='utf-8') → py._path.local.LocalPath

makefile(ext, *args, **kwargs)

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().

makeconftest(source)

Write a contest.py file with ‘source’ as contents.

makeini(source)

Write a tox.ini file with ‘source’ as contents.

getinicfg(source)

Return the pytest section from the tox.ini config file.

makepyfile(*args, **kwargs) → py._path.local.LocalPath

Shortcut for .makefile() with a .py extension.

maketxtfile(*args, **kwargs)

Shortcut for .makefile() with a .txt 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]

Create the given set of files.

This is a more straight-forward API than the other helpers (e.g. makepyfile()).

Parameters

• files (Mapping[str,str]) –

  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)

Prepend a directory to sys.path, defaults to tmpdir.

This is undone automatically at the end of each test.

mkdir(name)

Create a new (sub)directory.

mkpydir(name)

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)

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 Failed

Bases: Exception

signals a stop as failed test run.

exception Interrupted

Bases: KeyboardInterrupt

signals an interrupted test run.

for ... in _collect(argpath, names)

_fixturemanager = None

_matchnodes(matching, names)

_node_location_to_relpath(node_path: py._path.local.LocalPath) → str

staticmethod _parse_fname_lineno(arg: str) → Tuple[str, Tuple[Optional[int], Optional[int]]]

_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)

getnode(config, arg)

Return the collection node of a file.

Parameters

• config – _pytest.config.Config instance, see parseconfig() and parseconfigure() to create the configuration

• arg – a py.path.local instance of the file

getpathnode(path)

Return the collection node of a file.

This is like getnode() but uses parseconfigure() to create the (configured) pytest Config instance.

Parameters

path (py.path.local) – the file

genitems(colitems)

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)

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)

Run a test module in process using pytest.main().

This run writes “source” into a temporary file and runs pytest.main() on it, returning a HookRecorder 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)

Run pytest.main(['--collectonly']) in-process.

Runs the pytest.main() function to run all of pytest inside the test process itself like inline_run(), but returns a tuple of the collected items and a HookRecorder instance.

inline_run(*args, plugins=(), no_reraise_ctrlc: bool = False)

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 a HookRecorder instance which gives more detailed results from that run than can be done by matching stdout/stderr from runpytest().

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

Return result of running pytest in-process, providing a similar interface to what self.runpytest() provides.

runpytest(*args_, tty=None, **kwargs) → _pytest.pytester.RunResult

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]]

parseconfig(*args_: Union[str, py._path.local.LocalPath]) → _pytest.config.Config

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)

Return a new pytest configured Config instance.

This returns a new _pytest.config.Config instance like parseconfig(), but also calls the pytest_configure hook.

getitem(source, funcname='test_func')

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)

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)

Return the module collection node for source.

This writes source to a file using makepyfile() 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]]

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]]

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

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.

_dump_lines(lines, fp)

_getpytestargs()

runpython(script) → _pytest.pytester.RunResult

Run a python script using sys.executable as interpreter.

Returns a RunResult.

runpython_c(command)

Run python -c “command”, return a RunResult.

runpytest_subprocess(*args, stdin=<CloseStdinType.CLOSE_STDIN: 1>, timeout=None) → _pytest.pytester.RunResult

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

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

Run a command using pexpect.

The pexpect child is returned.

_Testdir__take_sys_modules_snapshot()

class LineComp

Bases: object

assert_contains_lines(lines2)

Assert that lines2 are contained (linearly) in lines1.

Return a list of extralines found.

exception LineMatcherFailed(*, msg: str, log_output: List[str])

Bases: _pytest.outcomes.Failed

class LineMatcher(lines: List[str])

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().

_getlines(lines2: Union[str, Sequence[str], _pytest._code.source.Source]) → Sequence[str]

fnmatch_lines_random(lines2: Sequence[str]) → None

Check lines exist in the output in any order (using fnmatch.fnmatch()).

re_match_lines_random(lines2: Sequence[str]) → None

Check lines exist in the output in any order (using re.match()).

_match_lines_random(lines2: Sequence[str], match_func: Callable[[str, str], bool]) → None

get_lines_after(fnline: str) → Sequence[str]

Return all lines following the given line in the text.

The given line can contain glob wildcards.

_log(*args) → None

_log_text

fnmatch_lines(lines2: Sequence[str], *, consecutive: bool = False, complete: bool = False) → None

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.

Parameters

• lines2 – string patterns to match.

• consecutive (bool) – match lines consecutively?

• complete (bool) – require all lines to be matched in total

re_match_lines(lines2: Sequence[str], *, consecutive: bool = False, complete: bool = False) → None

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.

Parameters

• lines2 – string patterns to match.

• consecutive (bool) – match lines consecutively?

• complete (bool) – require all lines to be matched in total

_match_lines(lines2: Sequence[str], match_func: Callable[[str, str], bool], match_nickname: str, *, consecutive: bool = False, complete: bool = False) → None

Underlying implementation of fnmatch_lines and re_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 pattern

• match_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

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

Ensure captured lines do not match the given pattern, using re.match.

Parameters

pat (str) – the regular expression to match lines.

_no_match_line(pat: str, match_func: Callable[[str, str], bool], match_nickname: str) → None

Ensure captured lines does not have a the given pattern, using fnmatch.fnmatch

Parameters

pat (str) – the pattern to match lines

_fail(msg: str) → None

str() → str

Return the entire original text.