0
# Mock Creation
1

2
HTTP method functions and mock creation patterns for intercepting and mocking HTTP requests. These functions provide the primary interface for creating mocks using pook's fluent API, allowing you to easily set up request interceptions with method-specific shortcuts.
3

4
## Capabilities
5

6
### Generic Mock Creation
7

8
Creates a generic HTTP mock that can be configured for any HTTP method and request pattern.
9

10
```python { .api }
11
def mock(url=None, **kw):
12
    """
13
    Creates and registers a new HTTP mock.
14
    
15
    Parameters:
16
    - url (str, optional): Request URL to mock
17
    - activate (bool, optional): Force mock engine activation. Defaults to False
18
    - **kw: Variadic keyword arguments for Mock constructor including:
19
        - method (str): HTTP method name to match
20
        - path (str): URL path to match
21
        - headers (dict): Header values to match
22
        - params (dict): URL params to match
23
        - body (str|regex): Request body to match
24
        - json (dict|list|str|regex): JSON payload body to match
25
        - times (int): Mock TTL or maximum number of matches
26
        - persist (bool): Enable persistent mode
27
        - reply (int): Mock response status code
28
        - response_body (str): Response body to use
29
        - response_json (dict|list|str): Response JSON to use
30
    
31
    Returns:
32
    Mock: New mock instance
33
    """
34
```
35

36
Usage examples:
37

38
```python
39
import pook
40

41
# Basic mock creation
42
mock = pook.mock('https://api.example.com/data')
43
mock.method('POST').json({'key': 'value'}).reply(201)
44

45
# Mock with immediate configuration
46
pook.mock('https://api.example.com/users', 
47
          method='GET', 
48
          reply=200, 
49
          response_json={'users': []})
50

51
# Force engine activation
52
pook.mock('https://api.example.com/health', activate=True).reply(200)
53
```
54

55
### GET Method Mock
56

57
Creates a mock specifically for GET requests with convenient method-specific configuration.
58

59
```python { .api }
60
def get(url, **kw):
61
    """
62
    Registers a new mock HTTP request with GET method.
63
    
64
    Parameters:
65
    - url (str): Request URL to mock
66
    - **kw: Additional Mock constructor arguments (same as mock() function)
67
    
68
    Returns:
69
    Mock: Mock instance configured for GET method
70
    """
71
```
72

73
Usage examples:
74

75
```python
76
import pook
77

78
# Simple GET mock
79
pook.get('https://api.example.com/users').reply(200).json([
80
    {'id': 1, 'name': 'John'},
81
    {'id': 2, 'name': 'Jane'}
82
])
83

84
# GET with query parameters
85
pook.get('https://api.example.com/users').param('page', '1').param('limit', '10').reply(200)
86

87
# GET with headers validation
88
pook.get('https://api.example.com/protected').header('Authorization', 'Bearer token').reply(200)
89
```
90

91
### POST Method Mock
92

93
Creates a mock for POST requests with support for request body validation and response configuration.
94

95
```python { .api }
96
def post(url, **kw):
97
    """
98
    Registers a new mock HTTP request with POST method.
99
    
100
    Parameters:
101
    - url (str): Request URL to mock
102
    - **kw: Additional Mock constructor arguments (same as mock() function)
103
    
104
    Returns:
105
    Mock: Mock instance configured for POST method
106
    """
107
```
108

109
Usage examples:
110

111
```python
112
import pook
113

114
# POST with JSON body validation
115
pook.post('https://api.example.com/users').json({
116
    'name': 'John Doe',
117
    'email': 'john@example.com'
118
}).reply(201).json({'id': 123, 'name': 'John Doe'})
119

120
# POST with form data
121
pook.post('https://api.example.com/login').body('username=admin&password=secret').reply(200)
122

123
# POST with content type validation
124
pook.post('https://api.example.com/upload').type('application/json').reply(200)
125
```
126

127
### PUT Method Mock
128

129
Creates a mock for PUT requests, typically used for updating resources.
130

131
```python { .api }
132
def put(url, **kw):
133
    """
134
    Registers a new mock HTTP request with PUT method.
135
    
136
    Parameters:
137
    - url (str): Request URL to mock
138
    - **kw: Additional Mock constructor arguments (same as mock() function)
139
    
140
    Returns:
141
    Mock: Mock instance configured for PUT method
142
    """
143
```
144

145
Usage examples:
146

147
```python
148
import pook
149

150
# PUT for resource updates
151
pook.put('https://api.example.com/users/123').json({
152
    'name': 'John Smith',
153
    'email': 'john.smith@example.com'
154
}).reply(200).json({'id': 123, 'name': 'John Smith'})
155

156
# PUT with path parameters
157
pook.put('https://api.example.com/users/123').reply(204)
158
```
159

160
### PATCH Method Mock
161

162
Creates a mock for PATCH requests, used for partial resource updates.
163

164
```python { .api }
165
def patch(url=None, **kw):
166
    """
167
    Registers a new mock HTTP request with PATCH method.
168
    
169
    Parameters:
170
    - url (str): Request URL to mock
171
    - **kw: Additional Mock constructor arguments (same as mock() function)
172
    
173
    Returns:
174
    Mock: Mock instance configured for PATCH method
175
    """
176
```
177

