From c863514660fed43058c93b288cdf68d476a9cabc Mon Sep 17 00:00:00 2001 From: Di Peng Date: Mon, 27 Jun 2011 18:38:02 -0700 Subject: doc(angular.mock.service.$browser): add xhr docs --- src/angular-mocks.js | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 2 deletions(-) (limited to 'src/angular-mocks.js') diff --git a/src/angular-mocks.js b/src/angular-mocks.js index 0b5c35b5..3de04772 100644 --- a/src/angular-mocks.js +++ b/src/angular-mocks.js @@ -69,8 +69,8 @@ * Built-in mocks: * * * {@link angular.mock.service.$browser $browser } - A mock implementation of the browser. - * * {@link angular.mock.service.$exceptionHandler $exceptionHandler } - A mock implementation of the - * angular service exception handler. + * * {@link angular.mock.service.$exceptionHandler $exceptionHandler } - A mock implementation of + * the angular service exception handler. * * {@link angular.mock.service.$log $log } - A mock implementation of the angular service log. */ angular.mock = {}; @@ -80,6 +80,24 @@ angular.mock = {}; * @workInProgress * @ngdoc service * @name angular.mock.service.$browser + * + * @description + * This service is a mock implementation of {@link angular.service.$browser}. It provides fake + * implementation for commonly used browser apis that are hard to test, e.g. setTimeout, xhr, + * cookies. + * + * This implementation is automatically available and replaces regular `$browser` service in tests + * when `angular-mocks.js` is loaded. + * + * The api of this service is the same as the real {@link angular.service.$browser $browser}, except + * that there are several helper methods available which can be used in tests. + * + * The following apis can be used in tests: + * + * - {@link angular.mock.service.$browser.xhr $browser.xhr} — enables testing of code that uses + * the {@link angular.service.$xhr $xhr service} to make XmlHttpRequests. + * - $browser.defer — enables testing of code that uses + * {@link angular.service.$defer $defer service} for executing functions via the `setTimeout` api. */ function MockBrowser() { var self = this, @@ -108,6 +126,33 @@ function MockBrowser() { }; + /** + * @ngdoc function + * @name angular.mock.service.$browser.xhr + * + * @description + * Generic method for training browser to expect a request in a test and respond to it. + * + * See also convenience methods for browser training: + * + * - {@link angular.mock.service.$browser.xhr.expectGET $browser.xhr.expectGET} + * - {@link angular.mock.service.$browser.xhr.expectPOST $browser.xhr.expectPOST} + * - {@link angular.mock.service.$browser.xhr.expectPUT $browser.xhr.expectPUT} + * - {@link angular.mock.service.$browser.xhr.expectDELETE $browser.xhr.expectDELETE} + * - {@link angular.mock.service.$browser.xhr.expectJSON $browser.xhr.expectJSON} + * + * To flush pending requests in tests use + * {@link angular.mock.service.$browser.xhr.flush $browser.xhr.flush}. + * + * @param {string} method Expected HTTP method. + * @param {string} url Url path for which a request is expected. + * @param {(object|string)=} data Expected body of the (POST) HTTP request. + * @param {function(number, *)} callback Callback to call when response is flushed. + * @param {object} headers Key-value pairs of expected headers. + * @returns {object} Response configuration object. You can call its `respond()` method to + * configure what should the browser mock return when the response is + * {@link angular.mock.service.$browser.xhr.flush flushed}. + */ self.xhr = function(method, url, data, callback, headers) { headers = headers || {}; if (data && angular.isObject(data)) data = angular.toJson(data); @@ -142,11 +187,85 @@ function MockBrowser() { } }; }; + + /** + * @ngdoc function + * @name angular.mock.service.$browser.xhr.expectGET + * + * @description + * Trains browser to expect a `GET` request and respond to it. + * + * @param {string} url Url path for which a request is expected. + * @returns {object} Response configuration object. You can call its `respond()` method to + * configure what should the browser mock return when the response is + * {@link angular.mock.service.$browser.xhr.flush flushed}. + */ self.xhr.expectGET = angular.bind(self, self.xhr.expect, 'GET'); + + /** + * @ngdoc function + * @name angular.mock.service.$browser.xhr.expectPOST + * + * @description + * Trains browser to expect a `POST` request and respond to it. + * + * @param {string} url Url path for which a request is expected. + * @returns {object} Response configuration object. You can call its `respond()` method to + * configure what should the browser mock return when the response is + * {@link angular.mock.service.$browser.xhr.flush flushed}. + */ self.xhr.expectPOST = angular.bind(self, self.xhr.expect, 'POST'); + + /** + * @ngdoc function + * @name angular.mock.service.$browser.xhr.expectDELETE + * + * @description + * Trains browser to expect a `DELETE` request and respond to it. + * + * @param {string} url Url path for which a request is expected. + * @returns {object} Response configuration object. You can call its `respond()` method to + * configure what should the browser mock return when the response is + * {@link angular.mock.service.$browser.xhr.flush flushed}. + */ self.xhr.expectDELETE = angular.bind(self, self.xhr.expect, 'DELETE'); + + /** + * @ngdoc function + * @name angular.mock.service.$browser.xhr.expectPUT + * + * @description + * Trains browser to expect a `PUT` request and respond to it. + * + * @param {string} url Url path for which a request is expected. + * @returns {object} Response configuration object. You can call its `respond()` method to + * configure what should the browser mock return when the response is + * {@link angular.mock.service.$browser.xhr.flush flushed}. + */ self.xhr.expectPUT = angular.bind(self, self.xhr.expect, 'PUT'); + + /** + * @ngdoc function + * @name angular.mock.service.$browser.xhr.expectJSON + * + * @description + * Trains browser to expect a `JSON` request and respond to it. + * + * @param {string} url Url path for which a request is expected. + * @returns {object} Response configuration object. You can call its `respond()` method to + * configure what should the browser mock return when the response is + * {@link angular.mock.service.$browser.xhr.flush flushed}. + */ self.xhr.expectJSON = angular.bind(self, self.xhr.expect, 'JSON'); + + /** + * @ngdoc function + * @name angular.mock.service.$browser.xhr.flush + * + * @description + * Flushes all pending requests and executes xhr callbacks with the trained response as the + * argument. + */ self.xhr.flush = function() { if (requests.length == 0) { throw new Error("No xhr requests to be flushed!"); -- cgit v1.2.3