0
# Plugin Configuration
1

2
Core plugin setup, command-line options, and pytest integration for pytest-xdist. This module handles all the configuration and initialization needed to enable distributed testing.
3

4
## Capabilities
5

6
### Command Line Options
7

8
pytest-xdist adds numerous command-line options to control distributed testing behavior.
9

10
```python { .api }
11
def pytest_addoption(parser: pytest.Parser) -> None:
12
    """Add xdist-specific command line options to pytest."""
13
```
14

15
**Key Options:**
16

17
- `-n/--numprocesses`: Number of processes ('auto', 'logical', or integer)
18
- `--maxprocesses`: Limit maximum workers with auto detection  
19
- `--max-worker-restart`: Maximum worker restart count
20
- `--dist`: Distribution mode (each, load, loadscope, loadfile, loadgroup, worksteal, no)
21
- `--loadscope-reorder/--no-loadscope-reorder`: Control test reordering in loadscope mode
22
- `--tx`: Test execution environments
23
- `--px`: Proxy gateways  
24
- `-d/--distload`: Shortcut for '--dist=load'
25
- `--rsyncdir`: Directories for rsyncing (deprecated)
26
- `--rsyncignore`: Ignore patterns for rsyncing (deprecated)
27
- `--testrunuid`: Shared identifier across workers
28
- `--maxschedchunk`: Maximum tests scheduled per step
29

30
### Configuration Processing
31

32
Handles main command-line processing and configuration validation.
33

34
```python { .api }
35
def pytest_cmdline_main(config: pytest.Config) -> None:
36
    """Main command line processing for xdist options."""
37
```
38

39
**Functionality:**
40
- Converts `-d/--distload` to `--dist=load`
41
- Handles `--numprocesses` with 'auto' and 'logical' values
42
- Disables distribution when `--pdb` is used
43
- Validates option combinations
44
- Sets up worker count based on CPU detection
45

46
### Plugin Configuration
47

48
Configures the xdist plugin and sets up distributed session if needed.
49

50
```python { .api }
51
def pytest_configure(config: pytest.Config) -> None:
52
    """Configure xdist plugin and create distributed session if needed."""
53
```
54

55
**Functionality:**
56
- Adds xdist_group marker configuration
57
- Skips configuration for collection-only runs
58
- Creates DSession for distributed modes
59
- Registers distributed session with plugin manager
60
- Issues deprecation warnings for deprecated features
61

62
### Hook Registration
63

64
Registers xdist-specific hooks with pytest's plugin manager.
65

66
```python { .api }
67
def pytest_addhooks(pluginmanager: pytest.PytestPluginManager) -> None:
68
    """Add xdist hook specifications to pytest."""
69
```
70

71
### Auto Worker Detection
72

73
Automatically detects the optimal number of workers based on system resources.
74

75
```python { .api }
76
def pytest_xdist_auto_num_workers(config: pytest.Config) -> int:
77
    """
78
    Hook implementation for determining auto worker count.
79
    
80
    Returns:
81
        int: Number of workers to spawn for 'auto' or 'logical' modes
82
    """
83
```
84

85
**Detection Logic:**
86
1. Check `PYTEST_XDIST_AUTO_NUM_WORKERS` environment variable
87
2. Use psutil if available (respects logical vs physical CPU setting)
88
3. Fall back to `os.sched_getaffinity()` on Unix systems
89
4. Use `os.cpu_count()` or `multiprocessing.cpu_count()` as final fallback
90
5. Special handling for Travis CI environment
91
6. Returns 1 if detection fails
92

93
### Utility Functions
94

95
Helper functions for parsing and validating configuration options.
96

97
```python { .api }
98
def parse_numprocesses(s: str) -> int | Literal["auto", "logical"]:
99
    """
100
    Parse numprocesses argument value.
101
    
102
    Args:
103
        s: String value ('auto', 'logical', or numeric)
104
        
105
    Returns:
106
        Parsed value as int or literal string
107
    """
108

109
def _is_distribution_mode(config: pytest.Config) -> bool:
110
    """
111
    Check if distribution mode is enabled.
112
    
113
    Args:
114
        config: pytest configuration object
115
        
116
    Returns:
117
        bool: True if distribution is enabled
118
    """
119
```
120

121
## Usage Examples
122

123
### Basic Configuration
124

125
```python
126
# In conftest.py - check if xdist is being used
127
def pytest_configure(config):
128
    if hasattr(config, 'workerinput'):
129
        # Running as xdist worker
130
        setup_worker_specific_config()
131
    else:
132
        # Running as controller or single process
133
        setup_controller_config()
134
```
135

136
### Custom Worker Count Hook
137

138
```python
139
# In conftest.py - customize auto worker detection
140
def pytest_xdist_auto_num_workers(config):
141
    # Custom logic for determining worker count
142
    if config.getoption("--slow-tests"):
143
        return 2  # Use fewer workers for slow tests
144
    return None  # Use default detection
145
```
146

147
### Environment Variable Usage
148

149
```bash
150
# Set custom worker count via environment
151
export PYTEST_XDIST_AUTO_NUM_WORKERS=8
152
pytest -n auto
153

154
# Use logical CPU count (includes hyperthreading)
155
pytest -n logical
156

157
# Use physical CPU count only
158
pytest -n auto
159
```