178
Usage examples:
179

180
```python
181
import pook
182

183
# PATCH for partial updates
184
pook.patch('https://api.example.com/users/123').json({
185
    'email': 'newemail@example.com'
186
}).reply(200).json({'id': 123, 'email': 'newemail@example.com'})
187

188
# PATCH with validation
189
pook.patch('https://api.example.com/settings').header('Content-Type', 'application/json').reply(200)
190
```
191

192
### DELETE Method Mock
193

194
Creates a mock for DELETE requests, typically used for resource deletion.
195

196
```python { .api }
197
def delete(url, **kw):
198
    """
199
    Registers a new mock HTTP request with DELETE method.
200
    
201
    Parameters:
202
    - url (str): Request URL to mock  
203
    - **kw: Additional Mock constructor arguments (same as mock() function)
204
    
205
    Returns:
206
    Mock: Mock instance configured for DELETE method
207
    """
208
```
209

210
Usage examples:
211

212
```python
213
import pook
214

215
# DELETE with no response body
216
pook.delete('https://api.example.com/users/123').reply(204)
217

218
# DELETE with confirmation response
219
pook.delete('https://api.example.com/users/123').reply(200).json({
220
    'message': 'User deleted successfully'
221
})
222

223
# DELETE with authorization check
224
pook.delete('https://api.example.com/users/123').header('Authorization', 'Bearer token').reply(204)
225
```
226

227
### HEAD Method Mock
228

229
Creates a mock for HEAD requests, used to retrieve headers without response body.
230

231
```python { .api }
232
def head(url, **kw):
233
    """
234
    Registers a new mock HTTP request with HEAD method.
235
    
236
    Parameters:
237
    - url (str): Request URL to mock
238
    - **kw: Additional Mock constructor arguments (same as mock() function)
239
    
240
    Returns:
241
    Mock: Mock instance configured for HEAD method
242
    """
243
```
244

245
Usage examples:
246

247
```python
248
import pook
249

250
# HEAD request for resource existence check
251
pook.head('https://api.example.com/users/123').reply(200).header('Content-Length', '1024')
252

253
# HEAD with custom headers
254
pook.head('https://api.example.com/files/document.pdf').reply(200).headers({
255
    'Content-Type': 'application/pdf',
256
    'Content-Length': '2048576',
257
    'Last-Modified': 'Wed, 21 Oct 2023 07:28:00 GMT'
258
})
259
```
260

261
### OPTIONS Method Mock
262

263
Creates a mock for OPTIONS requests, typically used for CORS preflight requests.
264

265
```python { .api }
266
def options(url=None, **kw):
267
    """
268
    Registers a new mock HTTP request with OPTIONS method.
269
    
270
    Parameters:
271
    - url (str): Request URL to mock
272
    - **kw: Additional Mock constructor arguments (same as mock() function)
273
    
274
    Returns:
275
    Mock: Mock instance configured for OPTIONS method
276
    """
277
```
278

279
Usage examples:
280

281
```python
282
import pook
283

284
# OPTIONS for CORS preflight
285
pook.options('https://api.example.com/users').reply(200).headers({
286
    'Access-Control-Allow-Origin': '*',
287
    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
288
    'Access-Control-Allow-Headers': 'Content-Type, Authorization'
289
})
290

291
# OPTIONS with specific origin validation
292
pook.options('https://api.example.com/data').header('Origin', 'https://myapp.com').reply(200)
293
```
294

295
## Fluent API Patterns
296

297
All mock creation functions return Mock instances that support method chaining:
298

299
```python
300
# Chaining multiple configurations
301
pook.get('https://api.example.com/users') \
302
    .header('Authorization', 'Bearer token') \
303
    .param('page', '1') \
304
    .reply(200) \
305
    .json({'users': [], 'total': 0})
306

307
# Complex request matching
308
pook.post('https://api.example.com/webhooks') \
309
    .header('X-Webhook-Secret', 'secret123') \
310
    .json({'event': 'user.created'}) \
311
    .reply(200) \
312
    .json({'received': True})
313

314
# Multiple response scenarios
315
mock = pook.get('https://api.example.com/flaky-endpoint')
316
mock.times(3).reply(500)  # Fail 3 times
317
mock.reply(200).json({'data': 'success'})  # Then succeed
318
```
319

320
## Context Integration
321

322
Mock creation functions work seamlessly with pook's context management:
323

324
```python
325
# Using with activation decorator
326
@pook.activate
327
def test_api():
328
    pook.get('https://api.example.com/test').reply(200)
329
    # Test code here
330

331
# Using with context manager
332
with pook.use():
333
    pook.post('https://api.example.com/data').reply(201)
334
    # HTTP requests are mocked within this block
335

336
# Using with isolated engines
337
with pook.use() as engine:
338
    engine.mock('https://api.example.com/isolated').reply(200)
339
    # Isolated mock scope
340
```