pytest

https://docs.pytest.org/en/stable/
Admin
pytest is a Python testing framework that simplifies writing small, readable tests and scales for...
Tokens:660,151
Snippets:5,073
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Per-session Database funcarg using cached_setup

Source: https://docs.pytest.org/en/stable/funcarg_compare.html

Example of implementing a per-session Database object using the old pytest_funcarg__ mechanism with request.cached_setup(). Shows setup and teardown callbacks.

```python
# content of conftest.py
class Database:
    def __init__(self):
        print("database instance created")

    def destroy(self):
        print("database instance destroyed")


def pytest_funcarg__db(request):
    return request.cached_setup(
        setup=DataBase, teardown=lambda db: db.destroy, scope="session"
    )

```

--------------------------------

### Configuration file search order for the example

Source: https://docs.pytest.org/en/stable/reference/customize.html

Lists the configuration files that pytest checks in order, starting from the common ancestor directory and moving upwards. Comments indicate the required content for pyproject.toml, tox.ini, and setup.cfg to match.

```text
# first look for path/pytest.toml
path/pytest.toml
path/pytest.ini
path/pyproject.toml  # must contain a [tool.pytest] table to match
path/tox.ini         # must contain [pytest] section to match
path/setup.cfg       # must contain [tool:pytest] section to match
pytest.toml
pytest.ini
... # all the way up to the root

# now look for setup.py
path/setup.py
setup.py
... # all the way up to the root

```

--------------------------------

### Install pre-commit and its hook

Source: https://docs.pytest.org/en/stable/contributing.html

Install pre-commit and set up its hook on the repository. After this, pre-commit will run automatically on each commit.

```bash
$ pip install --user pre-commit
$ pre-commit install

```

--------------------------------

### check_myapp.py: Example test file

Source: https://docs.pytest.org/en/stable/example/pythoncollection.html

Example test file that matches the custom naming conventions from Example 1. It defines a class CheckMyApp with methods simple_check and complex_check.

```python
# content of check_myapp.py
class CheckMyApp:
    def simple_check(self):
        pass

    def complex_check(self):
        pass

```

--------------------------------

### Install tox

Source: https://docs.pytest.org/en/stable/contributing.html

Install tox, which is used to run all tests and automatically sets up virtualenvs.

```bash
$ pip install tox

```

--------------------------------

### setup.cfg configuration example

Source: https://docs.pytest.org/en/stable/reference/customize.html

Example of a setup.cfg file with a [tool:pytest] section to hold pytest configuration. Usage is not recommended for complex cases due to parser differences.

```ini
# setup.cfg
[tool:pytest]
minversion = 6.0
addopts = -ra -q
testpaths =
    tests
    integration

```

--------------------------------

### Install pytest 3.2.5 with pip

Source: https://docs.pytest.org/en/stable/announce/release-3.2.5.html

Use this command to install pytest version 3.2.5. The release announcement does not specify additional setup steps or output.

```bash
pip install pytest==3.2.5
```

--------------------------------

### Example plugin with hello fixture and --name option

Source: https://docs.pytest.org/en/stable/how-to/writing_plugins.html

Example plugin that provides a fixture 'hello' which yields a function. The function returns 'Hello World!' if no value is supplied, or 'Hello {value}!' if a string value is supplied. It also adds a --name command line option.

```python
import pytest


def pytest_addoption(parser):
    group = parser.getgroup("helloworld")
    group.addoption(
        "--name",
        action="store",
        dest="name",
        default="World",
        help='Default "name" for hello().',
    )


@pytest.fixture
def hello(request):
    name = request.config.getoption("name")

    def _hello(name=None):
        if not name:
            name = request.config.getoption("name")
        return f"Hello {name}!"

    return _hello

```

--------------------------------

### Example of imported test class collection

Source: https://docs.pytest.org/en/stable/reference/reference.html

Example showing a production class imported into a test module. With default options, pytest collects the class Testament from tests/test_testament.py because it starts with Test.

```python
# contents of src/domain.py
class Testament: ...


# contents of tests/test_testament.py
from domain import Testament


def test_testament(): ...
```

--------------------------------

### Dummy setup.py that raises exception if imported

Source: https://docs.pytest.org/en/stable/example/pythoncollection.html

Dummy setup.py file that will raise an exception if imported, used to demonstrate ignoring files during collection.

```python
# content of setup.py
0 / 0  # will raise exception if imported

```

--------------------------------

### Nose-style setup/teardown methods

Source: https://docs.pytest.org/en/stable/deprecations.html

Example of nose-style setup and teardown methods that are not pytest native and are deprecated.

