0
# Configuration
1

2
Command-line interface and configuration system for customizing test execution, output formatting, test selection, and runtime behavior. Supports extensive options for different testing environments.
3

4
## Capabilities
5

6
### Configuration Class
7

8
Main configuration class that manages all behave configuration options and command-line argument parsing.
9

10
```python { .api }
11
class Configuration:
12
    """
13
    Main configuration class managing all behave settings.
14
    
15
    Attributes:
16
    - format: list, output formatter names
17
    - outdir: str, output directory path
18
    - outfiles: list, output file paths for formatters
19
    - dry_run: bool, show steps without executing them
20
    - verbosity: int, output verbosity level (0-2)
21
    - stop: bool, stop on first failure
22
    - tags: list, tag expressions for test selection
23
    - include_re: str, regex for including features by filename
24
    - exclude_re: str, regex for excluding features by filename
25
    - name: list, scenario name patterns to include
26
    - junit: bool, enable JUnit XML output
27
    - junit_directory: str, directory for JUnit XML files
28
    - logging_level: str, logging level ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG")
29
    - logging_format: str, log message format
30
    - logging_datefmt: str, log timestamp format
31
    - log_capture: bool, capture logging output
32
    - no_capture: bool, disable output capture
33
    - no_capture_stderr: bool, disable stderr capture  
34
    - color: bool, enable colored output
35
    - lang: str, language for step keywords
36
    - show_source: bool, show source location of step definitions
37
    - show_timings: bool, show step execution times
38
    - expand: bool, expand scenario outlines in formatters
39
    - show_multiline: bool, show multiline text in output
40
    
41
    Methods:
42
    - load_configuration(filenames): Load configuration from files
43
    - setup_outputs(): Initialize output formatters
44
    - setup_stage(stage): Configure for specific execution stage
45
    """
46
```
47

48
### Command Line Interface
49

50
Main CLI entry point that parses arguments and executes tests.
51

52
```python { .api }
53
def main(argv: list = None) -> int:
54
    """
55
    Main CLI entry point for behave command.
56
    
57
    Parameters:
58
    - argv: list, command line arguments (default: sys.argv)
59
    
60
    Returns:
61
    int: Exit code (0 for success, non-zero for failure)
62
    """
63
```
64

65
### Configuration Error Handling
66

67
Exception class for configuration-related errors and validation failures.
68

69
```python { .api }
70
class ConfigError(Exception):
71
    """
72
    Configuration error exception.
73
    
74
    Raised when:
75
    - Invalid configuration file format
76
    - Conflicting configuration options
77
    - Missing required configuration values
78
    - Invalid formatter specifications
79
    """
80
```
81

82
## Configuration Sources
83

84
Behave loads configuration from multiple sources in priority order:
85

86
### Command Line Arguments
87
```bash
88
# Basic execution
89
behave
90

91
# Specify features directory
92
behave features/
93

94
# Select specific feature file
95
behave features/login.feature
96

97
# Run with specific formatter
98
behave --format json --outfile results.json
99

100
# Run with tag selection
101
behave --tags @smoke --tags ~@slow
102

103
# Dry run (show steps without executing)
104
behave --dry-run
105

106
# Stop on first failure
107
behave --stop
108

109
# Increase verbosity
110
behave -v
111
```
112

113
### Configuration Files
114
Behave reads configuration from `.behaverc`, `setup.cfg`, or `pyproject.toml`:
115

116
#### .behaverc Format
117
```ini
118
[behave]
119
format = pretty
120
outdir = reports
121
tags = @current
122
stop = true
123
verbosity = 2
124
color = true
125
```
126

127
#### setup.cfg Format  
128
```ini
129
[behave]
130
format = pretty,json
131
outdir = test-reports
132
tags = @smoke,~@slow
133
junit = true
134
junit_directory = test-reports/junit
135
```
136

137
#### pyproject.toml Format
138
```toml
139
[tool.behave]
140
format = ["pretty", "json"]
141
outdir = "reports"
142
tags = ["@smoke", "~@slow"]
143
color = true
144
verbosity = 2
145
```
146

147
### Environment Variables
148
```bash
149
export BEHAVE_VERBOSITY=2
150
export BEHAVE_FORMAT=json
151
export BEHAVE_OUTDIR=reports
152
```
153

154
## Tag Selection
155

156
Powerful tag-based test selection system:
157

158
### Basic Tag Selection
159
```bash
160
# Run scenarios tagged with @smoke
161
behave --tags @smoke
162

163
# Run scenarios NOT tagged with @slow
164
behave --tags ~@slow
165

166
# Run scenarios tagged with @smoke AND not @slow
167
behave --tags @smoke --tags ~@slow
168
```
169

