pytest-order

pytest-order is a pytest plugin that lets you mark individual tests with an explicit execution order (@pytest.mark.order(1), @pytest.mark.order("last"), relative markers like before/after) instead of relying on pytest’s default alphabetical-within-file collection order. It’s a maintained fork/successor of the older pytest-ordering plugin, adding features like sorting across files/modules, dependency-style relative ordering, and marker-based grouping.

While most test suites should avoid depending on execution order, pytest-order is commonly reached for in integration or end-to-end test suites where setup/teardown sequencing genuinely matters (e.g., a test that creates a resource must run before a test that queries it) and restructuring into fixtures isn’t practical.

What You Get

• @pytest.mark.order(N) to pin a test to an absolute position (including negative indices like -1 for “run last”)
• Relative ordering markers — before, after, sparse, group — to sequence tests relative to each other without hardcoding absolute positions
• Cross-module and cross-class ordering, not just within a single test file
• Configuration options (--indulgent-ordering) to gracefully mix ordered and unordered tests instead of failing on conflicts
• Compatibility layer for projects migrating from the unmaintained pytest-ordering plugin

Common Use Cases

• Integration test suites where a resource-creation test must run before tests that depend on that resource existing
• End-to-end test suites simulating a multi-step user workflow (signup, then login, then perform action) across separate test functions
• Smoke tests that need to run first or last in a CI pipeline regardless of pytest’s default collection order
• Migrating an existing suite off the unmaintained pytest-ordering plugin with minimal marker syntax changes

Under The Hood

Architecture - plugin.py (204 lines) registers pytest hooks and marker configuration; the actual ordering logic is isolated in sorter.py (560 lines), which resolves absolute, relative, and group-based order markers into a single sort order pytest applies to the collected item list, with item.py (357 lines) modeling each test’s order metadata.

Tech Stack - Pure Python, built entirely on pytest’s public plugin hook API (pytest_collection_modifyitems, pytest_addoption) with no runtime dependencies beyond pytest itself.

Code Quality - A dedicated tests/ directory alongside example/ projects covering introduction, configuration, and usage scenarios, plus perf_tests/ specifically for performance regression testing of the sorting algorithm — a signal that ordering large test suites efficiently was a deliberate design concern.

API Design - The marker-based API (@pytest.mark.order(...)) fits naturally into pytest’s existing marker idiom, so adopting it requires no changes to test structure or fixtures — just adding decorators, which keeps the learning curve low for teams already familiar with pytest.