0
# CLI Integration
1

2
Comprehensive pytest integration providing command-line options, session management, and reporting capabilities. Syrupy automatically registers as a pytest plugin and provides both CLI options and pytest fixtures for snapshot testing workflows.
3

4
## Capabilities
5

6
### Command-Line Options
7

8
Syrupy adds several command-line options to pytest for controlling snapshot behavior, reporting, and configuration.
9

10
```python { .api }
11
def pytest_addoption(parser: "pytest.Parser") -> None:
12
    """
13
    Register syrupy command-line options with pytest.
14
    
15
    Adds options to pytest's argument parser for snapshot configuration,
16
    update modes, reporting, and extension selection.
17
    """
18
```
19

20
### Core Options
21

22
Essential options for snapshot update workflows and basic configuration.
23

24
```bash
25
# Update snapshots to match current test assertions
26
pytest --snapshot-update
27

28
# Show detailed information about snapshot operations
29
pytest --snapshot-details
30

31
# Warn about unused snapshots instead of failing tests
32
pytest --snapshot-warn-unused
33

34
# Disable colored output in test results
35
pytest --snapshot-no-colors
36
```
37

38
Usage examples:
39

40
```bash
41
# Standard workflow: run tests and update failing snapshots
42
pytest tests/
43
pytest --snapshot-update  # Update snapshots after reviewing failures
44

45
# Generate detailed report with snapshot file locations
46
pytest --snapshot-details tests/
47

48
# CI/CD friendly: don't fail on unused snapshots, just warn
49
pytest --snapshot-warn-unused tests/
50

51
# Terminal-friendly: disable colors for log processing
52
pytest --snapshot-no-colors tests/ > test_results.log
53
```
54

55
### Advanced Configuration
56

57
Options for customizing snapshot behavior, extensions, and diff display.
58

59
```bash
60
# Use custom extension class by default
61
pytest --snapshot-default-extension=syrupy.extensions.json.JSONSnapshotExtension
62

63
# Control diff display mode for performance
64
pytest --snapshot-diff-mode=detailed  # Show full diffs (default)
65
pytest --snapshot-diff-mode=disabled  # Disable diffs for large snapshots
66

67
# Ignore specific file extensions during snapshot discovery
68
pytest --snapshot-ignore-file-extensions=.tmp,.cache
69

70
# Enable PyCharm diff integration
71
pytest --snapshot-patch-pycharm-diff
72
```
73

74
Usage examples:
75

76
```bash
77
# Use JSON extension for all snapshots in a test run
78
pytest --snapshot-default-extension=syrupy.extensions.json.JSONSnapshotExtension tests/api/
79

80
# Optimize performance for tests with large snapshots
81
pytest --snapshot-diff-mode=disabled tests/integration/
82

83
# Ignore temporary and cache files when checking for unused snapshots
84
pytest --snapshot-ignore-file-extensions=.tmp,.cache,.bak tests/
85

86
# IDE integration for better diff viewing
87
pytest --snapshot-patch-pycharm-diff tests/
88
```
89

90
### Session Management
91

92
Internal pytest hooks managing snapshot session lifecycle, test collection, and reporting.
93

94
```python { .api }
95
def pytest_sessionstart(session: Any) -> None:
96
    """Initialize snapshot session before tests are collected and run."""
97

98
def pytest_collection_modifyitems(session: Any, config: Any, items: List["pytest.Item"]) -> None:
99
    """Process collected test items after collection."""
100

101
def pytest_collection_finish(session: Any) -> None:
102
    """Finalize test collection and select snapshot-related items."""
103

104
def pytest_runtest_logreport(report: pytest.TestReport) -> None:
105
    """Handle test run reports during setup, call, and teardown phases."""
106

107
def pytest_sessionfinish(session: "pytest.Session", exitstatus: int) -> None:
108
    """Finalize snapshot session and set appropriate exit status."""
109

110
def pytest_terminal_summary(terminalreporter: Any, exitstatus: int, config: Any) -> None:
111
    """Add syrupy-specific summary to pytest terminal output."""
112
```
113

114
### Snapshot Fixture
115

116
Primary pytest fixture providing the snapshot assertion interface to test functions.
117

118
```python { .api }
119
@pytest.fixture
120
def snapshot(request: "pytest.FixtureRequest") -> "SnapshotAssertion":
121
    """
122
    Pytest fixture providing snapshot assertion capability.
123
    
124
    Parameters:
125
    - request: Pytest fixture request containing configuration and test context
126
    
127
    Returns:
128
    SnapshotAssertion: Configured snapshot assertion instance
129
    
130
    The fixture automatically configures based on CLI options:
131
    - update_snapshots: From --snapshot-update flag
132
    - extension_class: From --snapshot-default-extension option  
133
    - test_location: Derived from pytest test node
134
    - session: Active snapshot session
135
    """
136
```
137

138
Usage examples:
139

