PYTEST(1)

🌸 NAME 🌸

pytest — pytest usage, bestie 💖

okay so ALSO, before anything: there's a whole Complete pytest command-line flags reference waiting for you if you wanna go deeper. iykyk.

So like. In general, you invoke pytest with the command pytest (other ways to call it are further down, keep scrolling 🫶). That runs every test in every file whose name follows the form test_*.py or *_test.py in the current directory and all its subdirectories. More generally, pytest follows the standard test discovery rules. no cap.

---

🔍 SPECIFYING WHICH TESTS TO RUN 🔍

pytest has several ways to run and pick tests, either from the command line or from a file (reading args from a file is further down, hold on bestie).

🍓 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 runs tests whose names match the given string expression (case-insensitive), and that expression 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 the expression when you're 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 info, go peep the marks docs.

🍓 Run tests from packages

pytest --pyargs pkg.testing

This imports pkg.testing and uses its filesystem location to find and run tests from. iconic tbh.

🍓 Read arguments from file

<span class="mint">Added in version 8.2.</span>

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. chef's kiss ✨

---

🆘 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

literally just ask, babe 😌

---

⏱️ PROFILING TEST EXECUTION DURATION ⏱️

<span class="mint">Changed in version 6.0.</span>

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 (smaller than 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 on 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

bye bestie 👋💀

---

🌈 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. subtle but so real.

💜 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. fr fr, don't do it 🙈

---

👑 Author 👑

holger krekel at merlinux eu

📜 Copyright 📜

2015, holger krekel and pytest-dev team

---

okay that's the whole thing bestie, you're so welcome 🫶 this was version 9.1.1, dated Jun 20, 2026 — go forth and write tests that slay 💅✨🧚‍♀️🎀