170
### Complex Tag Expressions
171
```bash
172
# OR logic (comma separation)
173
behave --tags @smoke,@regression
174

175
# AND logic with NOT
176
behave --tags @smoke --tags ~@manual
177

178
# Complex expressions
179
behave --tags "(@smoke or @regression) and not @slow"
180
```
181

182
## Output Formatting
183

184
### Built-in Formatters
185
```python { .api }
186
# Available formatter options:
187
formatters = [
188
    "plain",      # Simple text output
189
    "pretty",     # Enhanced text with colors
190
    "json",       # JSON format for tooling
191
    "json.pretty", # Pretty-printed JSON
192
    "junit",      # JUnit XML format
193
    "progress",   # Progress bar
194
    "progress2",  # Compact progress display
195
    "progress3",  # Detailed progress display
196
    "rerun",      # Failed scenario rerun info
197
    "tags",       # List all available tags
198
    "steps",      # List all step definitions
199
    "steps.doc",  # Step definitions with docstrings
200
    "steps.code", # Step definitions with source
201
    "steps.usage", # Step usage statistics
202
]
203
```
204

205
### Multiple Formatters
206
```bash
207
# Output to multiple formats
208
behave --format pretty --format json --outfile results.json
209

210
# Separate output files
211
behave --format pretty --format json:results.json --format junit:junit.xml
212
```
213

214
## Advanced Configuration Options
215

216
### Output Capture Control
217
```python
218
# Configuration options for output capture
219
config.log_capture = True          # Capture logging output
220
config.no_capture = False          # Enable stdout/stderr capture  
221
config.no_capture_stderr = False   # Enable stderr capture
222
config.show_source = True          # Show step definition locations
223
config.show_timings = True         # Show execution times
224
```
225

226
### Execution Control
227
```python
228
# Execution behavior options
229
config.dry_run = False             # Actually execute steps
230
config.stop = False                # Continue after failures
231
config.wip = False                 # Work-in-progress mode
232
config.expand = False              # Expand scenario outlines
233
config.lang = "en"                 # Language for keywords
234
```
235

236
### File Selection
237
```python
238
# File and scenario selection
239
config.include_re = r".*"          # Include pattern
240
config.exclude_re = None           # Exclude pattern  
241
config.name = []                   # Scenario name patterns
242
config.exclude_names = []          # Excluded scenario names
243
```
244

245
## Environment Integration
246

247
### Environment File (environment.py)
248
```python
249
# environment.py - Central configuration point
250
def before_all(context):
251
    # Global test setup
252
    context.config.setup_stage("before_all")
253
    setup_test_environment(context.config)
254

255
def before_feature(context, feature):
256
    # Feature-level setup based on tags
257
    if "database" in feature.tags:
258
        setup_database(context.config.database_url)
259

260
def after_all(context):
261
    # Global cleanup
262
    cleanup_test_environment()
263
```
264

265
### Configuration Access in Steps
266
```python
267
@given('I configure the system')
268
def step_impl(context):
269
    # Access configuration in steps
270
    base_url = context.config.base_url
271
    timeout = context.config.timeout
272
    # Use configuration values
273
```
274

275
## Custom Configuration
276

277
### Extending Configuration
278
```python
279
# Custom configuration class
280
class CustomConfiguration(Configuration):
281
    def __init__(self, **kwargs):
282
        super().__init__(**kwargs)
283
        self.custom_option = kwargs.get('custom_option', 'default')
284
        self.api_base_url = kwargs.get('api_base_url', 'http://localhost')
285
```
286

287
### Plugin Integration
288
```python
289
# Configuration for custom plugins
290
config.plugin_config = {
291
    'screenshot_on_failure': True,
292
    'screenshot_dir': 'screenshots',
293
    'browser_type': 'chrome',
294
    'headless': False
295
}
296
```
297

298
## Command Line Examples
299

300
### Common Usage Patterns
301
```bash
302
# Development workflow
303
behave --tags @current --stop -v
304

305
# CI/CD pipeline
306
behave --format json --outfile results.json --format junit --junit-directory reports/
307

308
# Smoke testing
309
behave --tags @smoke --format pretty --no-capture
310

311
# Regression testing  
312
behave --tags @regression --format progress --outdir reports/
313

314
# Debug mode
315
behave --tags @debug --dry-run --show-source -v
316

317
# Parallel execution preparation
318
behave --format rerun --outfile failed_scenarios.txt
319
```
320

321
### Environment-specific Runs
322
```bash
323
# Production-like environment
324
behave --define environment=prod --tags ~@local_only
325

326
# Local development
327
behave --define environment=local --no-capture --stop
328

329
# Staging environment
330
behave --define environment=staging --format json --outfile staging_results.json
331
```