EVOLUTION-MANAGER

Edit File: $httpBackend.html

<a href='https://github.com/angular/angular.js/edit/v1.3.x/src/ngMock/angular-mocks.js?message=docs($httpBackend)%3A%20describe%20your%20change...#L898' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit">&nbsp;</i>Improve this Doc</a>

<a href='https://github.com/angular/angular.js/tree/v1.3.9/src/ngMock/angular-mocks.js#L898' class='view-source pull-right btn btn-primary'>
  <i class="glyphicon glyphicon-zoom-in">&nbsp;</i>View Source
</a>

<header class="api-profile-header">
  <h1 class="api-profile-header-heading">$httpBackend</h1>
  <ol class="api-profile-header-structure naked-list step-list">

<li>
      - service in module <a href="api/ngMock">ngMock</a>
    </li>
  </ol>
</header>

<div class="api-profile-description">
  <p>Fake HTTP backend implementation suitable for unit testing applications that use the
<a href="api/ng/service/$http">$http service</a>.</p>
<p><em>Note</em>: For fake HTTP backend implementation suitable for end-to-end testing or backend-less
development please see <a href="api/ngMockE2E/service/$httpBackend">e2e $httpBackend mock</a>.</p>
<p>During unit testing, we want our unit tests to run quickly and have no external dependencies so
we don’t want to send <a href="https://developer.mozilla.org/en/xmlhttprequest">XHR</a> or
<a href="http://en.wikipedia.org/wiki/JSONP">JSONP</a> requests to a real server. All we really need is
to verify whether a certain request has been sent or not, or alternatively just let the
application make requests, respond with pre-trained responses and assert that the end result is
what we expect it to be.</p>
<p>This mock implementation can be used to respond with static or dynamic responses via the
<code>expect</code> and <code>when</code> apis and their shortcuts (<code>expectGET</code>, <code>whenPOST</code>, etc).</p>
<p>When an Angular application needs some data from a server, it calls the $http service, which
sends the request to a real server using $httpBackend service. With dependency injection, it is
easy to inject $httpBackend mock (which has the same API as $httpBackend) and use it to verify
the requests and respond with some testing data without sending a request to a real server.</p>
<p>There are two ways to specify what test data should be returned as http responses by the mock
backend when the code under test makes http requests:</p>
<ul>
<li><code>$httpBackend.expect</code> - specifies a request expectation</li>
<li><code>$httpBackend.when</code> - specifies a backend definition</li>
</ul>
<h1 id="request-expectations-vs-backend-definitions">Request Expectations vs Backend Definitions</h1>
<p>Request expectations provide a way to make assertions about requests made by the application and
to define responses for those requests. The test will fail if the expected requests are not made
or they are made in the wrong order.</p>
<p>Backend definitions allow you to define a fake backend for your application which doesn&#39;t assert
if a particular request was made or not, it just returns a trained response if a request is made.
The test will pass whether or not the request gets made during testing.</p>
<table class="table">
  <tr><th width="220px"></th><th>Request expectations</th><th>Backend definitions</th></tr>
  <tr>
    <th>Syntax</th>
    <td>.expect(...).respond(...)</td>
    <td>.when(...).respond(...)</td>
  </tr>
  <tr>
    <th>Typical usage</th>
    <td>strict unit tests</td>
    <td>loose (black-box) unit testing</td>
  </tr>
  <tr>
    <th>Fulfills multiple requests</th>
    <td>NO</td>
    <td>YES</td>
  </tr>
  <tr>
    <th>Order of requests matters</th>
    <td>YES</td>
    <td>NO</td>
  </tr>
  <tr>
    <th>Request required</th>
    <td>YES</td>
    <td>NO</td>
  </tr>
  <tr>
    <th>Response required</th>
    <td>optional (see below)</td>
    <td>YES</td>
  </tr>
</table>

