Introduction

pytest-order is a pytest plugin which allows you to customize the order in which your tests are run. It provides the marker order, that has attributes that define when your tests should run in relation to each other. These attributes can be absolute (i.e. first, or second-to-last) or relative (i.e. run this test before this other test).

Note

It is generally considered bad practice to write tests that depend on each other. However, in reality this may still be needed due to performance issues, legacy code or other constraints. Still, before using this plugin, you should check if you can refactor your tests to remove the dependencies between tests.

Relationship with pytest-ordering

pytest-order is a fork of pytest-ordering, which is not maintained anymore. The idea and most of the code has been created by Frank Tobia, the author of that plugin, and contributors to the project.

However, pytest-order is not compatible with pytest-ordering due to the changed marker name (order instead of run) and the removal of all other special markers for consistence (as has been discussed in this issue). This also avoids clashes between the plugins if they are both installed.

Here are examples for which markers correspond to markers in pytest-ordering:

• pytest.mark.order1, pytest.mark.run(order=1) => pytest.mark.order(1)

• pytest.mark.first => pytest.mark.order("first")

Additionally, pytest-order provides a number of features (relative ordering, all configuration options) that are not available in pytest-ordering.

Supported Python and pytest versions

pytest-order supports python 3.7 - 3.12 and pypy3, and is compatible with pytest 5.0.0 or newer (older versions may also work, but are not tested) for Python versions up to 3.9, and with pytest >= 6.2.4 for Python versions >= 3.10.

All supported combinations of Python and pytest versions are tested in the CI builds. The plugin shall work under Linux, MacOs and Windows.

Installation

The latest released version can be installed from PyPi:

pip install pytest-order

The latest main branch can be installed from the GitHub sources:

pip install git+https://github.com/pytest-dev/pytest-order

Examples

Most examples shown in this documentation can be also found in the repository under example as working test files.

Quickstart

Ordinarily pytest will run tests in the order that they appear in a module. For example, for the following tests:

def test_foo():
    assert True


def test_bar():
    assert True

the output is something like:

$ pytest test_foo.py -vv
============================= test session starts ==============================
platform darwin -- Python 3.7.1, pytest-5.4.3, py-1.8.1, pluggy-0.13.1 -- env/bin/python
collected 2 items

test_foo.py:2: test_foo PASSED
test_foo.py:6: test_bar PASSED

=========================== 2 passed in 0.01 seconds ===========================

With pytest-order, you can change the default ordering as follows:

import pytest


@pytest.mark.order(2)
def test_foo():
    assert True


@pytest.mark.order(1)
def test_bar():
    assert True

This will generate the output:

$ pytest test_foo.py -vv
============================= test session starts ==============================
platform darwin -- Python 3.7.1, pytest-5.4.3, py-1.8.1, pluggy-0.13.1 -- env/bin/python
plugins: order
collected 2 items

test_foo.py:7: test_bar PASSED
test_foo.py:3: test_foo PASSED

=========================== 2 passed in 0.01 seconds ===========================