Installation & Usage

#Installation The proxy is available via npm and can be installed into your project by calling npm install http-backend-proxy or better yet, just add http-backend-proxy to devDependencies in your package.json file.

#Basic Usage To instantiate an instance of the proxy, require it and create a new instance:

var HttpBackend = require('http-backend-proxy');
var proxy = new HttpBackend(browser);

browser is, of course, the protractor browser object. A configuration object may be passed as a second argument to the constructor. Available configuration options are discussed where appropriate below.

#$httpBackend API The proxy supports the same basic interface as Angular's $httpBackend so start with its docs. Note that all proxied methods return promises in the fashion of most other Protractor methods except when buffering is turned on. (See Buffered Mode below.) Beyond the $httpBackend API, the proxy adds a few additional methods which are discussed in the following sections.

See the end-to-end tests in test/e2e for some examples of usage.

#Buffered Mode It is possible to use the proxy in a 'buffered' mode by adding buffer: true to the configuration object passed to proxy constructor. When buffering is enabled, proxied methods return void and do not immediately pass their calls through to the browser. Calling flush() will pass all buffered calls through to the browser at once and return a promise that will be fulfilled after all calls have been executed.

Buffering is the generally recommended approach because in most cases you will need to make numerous calls to the proxy to set things up the way you want them for a given spec. Buffering will reduce the number of remote calls and considerably speed up your test setup.

#Calling Functions and Sharing Data between Tests and Browser Using the proxy to configure $httpBackend for simple calls is, well, simple:

proxy.whenGET('/logoff').respond(200);

But what if I want to return some big piece of JSON? If we were coding our test in the browser we might write something like:

var searchResults = require('./mock-data/searchResults.json');
$httpBackend.whenGET('/search&q=beatles').respond(200, searchResults)

This too will work just fine as long as at the time you call respond() on the proxy, searchResults resolves to a JSON object (or anything you would expect to find in a JSON object: strings, numbers, regular expressions, arrays, etc.)

To get a little fancier, you can even do this:

proxy.when('GET', /.*/)
    .respond(function(method, url){return [200, 'You called: ' + url];});

The proxy will serialize the function and send it up to the browser for execution.

But what about:

var searchResults = require('./mock-data/searchResults.json');

function getQueryTermsFrom(url){  ... implementation omitted ... };

proxy.when('GET', /search\?q=.*/)
    .respond(function(method, url){
      var term = getQueryTermFrom(url);
      var fixedUpResponse = searchResults.replace(/__TERM__/, term);
      return [200, fixedUpResponse];
    });

Now we have a problem. The proxy can serialize the function just fine and send it to the browser, but when it gets there, getQueryTermFrom and searchResults are not going to resolve. This calls for...

##Using the Context Object The proxy provides a special object called the context object that is intended to help out in theses kinds of situations. The context object is a property of the proxy, called context oddly enough, the value of which will be synchronized between the proxy and the browser-side $httpBackend before any proxied calls are executed on the browser. With this object in place we can now do the following:

var searchResults = require('./mock-data/searchResults.json');

proxy.context = {
  searchResults: searchResults,
  getQueryTermsFrom: function (url){  ... implementation omitted ... };
}

proxy.when('GET', /search\?q=.*/)
    .respond(function(method, url){
      var term = $httpBackend.context.getQueryTermFrom(url);
      var fixedUpResponse = $httpBackend.context.searchResults.replace(/__TERM__/, term);
      return [200, fixedUpResponse];
    });

Hint: If we rename our in-test proxy from proxy to $httpBackend, our tests will more easily get through any linting we may have set up.

Two caveats to the above: First, the context is limited to the following data types: strings, numbers, booleans, null, regular expresions, dates, functions, and arrays and hashes (simple objects) that in turn contain only said types, including further arrays and/or hashes. Second, any functions defined on the context object (getQueryTermsFrom in our example) must themselves either be self-contained or only reference other functions and values on the context object (or available globally in the browser, but lets not go there...)

When buffering is turned off, the context object is synchronized with the browser before every call to respond(). When buffering is turned on, this synchronization occurs as part of the call to flush(). This is important, because it is the value of the context object at the time of synchronization, not at the point when respond() is called on the proxy, that determines its value in the browser. More precisely, since values in the context object may not even be evaluated in the browser until an HTTP call occurs, the value at the time of the HTTP call will be the value of the object as of the most recent prior synchronization. Said another way, there is no closure mechanism in play here. Because of this behavior, it is also possible to manually synchronized the context object at any time. See below for how and why you might want to do this.