<p>In cases where both backend definitions and request expectations are specified during unit
testing, the request expectations are evaluated first.</p>
<p>If a request expectation has no response specified, the algorithm will search your backend
definitions for an appropriate response.</p>
<p>If a request didn&#39;t match any expectation or if the expectation doesn&#39;t have the response
defined, the backend definitions are evaluated in sequential order to see if any of them match
the request. The response from the first matched definition is returned.</p>
<h1 id="flushing-http-requests">Flushing HTTP requests</h1>
<p>The $httpBackend used in production always responds to requests asynchronously. If we preserved
this behavior in unit testing, we&#39;d have to create async unit tests, which are hard to write,
to follow and to maintain. But neither can the testing mock respond synchronously; that would
change the execution of the code under test. For this reason, the mock $httpBackend has a
<code>flush()</code> method, which allows the test to explicitly flush pending requests. This preserves
the async api of the backend, while allowing the test to execute synchronously.</p>
<h1 id="unit-testing-with-mock-httpbackend">Unit testing with mock $httpBackend</h1>
<p>The following code shows how to setup and use the mock backend when unit testing a controller.
First we create the controller under test:</p>
<pre><code class="lang-js">// The module code
angular
  .module(&#39;MyApp&#39;, [])
  .controller(&#39;MyController&#39;, MyController);

// The controller code
function MyController($scope, $http) {
  var authToken;

$http.get(&#39;/auth.py&#39;).success(function(data, status, headers) {
    authToken = headers(&#39;A-Token&#39;);
    $scope.user = data;
  });

$scope.saveMessage = function(message) {
    var headers = { &#39;Authorization&#39;: authToken };
    $scope.status = &#39;Saving...&#39;;

$http.post(&#39;/add-msg.py&#39;, message, { headers: headers } ).success(function(response) {
      $scope.status = &#39;&#39;;
    }).error(function() {
      $scope.status = &#39;ERROR!&#39;;
    });
  };
}
</code></pre>
<p>Now we setup the mock backend and create the test specs:</p>
<pre><code class="lang-js">// testing controller
describe(&#39;MyController&#39;, function() {
   var $httpBackend, $rootScope, createController, authRequestHandler;

// Set up the module
   beforeEach(module(&#39;MyApp&#39;));

beforeEach(inject(function($injector) {
     // Set up the mock http service responses
     $httpBackend = $injector.get(&#39;$httpBackend&#39;);
     // backend definition common for all tests
     authRequestHandler = $httpBackend.when(&#39;GET&#39;, &#39;/auth.py&#39;)
                            .respond({userId: &#39;userX&#39;}, {&#39;A-Token&#39;: &#39;xxx&#39;});

// Get hold of a scope (i.e. the root scope)
     $rootScope = $injector.get(&#39;$rootScope&#39;);
     // The $controller service is used to create instances of controllers
     var $controller = $injector.get(&#39;$controller&#39;);

createController = function() {
       return $controller(&#39;MyController&#39;, {&#39;$scope&#39; : $rootScope });
     };
   }));

afterEach(function() {
     $httpBackend.verifyNoOutstandingExpectation();
     $httpBackend.verifyNoOutstandingRequest();
   });

it(&#39;should fetch authentication token&#39;, function() {
     $httpBackend.expectGET(&#39;/auth.py&#39;);
     var controller = createController();
     $httpBackend.flush();
   });

it(&#39;should fail authentication&#39;, function() {

// Notice how you can change the response even after it was set
     authRequestHandler.respond(401, &#39;&#39;);

$httpBackend.expectGET(&#39;/auth.py&#39;);
     var controller = createController();
     $httpBackend.flush();
     expect($rootScope.status).toBe(&#39;Failed...&#39;);
   });

it(&#39;should send msg to server&#39;, function() {
     var controller = createController();
     $httpBackend.flush();

// now you don’t care about the authentication, but
     // the controller will still send the request and
     // $httpBackend will respond without you having to
     // specify the expectation and response for this request

$httpBackend.expectPOST(&#39;/add-msg.py&#39;, &#39;message content&#39;).respond(201, &#39;&#39;);
     $rootScope.saveMessage(&#39;message content&#39;);
     expect($rootScope.status).toBe(&#39;Saving...&#39;);
     $httpBackend.flush();
     expect($rootScope.status).toBe(&#39;&#39;);
   });

it(&#39;should send auth header&#39;, function() {
     var controller = createController();
     $httpBackend.flush();

$httpBackend.expectPOST(&#39;/add-msg.py&#39;, undefined, function(headers) {
       // check if the header was send, if it wasn&#39;t the expectation won&#39;t
       // match the request and the test will fail
       return headers[&#39;Authorization&#39;] == &#39;xxx&#39;;
     }).respond(201, &#39;&#39;);

$rootScope.saveMessage(&#39;whatever&#39;);
     $httpBackend.flush();
   });
});
</code></pre>

</div>

<div>

<h2>Methods</h2>
<ul class="methods">
  <li id="when">
    <h3><p><code>when(method, url, [data], [headers]);</code></p>

</h3>
    <div><p>Creates a new backend definition.</p>
</div>

<h4>Parameters</h4>
    
<table class="variables-matrix input-arguments">
  <thead>
    <tr>
      <th>Param</th>
      <th>Type</th>
      <th>Details</th>
    </tr>
  </thead>
  <tbody>
    
    <tr>
      <td>
        method
        
        
      </td>
      <td>
        <a href="" class="label type-hint type-hint-string">string</a>
      </td>
      <td>
        <p>HTTP method.</p>

</td>
    </tr>
    
    <tr>
      <td>
        url
        
        
      </td>
      <td>
        <a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-regexp">RegExp</a><a href="" class="label type-hint type-hint-function">function(string)</a>
      </td>
      <td>
        <p>HTTP url or function that receives the url
  and returns true if the url match the current definition.</p>

</td>
    </tr>
    
    <tr>
      <td>
        data
        
        <div><em>(optional)</em></div>
      </td>
      <td>
        <a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-regexp">RegExp</a><a href="" class="label type-hint type-hint-function">function(string)</a>
      </td>
      <td>
        <p>HTTP request body or function that receives
  data string and returns true if the data is as expected.</p>

</td>
    </tr>
    
    <tr>
      <td>
        headers
        
        <div><em>(optional)</em></div>
      </td>
      <td>
        <a href="" class="label type-hint type-hint-object">Object</a><a href="" class="label type-hint type-hint-function">function(Object)</a>
      </td>
      <td>
        <p>HTTP headers or function that receives http header
  object and returns true if the headers match the current definition.</p>