0
# Error and Abort Handling
1

2
Functionality for mocking network failures, HTTP errors, and request aborts. Essential for testing error handling and network failure scenarios in your application.
3

4
## Capabilities
5

6
### Mock Reject
7

8
Makes fetch calls reject with a specified error or custom error function. Used to simulate network failures or other request errors.
9

10
```javascript { .api }
11
/**
12
 * Mock all fetch calls to reject with specified error
13
 * @param errorOrFunction - Error object, string, or function that returns a promise rejection
14
 * @returns FetchMock instance for chaining
15
 */
16
fetch.mockReject(errorOrFunction);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
// Simple error string
23
fetch.mockReject("Network error");
24

25
// Error object
26
fetch.mockReject(new Error("Connection failed"));
27

28
// Custom error function
29
fetch.mockReject(() => Promise.reject(new TypeError("Failed to fetch")));
30

31
// In a test
32
it("handles network errors", async () => {
33
  fetch.mockReject("Network failure");
34
  
35
  await expect(fetch("/api/data")).rejects.toThrow("Network failure");
36
});
37
```
38

39
### Mock Reject Once
40

41
Makes the next fetch call reject with a specified error. Subsequent calls will use default behavior or other configured mocks.
42

43
```javascript { .api }
44
/**
45
 * Mock the next fetch call to reject with specified error
46
 * @param errorOrFunction - Error object, string, or function that returns a promise rejection  
47
 * @returns FetchMock instance for chaining
48
 */
49
fetch.mockRejectOnce(errorOrFunction);
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
// Single rejection followed by normal mock
56
fetch.mockRejectOnce("First call fails");
57
fetch.mockResponse("Second call succeeds");
58

59
// Test retry logic
60
it("retries on failure", async () => {
61
  fetch
62
    .mockRejectOnce("First attempt fails")
63
    .mockResponseOnce("Success on retry");
64
    
65
  // Your retry logic here
66
  const result = await retryableFetch("/api/data");
67
  expect(result).toBe("Success on retry");
68
});
69
```
70

71
### Mock Abort
72

73
Makes all fetch calls throw a DOMException with name "AbortError", simulating an aborted request.
74

75
```javascript { .api }
76
/**
77
 * Mock all fetch calls to abort (throw DOMException AbortError)
78
 * @returns FetchMock instance for chaining
79
 */
80
fetch.mockAbort();
81
```
82

83
**Usage Examples:**
84

85
```javascript
86
// Mock all requests to abort
87
fetch.mockAbort();
88

89
// Test abort handling
90
it("handles aborted requests", async () => {
91
  fetch.mockAbort();
92
  
93
  await expect(fetch("/api/data")).rejects.toThrow(
94
    expect.objectContaining({
95
      name: "AbortError"
96
    })
97
  );
98
});
99
```
100

101
### Mock Abort Once
102

103
Makes the next fetch call throw a DOMException with name "AbortError". Subsequent calls will use default behavior.
104

105
```javascript { .api }
106
/**
107
 * Mock the next fetch call to abort (throw DOMException AbortError)
108
 * @returns FetchMock instance for chaining
109
 */
110
fetch.mockAbortOnce();
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
// Single abort followed by normal response
117
fetch.mockAbortOnce();
118
fetch.mockResponse("Success after abort");
119

120
// Test abort controller integration
121
it("respects abort signals", async () => {
122
  const controller = new AbortController();
123
  
124
  // Mock abort for explicit signal
125
  fetch.mockAbortOnce();
126
  
127
  await expect(
128
    fetch("/api/data", { signal: controller.signal })
129
  ).rejects.toThrow(expect.any(DOMException));
130
});
131
```
132

133
## Types
134

135
```typescript { .api }
136
/**
137
 * Union type for error parameters in reject methods
138
 */
139
type ErrorOrFunction = Error | ((...args: any[]) => Promise<any>);
140
```
141

142
## Error Patterns
143

144
### Network Failures
145

146
```javascript
147
// Simulate connection timeout
148
fetch.mockReject(new Error("ETIMEDOUT"));
149

150
// Simulate DNS resolution failure  
151
fetch.mockReject(new Error("ENOTFOUND"));
152

153
// Simulate connection refused
154
fetch.mockReject(new Error("ECONNREFUSED"));
155
```
156

157
### HTTP Errors vs Network Errors
158

159
```javascript
160
// HTTP error (still resolves, check response.ok)
161
fetch.mockResponse("Not Found", { status: 404 });
162

163
// Network error (promise rejects)
164
fetch.mockReject("Network failure");
165

166
// Abort error (promise rejects with DOMException)
167
fetch.mockAbort();
168
```
169

170
### Testing Error Recovery
171

172
```javascript
173
it("recovers from transient failures", async () => {
174
  // First call fails, second succeeds
175
  fetch
176
    .mockRejectOnce("Temporary failure")
177
    .mockResponseOnce(JSON.stringify({ data: "success" }));
178
    
179
  // Test your retry logic
180
  const result = await fetchWithRetry("/api/data");
181
  expect(JSON.parse(result)).toEqual({ data: "success" });
182
});
183
```