Worker distribution strategies in PyTest

Introduction

Worker distribution strategies help run tests faster by sharing work across multiple helpers called workers.

You have many tests and want them to finish quickly.

You want to use multiple CPU cores to run tests at the same time.

You want to balance test load evenly so no worker is idle.

You want to avoid some workers getting too many slow tests.

You want to speed up testing in continuous integration systems.

Syntax

PyTest

pytest -n <num_workers> --dist=<mode>

-n sets how many workers run tests in parallel.

--dist chooses how tests are shared: loadscope, loadfile, or loadgroup.

Examples

Runs tests with 4 workers, grouping tests by their scope (like test classes or modules).

PyTest

pytest -n 4 --dist=loadscope

Runs tests with 3 workers, distributing tests by whole test files.

PyTest

pytest -n 3 --dist=loadfile

Runs tests with 2 workers, grouping tests by custom groups you define.

PyTest

pytest -n 2 --dist=loadgroup

Sample Program

This simple test runs three checks. Using -n 2 and --dist=loadscope, pytest runs tests in parallel with 2 workers, grouping tests by their scope to balance load.

PyTest

import pytest

@pytest.mark.parametrize('x', [1, 2, 3])
def test_example(x):
    assert x > 0

# Run this command in terminal:
# pytest -n 2 --dist=loadscope

# This runs the tests in parallel using 2 workers, grouping tests by their scope.

Important Notes

Use loadscope to group tests by their class or module, which helps balance load better than just files.

loadfile sends whole test files to workers, which is simpler but may cause imbalance if files differ in size.

loadgroup requires you to define groups, useful for special cases.

Summary

Worker distribution strategies help run tests faster by sharing work across multiple workers.

Use -n to set number of workers and --dist to choose distribution mode.

Common modes are loadscope (group by scope), loadfile (group by file), and loadgroup (custom groups).

Practice

1. What does the --dist=loadscope option do in pytest-xdist worker distribution?

easy

A. It distributes tests randomly to all workers.

B. It runs all tests sequentially on a single worker.

C. It groups tests by their scope and distributes them to workers.

D. It groups tests by file size before distribution.

Solution

1. Step 1: Understand the meaning of loadscope

   The loadscope mode groups tests by their scope, such as class or module, so related tests run together.

2. Step 2: Compare with other distribution modes

   Unlike random or file-based grouping, loadscope keeps related tests together for better caching and setup reuse.

3. Final Answer:

   It groups tests by their scope and distributes them to workers. -> Option C

4. Quick Check:

   loadscope = group by scope [OK]

Hint: Loadscope groups tests by scope like class or module [OK]

Common Mistakes:

• Confusing loadscope with random distribution
• Thinking loadscope groups by file size
• Assuming loadscope runs tests sequentially

2. Which of the following is the correct pytest command to run tests with 4 workers using file-based distribution?

easy

A. pytest -n 4 --dist=loadfile

B. pytest --dist=loadfile -n four

C. pytest -n=4 --dist=loadscope

D. pytest -n 4 --dist=loadgroup

Solution

1. Step 1: Identify correct syntax for number of workers

   The correct syntax is -n 4 to specify 4 workers; spelling out 'four' is invalid.

2. Step 2: Match distribution mode to file-based

   The file-based distribution mode is loadfile, so --dist=loadfile is correct.

3. Final Answer:

   pytest -n 4 --dist=loadfile -> Option A

4. Quick Check:

   -n 4 and --dist=loadfile correct syntax [OK]

Hint: Use -n number and --dist=loadfile for file grouping [OK]

Common Mistakes:

• Using spelled-out numbers like 'four'
• Mixing distribution modes incorrectly
• Using equals sign with -n option

3. Given this pytest command: pytest -n 3 --dist=loadfile, and three test files test_a.py, test_b.py, test_c.py, how will tests be distributed?

medium

A. Tests run sequentially on a single worker.

B. All workers run tests from all files randomly.

C. Tests are grouped by class across files.

D. Each worker runs tests from one file exclusively.

Solution

1. Step 1: Understand loadfile distribution

   Loadfile mode assigns tests grouped by file to different workers, so each worker gets whole files.

2. Step 2: Match number of workers to files

   With 3 workers and 3 files, each worker will get one file's tests exclusively.

3. Final Answer:

   Each worker runs tests from one file exclusively. -> Option D

4. Quick Check:

   loadfile = group by file [OK]

Hint: Loadfile means one file per worker [OK]

Common Mistakes:

• Thinking tests are split randomly
• Confusing loadfile with loadscope
• Assuming tests run sequentially

4. You run pytest -n 2 --dist=loadscope but notice tests from the same class run on different workers. What is the likely cause?

medium

A. Tests are not properly grouped because the class scope is not detected.

B. The -n option must be set to 1 for loadscope.

C. The --dist option is ignored when using multiple workers.

D. Tests are always distributed randomly regardless of options.

Solution

1. Step 1: Understand loadscope grouping behavior

   Loadscope groups tests by scope like class or module, so tests in the same class should run together.

2. Step 2: Identify why grouping fails

   If tests from the same class run on different workers, pytest likely failed to detect the class scope properly, causing wrong grouping.

3. Final Answer:

   Tests are not properly grouped because the class scope is not detected. -> Option A

4. Quick Check:

   Undetected scope breaks loadscope grouping [OK]

Hint: Undetected scope causes loadscope to fail grouping [OK]

Common Mistakes:

• Thinking -n must be 1 for loadscope
• Believing --dist is ignored with multiple workers
• Assuming distribution is always random

5. You want to run tests in custom groups using pytest-xdist. Which command and option combination allows you to define and use custom test groups for worker distribution?

hard

A. pytest -n 3 --dist=loadgroup --tx group1 --tx group2 --tx group3

B. pytest -n 3 --dist=loadgroup

C. pytest -n 3 --dist=loadfile --group=custom

D. pytest -n 3 --dist=loadscope --group=custom

Solution

1. Step 1: Identify the distribution mode for custom groups

   The loadgroup mode is designed for custom grouping of tests for distribution.

2. Step 2: Understand correct command usage

   Using --dist=loadgroup with -n 3 enables pytest-xdist to distribute tests based on user-defined groups configured elsewhere (e.g., in pytest hooks).

3. Final Answer:

   pytest -n 3 --dist=loadgroup -> Option B

4. Quick Check:

   loadgroup enables custom test groups [OK]

Hint: Use --dist=loadgroup to enable custom test groups [OK]

Common Mistakes:

• Adding invalid --group option
• Using --tx incorrectly for grouping
• Confusing loadgroup with loadfile or loadscope