0
# Mode Management
1

2
Replay's mode system controls how HTTP requests are handled, providing four distinct operational modes for different testing scenarios.
3

4
## Capabilities
5

6
### Mode Property
7

8
Controls the operational mode of the replay system.
9

10
```javascript { .api }
11
/**
12
 * Current operational mode
13
 * @type {'replay' | 'record' | 'cheat' | 'bloody'}
14
 */
15
Replay.mode: string;
16
```
17

18
**Usage Examples:**
19

20
```javascript
21
const Replay = require('replay');
22

23
// Set to record mode to capture new responses
24
Replay.mode = 'record';
25

26
// Set to replay mode for tests (default)
27
Replay.mode = 'replay';
28

29
// Set to cheat mode for development
30
Replay.mode = 'cheat';
31

32
// Set to bloody mode to bypass all replay functionality
33
Replay.mode = 'bloody';
34
```
35

36
### Environment Variable Configuration
37

38
The default mode can be set via environment variable:
39

40
```javascript { .api }
41
/**
42
 * Environment variable for default mode
43
 * @type {'replay' | 'record' | 'cheat' | 'bloody'}
44
 */
45
process.env.REPLAY: string;
46
```
47

48
**Usage Examples:**
49

50
```bash
51
# Run tests in record mode
52
REPLAY=record npm test
53

54
# Run in cheat mode
55
REPLAY=cheat node app.js
56

57
# Run in bloody mode (live requests)
58
REPLAY=bloody npm test
59
```
60

61
## Operational Modes
62

63
### Replay Mode (Default)
64

65
The default mode for running tests. Only replay captured responses, no outbound network access.
66

67
**Behavior:**
68
- Replays recorded HTTP responses from fixtures
69
- Blocks all outbound HTTP requests
70
- Throws connection refused error for unmatched requests
71
- Ensures deterministic, repeatable tests
72

73
**Use Cases:**
74
- Running automated tests
75
- CI/CD pipelines
76
- Offline development
77

78
### Record Mode
79

80
Captures new HTTP responses while replaying existing ones.
81

82
**Behavior:**
83
- Replays recorded responses when available
84
- Makes real HTTP requests for unmatched requests
85
- Saves new responses to fixture files
86
- Allows adding new test scenarios
87

88
**Use Cases:**
89
- Creating new tests
90
- Adding new API endpoints to existing tests
91
- Updating responses for changed APIs
92

93
### Cheat Mode
94

95
Allows both replay and live requests without recording.
96

97
**Behavior:**
98
- Replays recorded responses when available
99
- Makes real HTTP requests for unmatched requests
100
- Does not save new responses
101
- Useful for unstable development scenarios
102

103
**Use Cases:**
104
- Development with new, changing code
105
- Testing against live APIs without committing responses
106
- Debugging network issues
107

108
### Bloody Mode
109

110
Bypasses all replay functionality, all requests go live.
111

112
**Behavior:**
113
- All HTTP requests go to real servers
114
- No replay functionality
115
- No recording functionality
116
- Equivalent to not using Replay at all
117

118
**Use Cases:**
119
- Testing against live API changes
120
- Performance testing with real network conditions
121
- Validating recorded responses against current API behavior
122

123
## Error Handling
124

125
### Unsupported Mode Error
126

127
Thrown when an invalid mode is specified:
128

129
```javascript { .api }
130
/**
131
 * Error thrown for invalid mode
132
 * @throws {Error} When mode is not one of the supported values
133
 */
134
new Error(`Unsupported mode '${mode}', must be one of ${MODES.join(', ')}.`);
135
```
136

137
### Connection Refused Error
138

139
Thrown in replay mode when no matching fixture is found:
140

141
```javascript { .api }
142
/**
143
 * Error thrown when request cannot be replayed
144
 * @throws {Error} When in replay mode and no fixture matches
145
 */
146
new Error(`Connection to ${url} refused: not recording and no network access`);
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
const Replay = require('replay');
153

154
try {
155
  Replay.mode = 'invalid-mode';
156
} catch (error) {
157
  console.log(error.message); // "Unsupported mode 'invalid-mode', must be one of bloody, cheat, record, replay."
158
}
159

160
// In replay mode with no matching fixture
161
Replay.mode = 'replay';
162
http.get('http://new-api.example.com/data', (response) => {
163
  // This will throw: Connection to http://new-api.example.com:80/data refused: not recording and no network access
164
});
165
```