How to Split pytest by Timings With pytest-split

pytest-split partitions tests by recorded runtime, not file count, so every group finishes at about the same time.

Record durations once with --store-durations, commit the file, then split with --splits N --group i so slow tests spread evenly.

Steps

• Run pytest --store-durations to write .test_durations.
• Commit that file so CI can read historical timings.
• Split each job with --splits N --group ${{ matrix.group }} --durations-path .test_durations.

Workflow

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        group: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
      - run: pip install pytest pytest-split
      - run: pytest --splits 3 --group ${{ matrix.group }} --durations-path .test_durations

Gotchas

• A stale durations file skews balance; refresh it when the suite changes a lot.
• New tests with no recorded timing default to an estimate and may land unevenly.

Related guides