```python
class Test:
    def setup(self):
        self.resource = make_resource()

    def teardown(self):
        self.resource.close()

    def test_foo(self): ...

    def test_bar(self): ...

```

--------------------------------

### Example test directory structure

Source: https://docs.pytest.org/en/stable/example/pythoncollection.html

Shows a sample test directory layout with three subdirectories (example, foobar, hello/world), each containing test files. This structure is used to illustrate the effect of the --ignore option.

```text
tests/
|-- example
|   |-- test_example_01.py
|   |-- test_example_02.py
|   '-- test_example_03.py
|-- foobar
|   |-- test_foobar_01.py
|   |-- test_foobar_02.py
|   '-- test_foobar_03.py
'-- hello
    '-- world
        |-- test_world_01.py
        |-- test_world_02.py
        '-- test_world_03.py

```

--------------------------------

### Node.addfinalizer

Source: https://docs.pytest.org/en/stable/reference/reference.html

Register a function to be called without arguments when this node is finalized. This method can only be called when this node is active in a setup chain, for example during self.setup().

```APIDOC
## Node.addfinalizer

### Description
Register a function to be called without arguments when this node is finalized. This method can only be called when this node is active in a setup chain, for example during self.setup().

### Method
addfinalizer

### Parameters
- **fin** - Required - The function to be called.

```

--------------------------------

### copy_example(_name=None_)

Source: https://docs.pytest.org/en/stable/reference/reference.html

Copies a file from the project's directory into the test directory.

```APIDOC
## copy_example(_name=None_)

### Description
Copy file from project's directory into the testdir.

### Method
copy_example

### Parameters
#### Parameters
- **name** (str | None) - Optional - The name of the file to copy.

### Returns
Path to the copied directory (inside `self.path`).

### Return Type
pathlib.Path
```

--------------------------------

### Access logs from other stages with caplog.get_records(when)

Source: https://docs.pytest.org/en/stable/how-to/logging.html

Shows how to use caplog.get_records(when) to inspect logs from the 'setup' and 'call' stages during teardown. The example fails the test if any warning messages are encountered.

```python
@pytest.fixture
def window(caplog):
    window = create_window()
    yield window
    for when in ("setup", "call"):
        messages = [
            x.message for x in caplog.get_records(when) if x.levelno == logging.WARNING
        ]
        if messages:
            pytest.fail(f"warning messages encountered during testing: {messages}")

```

--------------------------------

### Use module globals in skipif expression

Source: https://docs.pytest.org/en/stable/announce/release-2.0.2.html

Example showing how to access module globals in a skipif expression. The test is skipped if the module's version string does not start with '1'.

```python
import pytest
import mymodule
@pytest.mark.skipif("mymodule.__version__[0] == "1")
def test_function():
    pass
```

--------------------------------

### Creating binary files with pathlib.Path.write_bytes

Source: https://docs.pytest.org/en/stable/_modules/_pytest/pytester.html

Shows how to create binary files directly using pathlib.Path.write_bytes instead of pytester.makefile.

```python
filename = pytester.path.joinpath("foo.bin")
filename.write_bytes(b"...")
```

--------------------------------

### Using module globals in pytest.mark.skipif expression

Source: https://docs.pytest.org/en/stable/changelog.html

Example of a skipif expression that accesses a module global to conditionally skip a test. The test is skipped if the module's version string does not start with '1'.

```python
import pytest
import mymodule
@pytest.mark.skipif("mymodule.__version__[0] == "1")
def test_function():
    pass

```

--------------------------------

### Command line equivalent of addopts example

Source: https://docs.pytest.org/en/stable/reference/reference.html

Issuing pytest test_hello.py with the addopts configuration actually means running this command.

```bash
pytest --maxfail=2 -rf test_hello.py
```

--------------------------------

### Problematic parametrize with generator (deprecated)

Source: https://docs.pytest.org/en/stable/deprecations.html

Using a generator as argvalues in @pytest.mark.parametrize is deprecated because it gets exhausted after first iteration, causing tests to be skipped. This example shows a class-level parametrize where test_2 is skipped.

```python
import pytest


def data_generator():
    yield 1
    yield 2


@pytest.mark.parametrize("n", data_generator())
class Test:
    def test_1(self, n):
        pass

    # test_2 will be skipped because data_generator() is exhausted.
    def test_2(self, n):
        pass

```

--------------------------------

### copy_example

Source: https://docs.pytest.org/en/stable/_modules/_pytest/pytester.html

Copies a file or directory from the project's example directory into the test directory.

