• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Mocks
2
3The use of [Mock objects](https://en.wikipedia.org/wiki/Mock_object) is a standard testing methodology for Python and other object-oriented languages. This library defines Mock classes that simulate responses to API calls. You can use them to test how your code handles basic interactions with Google APIs.
4
5> **Note:** Many of the [Python Client Library test scripts](https://github.com/googleapis/google-api-python-client/tree/main/tests) use these classes.
6
7## HttpMock
8
9This class simulates the response to a single HTTP request. As arguments, the constructor for the [HttpMock](https://googleapis.github.io/google-api-python-client/docs/epy/googleapiclient.http.HttpMock-class.html) object takes a dictionary object representing the response header and the path to a file. When this resource built on this object is executed, it simply returns contents of the file.
10
11### Example
12
13This example uses `HttpMock` to simulate the basic steps necessary to complete an API call to the [Google Books API](https://developers.google.com/apis-explorer/#p/books/v1/). The first Mock HTTP returns a status code of 200 and a file named `books-discovery.json`, which is the discovery document that describes the Books API. This file is a necessary part of the building of the service object, which takes place in the next few lines. The actual request is executed using the second Mock object. This returns the contents of `books-android.json`, the simulated response.
14
15```python
16from googleapiclient.discovery import build
17from googleapiclient.http import HttpMock
18import pprint
19
20http = HttpMock('books-discovery.json', {'status': '200'})
21api_key = 'your_api_key'
22service = build('books', 'v1', http=http, developerKey=api_key)
23request = service.volumes().list(source='public', q='android')
24http = HttpMock('books-android.json', {'status': '200'})
25response = request.execute(http=http)
26pprint.pprint(response)
27```
28
29> **Notes:**
30> - To run this sample, it would not be necessary to replace the placeholder your_api_key with an actual key, since the Mock object does not actually call the API.
31> - As you develop and test your application, it is a good idea to save actual API responses in files like books-discovery.json or books-android.json for use in testing.
32> - Notice that a second HttpMock is created to simulate the second HTTP call.
33> - The second use of the execute method demonstrates how you can re-use the request object by calling execute with another Mock object as an argument. (This would also work with an actual HTTP call.)
34
35## HttpMockSequence
36
37The [HttpMockSequence](https://googleapis.github.io/google-api-python-client/docs/epy/googleapiclient.http.HttpMockSequence-class.html) class simulates the sequence of HTTP responses. Each response consists of a header (a dictionary) and a content object (which can be a reference to a file, a JSON-like data structure defined inline, or one of the keywords listed below). When the resource built from this Mock object is executed, it returns the series of responses, one by one.
38
39### Special Values for simulated HTTP responses
40
41Instead of a pre-defined object, your code can use one of the following keywords as the content object of a simulated HTTP response. At runtime, the Mock object returns the information described in the table.
42
43<table>
44  <tbody><tr>
45    <th>
46      Keyword
47    </th>
48    <th>
49      Returns:
50    </th>
51  </tr>
52  <tr>
53    <td>
54      <code><span>echo_request_headers</span></code>
55    </td>
56    <td>
57      the complete request headers
58    </td>
59  </tr>
60  <tr>
61    <td>
62      <code><span>echo_request_headers_as_json</span></code>
63    </td>
64    <td>
65      the complete request headers as a json object
66    </td>
67  </tr>
68  <tr>
69    <td>
70      <code><span>echo_request_body</span></code>
71    </td>
72    <td>
73      the request body
74    </td>
75  </tr>
76  <tr>
77    <td>
78      <code><span>echo_request_uri</span></code>
79    </td>
80    <td>
81      the request uri
82    </td>
83  </tr></tbody>
84</table>
85
86### Example
87
88The following code snippet combines the two HTTP call simulations from the previous snippet into a single Mock object. The object created using `HttpMockSequence` simulates the return of the discovery document from the `books.volume.list` service, then the return of the result of the 'android' query (built in to the `request` object). You could add code to this snipped to print the contents of `response`, test that it returned successfully, etc.
89
90```python
91from googleapiclient.discovery import build
92from googleapiclient.http import HttpMockSequence
93
94books_discovery = # Saved data from a build response
95books_android = # Saved data from a request to list android volumes
96
97http = HttpMockSequence([
98    ({'status': '200'}, books_discovery),
99    ({'status': '200'}, books_android)])
100api_key = 'your_api_key'
101service = build('books', 'v1',
102                http=http,
103                developerKey=your_api_key)
104request = service.volumes().list(source='public', q='android')
105response = request.execute()
106```
107