##Configuring the Context Object If for some reason you don't like your context object being called 'context' (or more importantly, if 'context' should turn out to conflict with a future property of $httpBackend), it can be renamed by adding contextField: "a-new-field-name" to the configuration object that the proxy is constructed with. You can also disable the auto-synchronization of the context object described above by passing contextAutoSync: false. If you do, you will need to manually invoke synchronization.

##Manually Synchronizing Contexts The state of the context object can be synchronized manually at any time by calling proxy.syncContext(). This does not flush the buffer or otherwise send any new configuration to the remote $httpBackend instance. It simply synchronizes the state of the local and in-browser context objects. syncContext returns a promise.

Why do this? Consider the above example where we have a search URL whose return value is essentially defined as context.searchResults. If we can update the context in between tests, we can effectively cause search to return different results for each test. This makes it easy, for example, to test for correct behavior when some, none, and more-than-expected results are returned.

To avoid having to write this awkward code:

proxy.context = {
  searchResults: searchResults,
  getQueryTermsFrom: function (url){  ... implementation omitted ... };
}

proxy.when( ... );

... do some tests ...

proxy.context.searchResults = emptyResults;
proxy.syncContext();

... do some more tests ...

//rinse, wash, repeat...

you can pass the new context directly to syncContext like so:

proxy.syncContext({searchResults: emptyResults});

The above will merge the provided object with any existing context and synchronize the result. Merging allows you to avoid re-specifying the entire context object. Calling syncContext in this manner also updates the instance of the context object on the local proxy as well.

Note that the merge behavior only works if both the current and newly provided values are simple javascript objects. If either value is anything but, then simple assignment is used and the value passed to syncContext will completely replace the prior value. Examples of javascript objects that are not 'simple' and will not be merged are arrays, dates, regular expressions and pretty much anything created with the new keyword. Except for arrays and regular expressions, you shouldn't be using most of these anyway as they would never be returned from an HTTP call. The proxy would likely not correctly serialize them either.

Moreover, merging is only performed for the top-level object. Nested objects are treated atomically and simply replaced.

If any of this is confusing the syncContext unit tests may help clear it up and give detailed examples of the behavior.

#Configuring $httpBackend upon Page Load All of the above works great for setting up mock HTTP responses for calls that will be made in response to user interaction with a loaded page. But what about mocking data that your Angular application requests upon page load? The proxy supports doing this through its onLoad qualifier. Any configuration of the $httpBackend that needs to happen as part of the Angular applications initialization should be specified as follows:

proxy.onLoad.when(...).respond(...);

All calls to $httpBackend that are set up in this manner will be buffered and sent to the browser using Protractor's addMockModule capability. The proxy hooks into the browser.get() method such that when your tests call get(), the proxy gathers all calls made to onLoad... and wraps them in an Angular module that will execute them in its run() callback. The proxy also makes the current value of its context object available within the callback such that it can be reference in the same manner as with post-load calls.

Calls made using the onLoad qualifier are cumulative. For example:

proxy.onLoad.whenGET('/app-config').respond(...);
browser.get('index.html');
//The /app-config endpoint is configured as part of initializing the index.html page

... do some tests...

proxy.onLoad.whenGET('/user-prefs').respond(...);
browser.get('my-account.html');
//The /app-config and /user-prefs endpoints are both configured as part of initializing the my-accounts.html page

... more tests ...

When this is not desired, it is possible to reset the proxy's buffer of commands to send upon page load by calling proxy.onLoad.reset(). This also releases the hook into browser.get() which the proxy creates when a call is registered using onLoad. To ensure that tests using onLoad do not impact other tests, it is highly recommended that reset() be called as part of test clean-up for any tests that use onLoad. Further, protractor versions prior to 0.19.0 do not support the browser.removeMockModule() method which reset uses. Reset will silently fail to remove the module in this case. If you are using a protractor version prior to 0.19.0 you can invoke browser.clearMockModules() yourself and deal with the consequences, if any, of having all modules removed. For this reason, use of onLoad with earlier versions of Protractor is not recommended.

Note that the buffer used for calls against onLoad is separate from the buffer for calls made directly against the proxy (when buffering is enabled). Only the former buffer is resettable.

Again, looking at the tests should help clarify the proxy's onLoad behavior.

#Resetting the Mock The underlying $httpBackend mock does not support resetting the set of configured calls. So there is no way to do this through the proxy either. The simplest solution is to use browser.get() to reload your page. This of course resets the entire application state, not just that of the $httpBackend. Doing so may not seem ideal but if used wisely will give you good test isolation as well resetting the proxy. Alternately, you can use the techniques described under context synchronization above to modify the mock's behavior for each test.