```APIDOC
## copy_example

### Description
Copy file from project's directory into the testdir.

### Method
copy_example

### Signature
copy_example(self, name: str | None = None) -> Path

### Parameters
- **name** (str | None) - Optional - The name of the file to copy. If None, uses the test function name to locate the example.

### Returns
- **Path** - Path to the copied directory (inside ``self.path``).

### Return Type
pathlib.Path

### Raises
- **ValueError** - If pytester_example_dir is unset.
- **LookupError** - If the example is not found as a file or directory.
```

--------------------------------

### Build documentation locally with tox -e docs

Source: https://docs.pytest.org/en/stable/contributing.html

Run this command to build the documentation locally. The built documentation will be available in doc/en/_build/html, where 'en' refers to the documentation language.

```bash
$ tox -e docs

```

--------------------------------

### PytestPluginManager.load_setuptools_entrypoints

Source: https://docs.pytest.org/en/stable/reference/reference.html

Loads modules from querying the specified setuptools group.

```APIDOC
## load_setuptools_entrypoints(_group_, _name=None_)

### Description
Loads modules from querying the specified setuptools group.

### Method
load_setuptools_entrypoints

### Parameters
- **group** (str) - Required - Entry point group to load plugins.
- **name** (str | None) - Optional - If given, loads only plugins with the given name.

### Returns
- int: The number of plugins loaded by this call.

```

--------------------------------

### pytest hook wrapper example

Source: https://docs.pytest.org/en/stable/how-to/writing_hook_functions.html

Defines a hook wrapper for pytest_pyfunc_call that executes code before and after the next hook implementation. It yields to get the result, processes it, and returns a new value. The wrapper must return a result or raise an exception.

```python
import pytest


@pytest.hookimpl(wrapper=True)
def pytest_pyfunc_call(pyfuncitem):
    do_something_before_next_hook_executes()

    # If the outcome is an exception, will raise the exception.
    res = yield

    new_res = post_process_result(res)

    # Override the return value to the plugin system.
    return new_res

```

--------------------------------

### Example directory structure for --import-mode=append

Source: https://docs.pytest.org/en/stable/explanation/pythonpath.html

This directory structure illustrates the scenario where the append import mode is beneficial. It shows a testing package with a test file and the package under test, allowing tests to run against the installed version of the package when using --import-mode=append.

```text
testing/__init__.py
testing/test_pkg_under_test.py
pkg_under_test/

```

--------------------------------

### Create virtual environment and install dev dependencies

Source: https://docs.pytest.org/en/stable/contributing.html

Create a virtual environment and install pytest in editable mode with the dev extra. Use the appropriate activation command for your OS.

```bash
$ python3 -m venv .venv
$ source .venv/bin/activate  # Linux
$ .venv/Scripts/activate.bat  # Windows
$ pip install -e ".[dev]"

```

--------------------------------

### Install pytest with pip or easy_install

Source: https://docs.pytest.org/en/stable/announce/release-2.0.0.html

Install pytest 2.0.0 using either pip or easy_install. Both commands install the latest version of pytest.

```bash
pip install -U pytest
easy_install -U pytest

```

--------------------------------

### Using @with_setup from nose.tools

Source: https://docs.pytest.org/en/stable/deprecations.html

Example of code using @with_setup that needs to be ported to a supported pytest style.

```python
from nose.tools import with_setup


def setup_some_resource(): ...


def teardown_some_resource(): ...


@with_setup(setup_some_resource, teardown_some_resource)
def test_foo(): ...

```

--------------------------------

### Node.warn example usage

Source: https://docs.pytest.org/en/stable/_modules/_pytest/nodes.html

Example calls to node.warn with PytestWarning and UserWarning.

```python
node.warn(PytestWarning("some message"))
node.warn(UserWarning("some message"))
```

--------------------------------

### pytest_fixture_setup(fixturedef, request)

Source: https://docs.pytest.org/en/stable/_modules/_pytest/hookspec.html

Perform fixture setup execution. Stops at first non-None result.

```APIDOC
## pytest_fixture_setup(fixturedef, request)

### Description
Perform fixture setup execution. Stops at first non-None result, see :ref:`firstresult`.

### Method
Hook function

### Parameters
- **fixturedef** (FixtureDef[Any]) - Required - The fixture definition object.
- **request** (SubRequest) - Required - The fixture request object.

### Returns
- **object | None** - The return value of the call to the fixture function. If the fixture function returns None, other implementations of this hook function will continue to be called.

### Usage
Any conftest file can implement this hook. For a given fixture, only conftest files in the fixture scope's directory and its parent directories are consulted.
```

--------------------------------

### Install argcomplete

Source: https://docs.pytest.org/en/stable/how-to/bash-completion.html

Install argcomplete with pip. Requires sudo and version 0.5.7 or higher.

```bash
sudo pip install 'argcomplete>=0.5.7'

```
Tokens:
Raw