pytest-xdist for parallel execution - Build an Automation Script

Run multiple pytest tests in parallel using pytest-xdist

Preconditions (2)

Step 1: Open a terminal or command prompt

Step 2: Navigate to the directory containing test_sample.py

Step 3: Run the command: pytest -n 3

Step 4: Observe the test execution running in parallel across 3 workers

Step 5: Verify that all tests pass successfully

✅ Expected Result: All tests in test_sample.py run in parallel using 3 workers and all tests pass without errors

Automation Requirements - pytest

Assertions Needed:

Verify that all tests pass

Verify that tests run in parallel (e.g., by checking timestamps or pytest-xdist output)

Best Practices:

Use pytest markers or fixtures to ensure tests are independent

Avoid shared state between tests to prevent flaky results

Use pytest's built-in assertion rewriting for clear error messages

Automated Solution

PyTest

import subprocess
import re

def test_pytest_xdist_parallel_execution():
    # Run pytest with 3 parallel workers
    result = subprocess.run(['pytest', '-n', '3', 'test_sample.py', '--maxfail=1', '--disable-warnings', '-q'], capture_output=True, text=True)
    output = result.stdout
    # Check that pytest exited with code 0 (all tests passed)
    assert result.returncode == 0, f"Tests failed with output:\n{output}"
    # Check pytest-xdist output for parallel workers
    # The output usually contains lines like 'gw0', 'gw1', 'gw2' indicating workers
    workers_found = re.findall(r'gw\d+', output)
    assert len(set(workers_found)) >= 3, "Less than 3 parallel workers detected in output"

This test runs the pytest command with the -n 3 option to execute tests in 3 parallel workers using pytest-xdist.

We use subprocess.run to execute the command and capture the output.

First, we assert that the return code is 0, meaning all tests passed.

Then, we check the output for worker identifiers like gw0, gw1, and gw2 which pytest-xdist prints to show parallel execution.

This confirms that tests ran in parallel.

Using --maxfail=1 and --disable-warnings keeps output clean and stops early on failure.

Common Mistakes - 3 Pitfalls

Running tests with pytest-xdist without ensuring tests are independent

{'mistake': 'Not capturing or checking the pytest output for parallel execution confirmation', 'why_bad': 'You might think tests ran in parallel but they actually ran sequentially', 'correct_approach': "Parse pytest output for worker identifiers like 'gw0', 'gw1' to confirm parallelism"}

{'mistake': "Using hardcoded sleep or wait instead of relying on pytest-xdist's parallelism", 'why_bad': 'Sleep does not guarantee parallel execution and slows tests unnecessarily', 'correct_approach': "Use pytest-xdist's -n option to run tests in parallel properly"}

Bonus Challenge

Now add a test that runs the same test file with different numbers of workers (1, 2, 4) and verifies all pass

Show Hint

Practice

1. What is the main purpose of using pytest-xdist in test execution?

easy

A. To run tests in parallel and reduce total test time

B. To generate detailed HTML reports

C. To automatically fix failing tests

D. To run tests only on a single CPU core

Solution

1. Step 1: Understand pytest-xdist functionality

   pytest-xdist allows running tests simultaneously on multiple CPU cores.

2. Step 2: Identify the benefit of parallel execution

   Running tests in parallel reduces the total time needed to complete all tests.

3. Final Answer:

   To run tests in parallel and reduce total test time -> Option A

4. Quick Check:

   pytest-xdist = parallel test execution [OK]

Hint: Remember: xdist means 'distributed' tests run together [OK]

Common Mistakes:

• Confusing xdist with report generation tools
• Thinking xdist fixes test code automatically
• Assuming xdist runs tests sequentially

2. Which command correctly runs tests in parallel using 4 workers with pytest-xdist?

easy

A. pytest -n 4

B. pytest --workers=4

C. pytest -p 4

D. pytest --parallel 4

Solution

1. Step 1: Recall pytest-xdist syntax for parallelism

   The correct flag to specify number of parallel workers is -n.

2. Step 2: Match the correct command

   pytest -n 4 runs tests with 4 parallel workers.

3. Final Answer:

   pytest -n 4 -> Option A

4. Quick Check:

   -n sets workers = C [OK]

Hint: Use '-n' to set number of parallel workers [OK]

Common Mistakes:

• Using incorrect flags like --workers or --parallel
• Confusing -p (plugin) with -n
• Omitting the number after -n

3. Given this pytest command: pytest -n 3 test_sample.py, what happens during test execution?

medium

A. Tests run in parallel but limited to 1 CPU core

B. Tests in test_sample.py run sequentially on one CPU core

C. Only 3 tests from test_sample.py run sequentially

D. Tests in test_sample.py run in parallel using 3 CPU cores

Solution

1. Step 1: Analyze the command options

   The -n 3 option tells pytest-xdist to use 3 workers for parallel execution.

2. Step 2: Understand effect on test_sample.py

   All tests in test_sample.py are distributed across 3 CPU cores and run simultaneously.

3. Final Answer:

   Tests in test_sample.py run in parallel using 3 CPU cores -> Option D

4. Quick Check:

   -n 3 means 3 parallel workers = A [OK]

Hint: -n sets parallel workers, all tests split among them [OK]

Common Mistakes:

• Thinking only 3 tests run instead of all tests
• Assuming tests run sequentially despite -n
• Confusing number of workers with number of tests

4. You run pytest -n 2 but get an error: ERROR: unknown option: -n. What is the likely cause?

medium

A. You used the wrong flag; it should be --num

B. pytest-xdist plugin is not installed

C. You need to run pytest with sudo

D. The test files are missing

Solution

1. Step 1: Understand the error message

   The error says -n is unknown, meaning pytest does not recognize the option.

2. Step 2: Identify cause related to pytest-xdist

   The -n option is provided by pytest-xdist plugin. If it's not installed, pytest won't recognize it.

3. Final Answer:

   pytest-xdist plugin is not installed -> Option B

4. Quick Check:

   Unknown -n means missing xdist plugin = B [OK]

Hint: Install pytest-xdist to enable -n option [OK]

Common Mistakes:

• Assuming -n flag is built-in pytest option
• Trying to run with sudo unnecessarily
• Ignoring plugin installation step

5. You want to speed up a large test suite using pytest-xdist but notice flaky failures when running with pytest -n auto. What is a good approach to fix this?

hard

A. Disable pytest-xdist and run tests sequentially

B. Increase the number of workers beyond CPU cores

C. Add @pytest.mark.serial to tests that share state to run them sequentially

D. Use pytest -n 1 to force single worker

Solution

1. Step 1: Understand cause of flaky failures

   Tests sharing state or resources can fail when run in parallel due to conflicts.

2. Step 2: Use markers to run conflicting tests sequentially

   Marking such tests with @pytest.mark.serial (or similar) ensures they run one at a time, avoiding conflicts.

3. Step 3: Keep parallelism for other tests

   This approach balances speed and stability by running safe tests in parallel and conflicting ones sequentially.

4. Final Answer:

   Add @pytest.mark.serial to tests that share state to run them sequentially -> Option C

5. Quick Check:

   Mark shared-state tests serial to fix flakes = A [OK]

Hint: Mark shared tests serial to avoid parallel conflicts [OK]

Common Mistakes:

• Blindly increasing workers causing more flakes
• Disabling parallelism losing speed benefits
• Using -n 1 which is just sequential run