Skip to content

Commit c863514

Browse files
Di PengIgorMinar
Di Peng
authored and
IgorMinar
committed
doc(angular.mock.service.$browser): add xhr docs
1 parent 86a6cc7 commit c863514

File tree

1 file changed

+121
-2
lines changed

1 file changed

+121
-2
lines changed

‎src/angular-mocks.js

Lines changed: 121 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,8 +69,8 @@
6969
* Built-in mocks:
7070
*
7171
* * {@link angular.mock.service.$browser $browser } - A mock implementation of the browser.
72-
* * {@link angular.mock.service.$exceptionHandler $exceptionHandler } - A mock implementation of the
73-
* angular service exception handler.
72+
* * {@link angular.mock.service.$exceptionHandler $exceptionHandler } - A mock implementation of
73+
* the angular service exception handler.
7474
* * {@link angular.mock.service.$log $log } - A mock implementation of the angular service log.
7575
*/
7676
angular.mock = {};
@@ -80,6 +80,24 @@ angular.mock = {};
8080
* @workInProgress
8181
* @ngdoc service
8282
* @name angular.mock.service.$browser
83+
*
84+
* @description
85+
* This service is a mock implementation of {@link angular.service.$browser}. It provides fake
86+
* implementation for commonly used browser apis that are hard to test, e.g. setTimeout, xhr,
87+
* cookies.
88+
*
89+
* This implementation is automatically available and replaces regular `$browser` service in tests
90+
* when `angular-mocks.js` is loaded.
91+
*
92+
* The api of this service is the same as the real {@link angular.service.$browser $browser}, except
93+
* that there are several helper methods available which can be used in tests.
94+
*
95+
* The following apis can be used in tests:
96+
*
97+
* - {@link angular.mock.service.$browser.xhr $browser.xhr} — enables testing of code that uses
98+
* the {@link angular.service.$xhr $xhr service} to make XmlHttpRequests.
99+
* - $browser.defer — enables testing of code that uses
100+
* {@link angular.service.$defer $defer service} for executing functions via the `setTimeout` api.
83101
*/
84102
function MockBrowser() {
85103
var self = this,
@@ -108,6 +126,33 @@ function MockBrowser() {
108126
};
109127

110128

129+
/**
130+
* @ngdoc function
131+
* @name angular.mock.service.$browser.xhr
132+
*
133+
* @description
134+
* Generic method for training browser to expect a request in a test and respond to it.
135+
*
136+
* See also convenience methods for browser training:
137+
*
138+
* - {@link angular.mock.service.$browser.xhr.expectGET $browser.xhr.expectGET}
139+
* - {@link angular.mock.service.$browser.xhr.expectPOST $browser.xhr.expectPOST}
140+
* - {@link angular.mock.service.$browser.xhr.expectPUT $browser.xhr.expectPUT}
141+
* - {@link angular.mock.service.$browser.xhr.expectDELETE $browser.xhr.expectDELETE}
142+
* - {@link angular.mock.service.$browser.xhr.expectJSON $browser.xhr.expectJSON}
143+
*
144+
* To flush pending requests in tests use
145+
* {@link angular.mock.service.$browser.xhr.flush $browser.xhr.flush}.
146+
*
147+
* @param {string} method Expected HTTP method.
148+
* @param {string} url Url path for which a request is expected.
149+
* @param {(object|string)=} data Expected body of the (POST) HTTP request.
150+
* @param {function(number, *)} callback Callback to call when response is flushed.
151+
* @param {object} headers Key-value pairs of expected headers.
152+
* @returns {object} Response configuration object. You can call its `respond()` method to
153+
* configure what should the browser mock return when the response is
154+
* {@link angular.mock.service.$browser.xhr.flush flushed}.
155+
*/
111156
self.xhr = function(method, url, data, callback, headers) {
112157
headers = headers || {};
113158
if (data && angular.isObject(data)) data = angular.toJson(data);
@@ -142,11 +187,85 @@ function MockBrowser() {
142187
}
143188
};
144189
};
190+
191+
/**
192+
* @ngdoc function
193+
* @name angular.mock.service.$browser.xhr.expectGET
194+
*
195+
* @description
196+
* Trains browser to expect a `GET` request and respond to it.
197+
*
198+
* @param {string} url Url path for which a request is expected.
199+
* @returns {object} Response configuration object. You can call its `respond()` method to
200+
* configure what should the browser mock return when the response is
201+
* {@link angular.mock.service.$browser.xhr.flush flushed}.
202+
*/
145203
self.xhr.expectGET = angular.bind(self, self.xhr.expect, 'GET');
204+
205+
/**
206+
* @ngdoc function
207+
* @name angular.mock.service.$browser.xhr.expectPOST
208+
*
209+
* @description
210+
* Trains browser to expect a `POST` request and respond to it.
211+
*
212+
* @param {string} url Url path for which a request is expected.
213+
* @returns {object} Response configuration object. You can call its `respond()` method to
214+
* configure what should the browser mock return when the response is
215+
* {@link angular.mock.service.$browser.xhr.flush flushed}.
216+
*/
146217
self.xhr.expectPOST = angular.bind(self, self.xhr.expect, 'POST');
218+
219+
/**
220+
* @ngdoc function
221+
* @name angular.mock.service.$browser.xhr.expectDELETE
222+
*
223+
* @description
224+
* Trains browser to expect a `DELETE` request and respond to it.
225+
*
226+
* @param {string} url Url path for which a request is expected.
227+
* @returns {object} Response configuration object. You can call its `respond()` method to
228+
* configure what should the browser mock return when the response is
229+
* {@link angular.mock.service.$browser.xhr.flush flushed}.
230+
*/
147231
self.xhr.expectDELETE = angular.bind(self, self.xhr.expect, 'DELETE');
232+
233+
/**
234+
* @ngdoc function
235+
* @name angular.mock.service.$browser.xhr.expectPUT
236+
*
237+
* @description
238+
* Trains browser to expect a `PUT` request and respond to it.
239+
*
240+
* @param {string} url Url path for which a request is expected.
241+
* @returns {object} Response configuration object. You can call its `respond()` method to
242+
* configure what should the browser mock return when the response is
243+
* {@link angular.mock.service.$browser.xhr.flush flushed}.
244+
*/
148245
self.xhr.expectPUT = angular.bind(self, self.xhr.expect, 'PUT');
246+
247+
/**
248+
* @ngdoc function
249+
* @name angular.mock.service.$browser.xhr.expectJSON
250+
*
251+
* @description
252+
* Trains browser to expect a `JSON` request and respond to it.
253+
*
254+
* @param {string} url Url path for which a request is expected.
255+
* @returns {object} Response configuration object. You can call its `respond()` method to
256+
* configure what should the browser mock return when the response is
257+
* {@link angular.mock.service.$browser.xhr.flush flushed}.
258+
*/
149259
self.xhr.expectJSON = angular.bind(self, self.xhr.expect, 'JSON');
260+
261+
/**
262+
* @ngdoc function
263+
* @name angular.mock.service.$browser.xhr.flush
264+
*
265+
* @description
266+
* Flushes all pending requests and executes xhr callbacks with the trained response as the
267+
* argument.
268+
*/
150269
self.xhr.flush = function() {
151270
if (requests.length == 0) {
152271
throw new Error("No xhr requests to be flushed!");

0 commit comments

Comments
 (0)