0
# Record Modes
1

2
Recording behavior configuration that determines when HTTP interactions are recorded versus replayed from existing cassettes. Record modes provide fine-grained control over VCR.py's recording strategy for different testing scenarios.
3

4
## Capabilities
5

6
### RecordMode Enum
7

8
Enumeration defining when VCR will record HTTP interactions to cassettes.
9

10
```python { .api }
11
class RecordMode(str, Enum):
12
    """
13
    Configures when VCR will record to the cassette.
14
    
15
    Can be used either as enum values (vcr.mode.ONCE) or as strings ("once").
16
    """
17
    ALL = "all"
18
    ANY = "any"
19
    NEW_EPISODES = "new_episodes" 
20
    NONE = "none"
21
    ONCE = "once"
22
```
23

24
### Mode Alias
25

26
```python { .api }
27
# Alias for RecordMode for backward compatibility
28
mode = RecordMode
29
```
30

31
## Record Mode Behaviors
32

33
### ONCE Mode
34

35
**Value:** `"once"`  
36
**Behavior:** Records the first set of requests, then replays them on subsequent runs. Attempting to add new episodes fails.
37

38
```python
39
import vcr
40

41
# Using enum
42
my_vcr = vcr.VCR(record_mode=vcr.mode.ONCE)
43

44
# Using string
45
my_vcr = vcr.VCR(record_mode="once")
46

47
@my_vcr.use_cassette('test.yaml')
48
def test_once_mode():
49
    # First run: records all HTTP interactions
50
    # Subsequent runs: replays recorded interactions
51
    # New requests not in cassette will cause test failure
52
    pass
53
```
54

55
### NEW_EPISODES Mode
56

57
**Value:** `"new_episodes"`  
58
**Behavior:** Replays existing interactions from cassette, but records any new requests not found in the cassette.
59

60
```python
61
my_vcr = vcr.VCR(record_mode=vcr.mode.NEW_EPISODES)
62

63
@my_vcr.use_cassette('test.yaml')
64
def test_new_episodes():
65
    # Existing requests: replayed from cassette
66
    # New requests: recorded and added to cassette
67
    # Useful for evolving APIs or adding new test coverage
68
    pass
69
```
70

71
### ALL Mode
72

73
**Value:** `"all"`  
74
**Behavior:** Records every request, regardless of whether it already exists in the cassette.
75

76
```python
77
my_vcr = vcr.VCR(record_mode=vcr.mode.ALL)
78

79
@my_vcr.use_cassette('test.yaml')
80
def test_all_mode():
81
    # Every HTTP request is recorded
82
    # Cassette grows with each test run
83
    # Useful for debugging or capturing request variations
84
    pass
85
```
86

87
### NONE Mode
88

89
**Value:** `"none"`  
90
**Behavior:** No requests are recorded. Only existing cassette interactions are replayed.
91

92
```python
93
my_vcr = vcr.VCR(record_mode=vcr.mode.NONE)
94

95
@my_vcr.use_cassette('test.yaml')
96
def test_none_mode():
97
    # No recording occurs
98
    # Only existing cassette interactions available
99
    # New requests will cause UnhandledHTTPRequestError
100
    # Useful for ensuring tests don't make unexpected requests
101
    pass
102
```
103

104
### ANY Mode
105

106
**Value:** `"any"`  
107
**Behavior:** Special recording mode with specific matching behavior.
108

109
```python
110
my_vcr = vcr.VCR(record_mode=vcr.mode.ANY)
111

112
@my_vcr.use_cassette('test.yaml') 
113
def test_any_mode():
114
    # Special matching behavior
115
    # Consult VCR.py documentation for specific ANY mode semantics
116
    pass
117
```
118

119
## Usage Patterns
120

121
### Development Workflow
122

123
```python
124
import vcr
125

126
# During initial development - record all interactions
127
dev_vcr = vcr.VCR(record_mode=vcr.mode.ALL)
128

129
# For stable tests - use recorded interactions only
130
stable_vcr = vcr.VCR(record_mode=vcr.mode.ONCE)
131

132
# When adding new features - record new requests
133
incremental_vcr = vcr.VCR(record_mode=vcr.mode.NEW_EPISODES)
134

135
# For CI/production - ensure no unexpected requests  
136
strict_vcr = vcr.VCR(record_mode=vcr.mode.NONE)
137
```
138

139
### Dynamic Mode Selection
140

141
```python
142
import os
143
import vcr
144

145
# Select mode based on environment
146
mode = os.environ.get('VCR_RECORD_MODE', 'once')
147
my_vcr = vcr.VCR(record_mode=mode)
148

149
@my_vcr.use_cassette('test.yaml')
150
def test_with_env_mode():
151
    # Mode controlled by environment variable
152
    # VCR_RECORD_MODE=all pytest test_file.py
153
    # VCR_RECORD_MODE=none pytest test_file.py
154
    pass
155
```
156

157
### Per-Test Mode Override
158

159
```python
160
base_vcr = vcr.VCR(record_mode=vcr.mode.ONCE)
161

162
@base_vcr.use_cassette('test.yaml', record_mode=vcr.mode.NEW_EPISODES)
163
def test_with_mode_override():
164
    # Override the base VCR's record mode for this specific test
165
    # Useful for individual test customization
166
    pass
167
```
168

169
## Error Scenarios
170

171
### ONCE Mode with New Requests
172

173
When using `ONCE` mode, attempts to make requests not in the cassette will raise an exception:
174

175
```python
176
import vcr
177

178
@vcr.use_cassette('existing.yaml', record_mode='once')
179
def test_new_request_fails():
180
    # If existing.yaml doesn't contain this request:
181
    # Raises: CannotOverwriteExistingCassetteException
182
    response = requests.get('http://new-endpoint.com')
183
```
184

185
### NONE Mode with Missing Requests
186

187
When using `NONE` mode, requests not in the cassette will raise an error:
188

189
```python
190
@vcr.use_cassette('partial.yaml', record_mode='none')
191
def test_missing_request_fails():
192
    # If partial.yaml doesn't contain this request:
193
    # Raises: UnhandledHTTPRequestError
194
    response = requests.get('http://missing-endpoint.com')
195
```