140
```python
141
def test_basic_fixture(snapshot):
142
    """Standard fixture usage"""
143
    result = {"message": "Hello world"}
144
    assert result == snapshot
145

146
def test_fixture_configuration(snapshot):
147
    """Fixture respects CLI configuration"""
148
    # If run with --snapshot-default-extension=syrupy.extensions.json.JSONSnapshotExtension
149
    # this will automatically use JSON extension
150
    data = {"users": [{"name": "Alice"}]}
151
    assert data == snapshot
152

153
def test_multiple_snapshots(snapshot):
154
    """Fixture supports multiple snapshots per test"""
155
    assert "first snapshot" == snapshot
156
    assert {"second": "snapshot"} == snapshot
157
    assert ["third", "snapshot"] == snapshot
158

159
# Session-scoped IDE integration fixture
160
@pytest.fixture(scope="session", autouse=True)
161
def _syrupy_apply_ide_patches(request: "pytest.FixtureRequest") -> Iterator[None]:
162
    """
163
    Automatic fixture for IDE integration patches.
164
    
165
    Applies when --snapshot-patch-pycharm-diff is enabled.
166
    """
167
```
168

169
### Assertion Representation
170

171
Custom assertion failure messages and diff display for snapshot comparisons.
172

173
```python { .api }
174
def pytest_assertrepr_compare(config: "pytest.Config", op: str, left: Any, right: Any) -> Optional[List[str]]:
175
    """
176
    Provide custom assertion representation for snapshot comparisons.
177
    
178
    Parameters:
179
    - config: Pytest configuration with syrupy options
180
    - op: Comparison operator (typically "==")
181
    - left: Left side of comparison (often SnapshotAssertion)
182
    - right: Right side of comparison (test data)
183
    
184
    Returns:
185
    Optional[List[str]]: Custom assertion failure message lines
186
    """
187
```
188

189
Example assertion output:
190

191
```
192
def test_failing_snapshot(snapshot):
193
    actual = {"name": "Bob", "age": 25}
194
    assert actual == snapshot
195
    
196
# When snapshot contains {"name": "Alice", "age": 30}, output shows:
197
# 
198
# >       assert actual == snapshot
199
# E       AssertionError: assert {'age': 25, 'name': 'Bob'} == snapshot_name
200
# E         [- snapshot_name] [+ received]
201
# E         {
202
# E         - 'age': 30,
203
# E         + 'age': 25,
204
# E         - 'name': 'Alice',
205
# E         + 'name': 'Bob',
206
# E         }
207
```
208

209
### Exit Status Handling
210

211
Syrupy modifies pytest exit status based on snapshot-specific conditions.
212

213
```python { .api }
214
EXIT_STATUS_FAIL_UNUSED = 1  # Exit code when unused snapshots found
215
```
216

217
Exit status behavior:
218

219
```bash
220
# Normal test failures: exit code from pytest
221
pytest tests/  # Exit 1 if tests fail, 0 if pass
222

223
# Unused snapshots found: exit code 1 (unless --snapshot-warn-unused)
224
pytest tests/  # Exit 1 if unused snapshots exist
225

226
# With warning mode: exit code 0 even with unused snapshots
227
pytest --snapshot-warn-unused tests/  # Exit 0, just warns about unused
228

229
# Update mode: cleans up unused snapshots
230
pytest --snapshot-update tests/  # Removes unused snapshots, exit 0 if successful
231
```
232

233
### Environment Variables
234

235
Environment variables that affect syrupy behavior:
236

237
```python { .api }
238
DISABLE_COLOR_ENV_VAR = "ANSI_COLORS_DISABLED"  # Disable colored output
239
# Alternative: NO_COLOR environment variable also disables colors
240
```
241

242
Usage examples:
243

244
```bash
245
# Disable colors via environment variable
246
export ANSI_COLORS_DISABLED=1
247
pytest tests/
248

249
# Alternative color disabling
250
export NO_COLOR=1
251
pytest tests/
252

253
# Override in single command
254
ANSI_COLORS_DISABLED=1 pytest tests/
255
```
256

257
### Integration Examples
258

259
Complete examples showing CLI integration in different scenarios:
260

261
```bash
262
# Development workflow
263
pytest tests/test_api.py                    # Run tests, see failures
264
pytest --snapshot-update tests/test_api.py # Update snapshots after review
265

266
# CI/CD pipeline
267
pytest --snapshot-warn-unused tests/       # Don't fail on unused snapshots
268
pytest --snapshot-no-colors tests/ > results.log  # Log-friendly output
269

270
# Performance testing with large snapshots  
271
pytest --snapshot-diff-mode=disabled tests/large_data/
272

273
# JSON API testing
274
pytest --snapshot-default-extension=syrupy.extensions.json.JSONSnapshotExtension tests/api/
275

276
# Comprehensive reporting
277
pytest --snapshot-details --snapshot-warn-unused tests/
278

279
# IDE integration
280
pytest --snapshot-patch-pycharm-diff tests/
281

282
# Custom extension with detailed reporting
283
pytest \
284
  --snapshot-default-extension=myproject.extensions.CustomExtension \
285
  --snapshot-details \
286
  --snapshot-update \
287
  tests/custom/
288
```
289

290
### Plugin Registration
291

292
Syrupy automatically registers as a pytest plugin through setuptools entry points:
293

294
```toml
295
# In pyproject.toml
296
[tool.poetry.plugins.pytest11]
297
syrupy = 'syrupy'
298
```
299

300
This enables automatic discovery and loading when syrupy is installed, making all CLI options and fixtures available without additional configuration.