---
name: "pytest"
section: "1"
platform: "linux"
package: "python3-pytest"
version: "8.3.5-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pytest"
---

# pytest(1)

pytest usage SEE ALSO: In general, pytest is invoked with the command pytest (see below for other ways to invoke pytest). This will execute all tests in all files whose names follow the form test\_\*.py or \\\*\_test.py in the current directory and its subdirectories. More generally, pytest follows standard test discovery rules.

## NAME

pytest - pytest usage

**SEE ALSO:**

*Complete pytest command-line flag reference*

In general, pytest is invoked with the command **pytest** (see below for *other ways to invoke pytest*). This will execute all tests in all files whose names follow the form **test\_\*.py** or **\\\*\_test.py** in the current directory and its subdirectories. More generally, pytest follows *standard test discovery rules*.

## SPECIFYING WHICH TESTS TO RUN

Pytest supports several ways to run and select tests from the command-line or from a file (see below for *reading arguments from file*).

**Run tests in a module**

```
pytest test_mod.py
```

**Run tests in a directory**

```
pytest testing/
```

**Run tests by keyword expressions**

```
pytest -k 'MyClass and not method'
```

This will run tests which contain names that match the given *string expression* (case-insensitive), which can include Python operators that use filenames, class names and function names as variables. The example above will run **TestMyClass.test\_something**  but not **TestMyClass.test\_method\_simple**. Use **""** instead of **''** in expression when running this on Windows

**Run tests by collection arguments**

Pass the module filename relative to the working directory, followed by specifiers like the class name and function name separated by **::** characters, and parameters from parameterization enclosed in **\[\]**.

To run a specific test within a module:

```
pytest tests/test_mod.py::test_func
```

To run all tests in a class:

```
pytest tests/test_mod.py::TestClass
```

Specifying a specific test method:

```
pytest tests/test_mod.py::TestClass::test_method
```

Specifying a specific parametrization of a test:

```
pytest tests/test_mod.py::test_func[x1,y2]
```

**Run tests by marker expressions**

To run all tests which are decorated with the **@pytest.mark.slow** decorator:

```
pytest -m slow
```

To run all tests which are decorated with the annotated **@pytest.mark.slow(phase=1)** decorator, with the **phase** keyword argument set to **1**:

```
pytest -m "slow(phase=1)"
```

For more information see *marks*.

**Run tests from packages**

```
pytest --pyargs pkg.testing
```

This will import **pkg.testing** and use its filesystem location to find and run tests from.

**Read arguments from file**

Added in version 8.2.

All of the above can be read from a file using the **@** prefix:

```
pytest @tests_to_run.txt
```

where **tests\_to\_run.txt** contains an entry per line, e.g.:

```
tests/test_file.py
tests/test_mod.py::test_func[x1,y2]
tests/test_mod.py::TestClass
-m slow
```

This file can also be generated using **pytest --collect-only -q** and modified as needed.

## GETTING HELP ON VERSION, OPTION NAMES, ENVIRONMENT VARIABLES

```
pytest --version   # shows where pytest was imported from
pytest --fixtures  # show available builtin function arguments
pytest -h | --help # show help on command line and config file options
```

## PROFILING TEST EXECUTION DURATION

Changed in version 6.0.

To get a list of the slowest 10 test durations over 1.0s long:

```
pytest --durations=10 --durations-min=1.0
```

By default, pytest will not show test durations that are too small (\<0.005s) unless **-vv** is passed on the command-line.

## MANAGING LOADING OF PLUGINS

### Early loading plugins

You can early-load plugins (internal and external) explicitly in the command-line with the **-p** option:

```
pytest -p mypluginmodule
```

The option receives a **name** parameter, which can be:

- •

  A full module dotted name, for example **myproject.plugins**. This dotted name must be importable.

- •

  The entry-point name of a plugin. This is the name passed to **importlib** when the plugin is registered. For example to early-load the *pytest-cov* plugin you can use:

  ```
  pytest -p pytest_cov
  ```

### Disabling plugins

To disable loading specific plugins at invocation time, use the **-p** option together with the prefix **no:**.

Example: to disable loading the plugin **doctest**, which is responsible for executing doctest tests from text files, invoke pytest like this:

```
pytest -p no:doctest
```

## OTHER WAYS OF CALLING PYTEST

### Calling pytest through python -m pytest

You can invoke testing through the Python interpreter from the command line:

```
python -m pytest [...]
```

This is almost equivalent to invoking the command line script **pytest \[...\]** directly, except that calling via **python** will also add the current directory to **sys.path**.

### Calling pytest from Python code

You can invoke **pytest** from Python code directly:

```
retcode = pytest.main()
```

this acts as if you would call "pytest" from the command line. It will not raise *SystemExit* but return the *exit code* instead. If you don't pass it any arguments, **main** reads the arguments from the command line arguments of the process (*sys.argv*), which may be undesirable. You can pass in options and arguments explicitly:

```
retcode = pytest.main(["-x", "mytestdir"])
```

You can specify additional plugins to **pytest.main**:

```
# content of myinvoke.py
import sys
import pytest
class MyPlugin:
    def pytest_sessionfinish(self):
        print("*** test run reporting finishing")
if __name__ == "__main__":
    sys.exit(pytest.main(["-qq"], plugins=[MyPlugin()]))
```

Running it will show that **MyPlugin** was added and its hook was invoked:

```
$ python myinvoke.py
*** test run reporting finishing
```

**NOTE:**

Calling **pytest.main()** will result in importing your tests and any modules that they import. Due to the caching mechanism of python's import system, making subsequent calls to **pytest.main()** from the same process will not reflect changes to those files between the calls. For this reason, making multiple calls to **pytest.main()** from the same process (in order to re-run tests, for example) is not recommended.

## AUTHOR

holger krekel at merlinux eu

## COPYRIGHT

2015, holger krekel and pytest-dev team