0
# Configuration
1
2
Green's configuration system provides hierarchical configuration merging from multiple sources including command-line arguments, configuration files, and environment variables with well-defined precedence rules.
3
4
## Capabilities
5
6
### Argument Parsing
7
8
Parses command-line arguments and creates a configuration namespace with all available Green options.
9
10
```python { .api }
11
def parseArguments(argv=None):
12
"""
13
Parse command-line arguments for Green.
14
15
Args:
16
argv (list, optional): List of command-line arguments.
17
If None, uses sys.argv[1:].
18
19
Returns:
20
argparse.Namespace: Parsed arguments with all Green options including:
21
- targets: List of test targets to run
22
- verbose: Verbosity level (0-4)
23
- processes: Number of parallel processes
24
- run_coverage: Enable coverage reporting
25
- junit_report: Path for JUnit XML output
26
- config: Custom config file path
27
- and many more options
28
29
Example:
30
args = parseArguments(['tests/', '--verbose', '2', '--run-coverage'])
31
print(f"Targets: {args.targets}")
32
print(f"Verbose level: {args.verbose}")
33
"""
34
```
35
36
### Configuration Merging
37
38
Merges configuration from multiple sources with proper precedence: config files, environment variables, and command-line arguments.
39
40
```python { .api }
41
def mergeConfig(args, testing=False):
42
"""
43
Merge configuration from files, environment, and command-line arguments.
44
45
Configuration precedence (last wins):
46
1. $HOME/.green
47
2. Environment variable $GREEN_CONFIG file
48
3. setup.cfg in current directory
49
4. .green in current directory
50
5. --config FILE specified file
51
6. Command-line arguments
52
53
Args:
54
args (argparse.Namespace): Parsed command-line arguments
55
testing (bool): Enable testing mode behavior
56
57
Returns:
58
argparse.Namespace: Merged configuration with all sources combined
59
60
Example:
61
args = parseArguments(['tests/'])
62
merged_args = mergeConfig(args)
63
# Now merged_args contains settings from all config sources
64
"""
65
```
66
67
### Configuration File Loading
68
69
Loads configuration from specific files using configparser format.
70
71
```python { .api }
72
def getConfig(filepath=None):
73
"""
74
Load configuration from a specific file.
75
76
Args:
77
filepath (str, optional): Path to configuration file.
78
If None, returns empty config.
79
80
Returns:
81
configparser.ConfigParser: Configuration object with Green settings
82
83
Example:
84
config = getConfig('/path/to/green.cfg')
85
if config.has_section('green'):
86
verbose = config.getint('green', 'verbose', fallback=1)
87
"""
88
```
89
90
### Default Arguments
91
92
Provides default argument values for all Green configuration options.
93
94
```python { .api }
95
def get_default_args():
96
"""
97
Get default argument values for all Green options.
98
99
Returns:
100
argparse.Namespace: Default configuration with all options set to
101
their default values
102
103
Example:
104
defaults = get_default_args()
105
print(f"Default verbosity: {defaults.verbose}")
106
print(f"Default processes: {defaults.processes}")
107
"""
108
```
109
110
### Shell Completion Helper
111
112
Helper class for storing option lists used in shell completion functionality.
113
114
```python { .api }
115
class StoreOpt:
116
"""
117
Helper class for storing option lists for shell completion.
118
119
Used internally by Green to track available options for bash/zsh completion.
120
"""
121
```
122
123
## Configuration File Formats
124
125
### INI Format (.green, setup.cfg)
126
127
```ini
128
[green]
129
verbose = 2
130
processes = 4
131
run-coverage = true
132
omit-patterns = */tests/*,*/migrations/*
133
junit-report = test-results.xml
134
debug = false
135
keep-reports = false
136
```
137
138
### Environment Variables
139
140
```bash
141
# Specify custom config file
142
export GREEN_CONFIG=/path/to/custom/green.cfg
143
144
# Alternative to config files (not recommended for complex configs)
145
export GREEN_VERBOSE=2
146
export GREEN_PROCESSES=4
147
```
148
149
## Configuration Locations and Precedence
150
151
Green resolves configuration in this exact order (later settings override earlier ones):
152
153
1. **$HOME/.green** - Global user configuration
154
2. **$GREEN_CONFIG** - Custom config file from environment variable
155
3. **setup.cfg** - Project-level configuration in current directory
156
4. **.green** - Directory-specific configuration
157
5. **--config FILE** - Explicitly specified config file
158
6. **Command-line arguments** - Direct command-line options
159
160
### Example Configuration Scenarios
161
162
```python
163
# Scenario 1: Basic programmatic configuration
164
from green.config import parseArguments, mergeConfig
165
166
# Parse with defaults
167
args = parseArguments()
168
# Merge with config files
169
final_config = mergeConfig(args)
170
171
# Scenario 2: Custom arguments with config merging
172
args = parseArguments(['tests/', '--verbose', '2'])
173
final_config = mergeConfig(args, testing=True)
174
175
# Scenario 3: Loading specific config file
176
from green.config import getConfig
177
config = getConfig('custom-green.cfg')
178
```
179
180
## Available Configuration Options
181
182
### Output Control
183
- `verbose` (int): Verbosity level 0-4
184
- `no_color` (bool): Disable colored output
185
- `disable_windows` (bool): Disable Windows-specific formatting
186
- `debug` (int): Debug output level
187
188
### Test Discovery
189
- `file_pattern` (str): Test file pattern (default: 'test*.py')
190
- `test_pattern` (str): Test method pattern
191
- `targets` (list): Test targets to run
192
193
### Execution Control
194
- `processes` (int): Number of parallel processes (0 = auto-detect)
195
- `initializer` (str): Worker process initializer function
196
- `finalizer` (str): Worker process finalizer function
197
198
### Coverage Integration
199
- `run_coverage` (bool): Enable coverage reporting
200
- `coverage_config_file` (str): Coverage config file path
201
- `omit_patterns` (str): Coverage omit patterns (comma-separated)
202
203
### Output Formats
204
- `junit_report` (str): JUnit XML report file path
205
- `keep_reports` (bool): Keep temporary report files
206
207
### Django Integration
208
- `django_verbosity` (int): Django-specific verbosity level
209
210
## Advanced Configuration Examples
211
212
### Multi-Environment Setup
213
214
**development.cfg**:
215
```ini
216
[green]
217
verbose = 3
218
debug = 1
219
keep-reports = true
220
processes = 2
221
```
222
223
**ci.cfg**:
224
```ini
225
[green]
226
verbose = 1
227
junit-report = test-results.xml
228
run-coverage = true
229
processes = 0 # auto-detect for CI
230
```
231
232
**production-test.cfg**:
233
```ini
234
[green]
235
verbose = 0
236
processes = 8
237
omit-patterns = */tests/*,*/dev_tools/*
238
```
239
240
### Programmatic Configuration Override
241
242
```python
243
from green.config import parseArguments, mergeConfig
244
245
# Start with file-based config
246
args = parseArguments(['tests/'])
247
config = mergeConfig(args)
248
249
# Override specific settings programmatically
250
config.verbose = 3
251
config.processes = 1 # Force single-process for debugging
252
config.debug = 2
253
config.junit_report = 'debug-results.xml'
254
255
# Use the modified config
256
from green.runner import run
257
from green.loader import GreenTestLoader
258
from green.output import GreenStream
259
import sys
260
261
loader = GreenTestLoader()
262
suite = loader.loadTargets(config.targets)
263
stream = GreenStream(sys.stdout)
264
result = run(suite, stream, config)
265
```
266
267
### Complex Project Configuration
268
269
For large projects with multiple test suites:
270
271
**setup.cfg**:
272
```ini
273
[green]
274
# Base configuration
275
verbose = 1
276
processes = 0
277
run-coverage = true
278
omit-patterns = */migrations/*,*/venv/*,*/node_modules/*
279
280
# Different test patterns for different components
281
file-pattern = test*.py
282
283
[green:unit]
284
# Unit test specific settings (used with custom runner)
285
verbose = 2
286
processes = 4
287
288
[green:integration]
289
# Integration test settings
290
verbose = 1
291
processes = 1
292
keep-reports = true
293
```