kylefang/angular.js
1
0
Fork 0
mirror of https://github.com/zhigang1992/angular.js.git synced 2026-04-26 22:35:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(guide/unit-testing): improve unit testing guide

Browse Source 
This commit adds to the unit testing guide:

- an explicit section on additional libraries: Karma, Jasmine and
  angular-mocks and link to the docs for those projects too. Explain the
  benefit and use case for each of these libaries
- fully featured test examples and add more documentation
  around them, in particular the controller test
- a clear separation between the section on principles of testing
  and the actual tutorial on writing a test

Closes #8220
This commit is contained in:
Jack Franklin
2014-11-22 11:30:16 -08:00
committed by Brian Ford
parent aa01be8b2c
commit 3109342679
1 changed files with 216 additions and 223 deletions
Download Patch File Download Diff File Expand all files Collapse all files

439
docs/content/guide/unit-testing.ngdoc
View File

@@ -8,15 +8,15 @@ comes with almost no help from the compiler. For this reason we feel very strong
written in JavaScript needs to come with a strong set of tests. We have built many features into
Angular which makes testing your Angular applications easy. So there is no excuse for not testing.
# Separation of Concerns
## Separation of Concerns
Unit testing as the name implies is about testing individual units of code. Unit tests try to
Unit testing, as the name implies, is about testing individual units of code. Unit tests try to
answer questions such as "Did I think about the logic correctly?" or "Does the sort function order
the list in the right order?"
In order to answer such a question it is very important that we can isolate the unit of code under test.
That is because when we are testing the sort function we don't want to be forced into creating
related pieces such as the DOM elements, or making any XHR calls in getting the data to sort.
related pieces such as the DOM elements, or making any XHR calls to fetch the data to sort.
While this may seem obvious it can be very difficult to call an individual function on a
typical project. The reason is that the developers often mix concerns resulting in a
@@ -24,12 +24,10 @@ piece of code which does everything. It makes an XHR request, it sorts the respo
manipulates the DOM.
With Angular we try to make it easy for you to do the right thing, and so we
provide dependency injection for your XHR (which you can mock out) and we created abstractions which
allow you to sort your model without having to resort to manipulating the DOM. So that in the end,
it is easy to write a sort function which sorts some data, so that your test can create a data set,
apply the function, and assert that the resulting model is in the correct order. The test does not
have to wait for the XHR response to arrive, create the right kind of test DOM, nor assert that your
function has mutated the DOM in the right way.
provide dependency injection for your XHR requests, which can be mocked, and we provide abstractions which
allow you to test your model without having to resort to manipulating the DOM. The test can then
assert that the data has been sorted without having to create or look at the state of the DOM or
wait for any XHR requests to return data. The individual sort function can be tested in isolation.
## With great power comes great responsibility
@@ -38,230 +36,218 @@ We tried to make the right thing easy, but if you ignore these guidelines you ma
untestable application.
## Dependency Injection
There are several ways in which you can get a hold of a dependency. You can:
1. Create it using the `new` operator.
2. Look for it in a well-known place, also known as a global singleton.
3. Ask a registry (also known as service registry) for it. (But how do you get a hold of
the registry? Most likely by looking it up in a well known place. See #2.)
4. Expect it to be handed to you.
Out of the four options in the list above, only the last one is testable. Let's look at why:
Angular comes with {@link di dependency injection} built-in, which makes testing components much
easier, because you can pass in a component's dependencies and stub or mock them as you wish.
### Using the `new` operator
Components that have their dependencies injected allow them to be easily mocked on a test by
test basis, without having to mess with any global variables that could inadvertently affect
another test.
While there is nothing wrong with the `new` operator fundamentally, a problem arises when calling `new`
on a constructor. This permanently binds the call site to the type. For example, let's say that we try to
instantiate an `XHR` that will retrieve data from the server.
## Additional tools for testing Angular applications
For testing Angular applications there are certain tools that you should use that will make testing much
easier to set up and run.
### Karma
[Karma](http://karma-runner.github.io/) is a JavaScript command line tool that can be used to spawn
a web server which loads your application's source code and executes your tests. You can configure
Karma to run against a number of browsers, which is useful for being confident that your application
works on all browsers you need to support. Karma is executed on the command line and will display
the results of your tests on the command line once they have run in the browser.
Karma is a NodeJS application, and should be installed through npm. Full installation instructions
are available on [the Karma website](http://karma-runner.github.io/0.12/intro/installation.html).
### Jasmine
[Jasmine](http://jasmine.github.io/1.3/introduction.html) is a test driven development framework for
JavaScript that has become the most popular choice for testing Angular applications. Jasmine
provides functions to help with structuring your tests and also making assertions. As your tests
grow, keeping them well structured and documented is vital, and Jasmine helps achieve this.
In Jasmine we use the `describe` function to group our tests together:
```js
function MyClass() {
this.doWork = function() {
var xhr = new XHR();
xhr.open(method, url, true);
xhr.onreadystatechange = function() {...}
xhr.send();
}
}
describe("sorting the list of users", function() {
// individual tests go here
});
```
A problem surfaces in tests when we would like to instantiate a `MockXHR` that would
allow us to return fake data and simulate network failures. By calling `new XHR()` we are
permanently bound to the actual XHR and there is no way to replace it. Yes, we could monkey
patch, but that is a bad idea for many reasons which are outside the scope of this document.
Here's an example of how the class above becomes hard to test when resorting to monkey patching:
And then each individual test is defined within a call to the `it` function:
```js
var oldXHR = XHR;
XHR = function MockXHR() {};
var myClass = new MyClass();
myClass.doWork();
// assert that MockXHR got called with the right arguments
XHR = oldXHR; // if you forget this bad things will happen
describe('sorting the list of users', function() {
it('sorts in descending order by default', function() {
// your test assertion goes here
});
});
```
Grouping related tests within `describe` blocks and describing each individual test within an
`it` call keeps your tests self documenting.
### Global look-up:
Another way to approach the problem is to look for the service in a well-known location.
Finally, Jasmine provides matchers which let you make assertions:
```js
function MyClass() {
this.doWork = function() {
global.xhr({
method:'...',
url:'...',
complete:function(response){ ... }
})
}
}
describe('sorting the list of users', function() {
it('sorts in descending order by default', function() {
var users = ['jack', 'igor', 'jeff'];
var sorted = sortUsers(users);
expect(sorted).toEqual(['jeff', 'jack', 'igor']);
});
});
```
While no new dependency instance is created, it is fundamentally the same as `new` in
that no way exists to intercept the call to `global.xhr` for testing purposes, other than
through monkey patching. The basic issue for testing is that a global variable needs to be mutated in
order to replace it with call to a mock method. For further explanation of why this is bad see: [Brittle Global
State & Singletons](http://misko.hevery.com/code-reviewers-guide/flaw-brittle-global-state-singletons/)
Jasmine comes with a number of matchers that help you make a variety of assertions. You should [read
the Jasmine documentation](http://jasmine.github.io/1.3/introduction.html#section-Matchers) to see
what they are. To use Jasmine with Karma, we use the
[karma-jasmine](https://github.com/karma-runner/karma-jasmine) test runner.
The class above is hard to test since we have to change the global state:
### angular-mocks
Angular also provides the {@link ngMock} module, which provides mocking for your tests. This is used
to inject and mock Angular services within unit tests. In addition, it is able to extend other
modules so they are synchronous. Having tests synchronous keeps them much cleaner and easier to work
with. One of the most useful parts of ngMock is {@link ngMock.$httpBackend}, which lets us mock XHR
requests in tests, and return sample data instead.
## Testing a Controller
Because Angular separates logic from the view layer, it keeps controllers easy to test. Let's take a
look at how we might test the controller below, which provides `$scope.grade`, which sets a property
on the scope based on the length of the password.
```js
var oldXHR = global.xhr;
global.xhr = function mockXHR() {};
var myClass = new MyClass();
myClass.doWork();
// assert that mockXHR got called with the right arguments
global.xhr = oldXHR; // if you forget this bad things will happen
angular.module('app', [])
.controller('PasswordController', function PasswordController($scope) {
$scope.password = '';
$scope.grade = function() {
var size = $scope.password.length;
if (size > 8) {
$scope.strength = 'strong';
} else if (size > 3) {
$scope.strength = 'medium';
} else {
$scope.strength = 'weak';
}
};
});
```
### Service Registry:
It may seem that this can be solved by having a registry of all the services and then
having the tests replace the services as needed.
Because controllers are not available on the global scope, we need to use {@link
angular.mock.inject} to inject our controller first. The first step is to use the `module` function,
which is provided by angular-mocks. This loads in the module it's given, so it is available in your
tests. We pass this into `beforeEach`, which is a function Jasmine provides that lets us run code
before each test. Then we can use `inject` to access `$controller`, the service that is responsible
for instantiating controllers.
```js
function MyClass() {
var serviceRegistry = ????;
this.doWork = function() {
var xhr = serviceRegistry.get('xhr');
xhr({
method:'...',
url:'...',
complete:function(response){ ... }
})
}
describe('PasswordController', function() {
beforeEach(module('app'));
var $controller;
beforeEach(inject(function(_$controller_){
// The injector unwraps the underscores (_) from around the parameter names when matching
$controller = _$controller_;
}));
describe('$scope.grade', function() {
it('sets the strength to "strong" if the password length is >8 chars', function() {
var $scope = {};
var controller = $controller('PasswordController', { $scope: $scope });
$scope.password = 'longerthaneightchars';
$scope.grade();
expect($scope.strength).toEqual('strong');
});
});
});
```
However, where does the serviceRegistry come from? If it is:
* `new`-ed up, the test has no chance to reset the services for testing.
* a global look-up then the service returned is global as well (but resetting is easier, since
only one global variable exists to be reset).
The class above is hard to test since we have to change the global state:
Notice how by nesting the `describe` calls and being descriptive when calling them with strings, the
test is very clear. It documents exactly what it is testing, and at a glance you can quickly see
what is happening. Now let's add the test for when the password is less than three characters, which
should see `$scope.strength` set to "weak":
```js
var oldServiceLocator = global.serviceLocator;
global.serviceLocator.set('xhr', function mockXHR() {});
var myClass = new MyClass();
myClass.doWork();
// assert that mockXHR got called with the right arguments
global.serviceLocator = oldServiceLocator; // if you forget this bad things will happen
describe('PasswordController', function() {
beforeEach(module('app'));
var $controller;
beforeEach(inject(function(_$controller_){
// The injector unwraps the underscores (_) from around the parameter names when matching
$controller = _$controller_;
}));
describe('$scope.grade', function() {
it('sets the strength to "strong" if the password length is >8 chars', function() {
var $scope = {};
var controller = $controller('PasswordController', { $scope: $scope });
$scope.password = 'longerthaneightchars';
$scope.grade();
expect($scope.strength).toEqual('strong');
});
it('sets the strength to "weak" if the password length <3 chars', function() {
var $scope = {};
var controller = $controller('PasswordController', { $scope: $scope });
$scope.password = 'a';
$scope.grade();
expect($scope.strength).toEqual('weak');
});
});
});
```
### Passing in Dependencies:
Last, the dependency can be passed in.
Now we have two tests, but notice the duplication between the tests. Both have to
create the `$scope` variable and create the controller. As we add new tests, this duplication is
only going to get worse. Thankfully, Jasmine provides `beforeEach`, which lets us run a function
before each individual test. Let's see how that would tidy up our tests:
```js
function MyClass(xhr) {
this.doWork = function() {
xhr({
method:'...',
url:'...',
complete:function(response){ ... }
})
}
describe('PasswordController', function() {
beforeEach(module('app'));
var $controller;
beforeEach(inject(function(_$controller_){
// The injector unwraps the underscores (_) from around the parameter names when matching
$controller = _$controller_;
}));
describe('$scope.grade', function() {
var $scope, controller;
beforeEach(function() {
$scope = {};
controller = $controller('PasswordController', { $scope: $scope });
});
it('sets the strength to "strong" if the password length is >8 chars', function() {
$scope.password = 'longerthaneightchars';
$scope.grade();
expect($scope.strength).toEqual('strong');
});
it('sets the strength to "weak" if the password length <3 chars', function() {
$scope.password = 'a';
$scope.grade();
expect($scope.strength).toEqual('weak');
});
});
});
```
This is the preferred method since the code makes no assumptions about the origin of `xhr` and cares
instead about whoever created the class responsible for passing it in. Since the creator of the
class should be different code than the user of the class, it separates the responsibility of
creation from the logic. This is dependency-injection in a nutshell.
We've moved the duplication out and into the `beforeEach` block. Each individual test now
only contains the code specific to that test, and not code that is general across all tests. As you
expand your tests, keep an eye out for locations where you can use `beforeEach` to tidy up tests.
`beforeEach` isn't the only function of this sort that Jasmine provides, and the [documentation
lists the others](http://jasmine.github.io/1.3/introduction.html#section-Setup_and_Teardown).
The class above is testable, since in the test we can write:
```js
function xhrMock(args) {...}
var myClass = new MyClass(xhrMock);
myClass.doWork();
// assert that xhrMock got called with the right arguments
```
Notice that no global variables were harmed in the writing of this test.
Angular comes with {@link di dependency injection} built-in, making the right thing
easy to do, but you still need to do it if you wish to take advantage of the testability story.
## Controllers
What makes each application unique is its logic, and the logic is what we would like to test. If the logic
for your application contains DOM manipulation, it will be hard to test. See the example
below:
```js
function PasswordCtrl() {
// get references to DOM elements
var msg = $('.ex1 span');
var input = $('.ex1 input');
var strength;
this.grade = function() {
msg.removeClass(strength);
var pwd = input.val();
password.text(pwd);
if (pwd.length > 8) {
strength = 'strong';
} else if (pwd.length > 3) {
strength = 'medium';
} else {
strength = 'weak';
}
msg
.addClass(strength)
.text(strength);
}
}
```
The code above is problematic from a testability point of view since it requires your test to have the right kind
of DOM present when the code executes. The test would look like this:
```js
var input = $('<input type="text"/>');
var span = $('<span>');
$('body').html('<div class="ex1">')
.find('div')
.append(input)
.append(span);
var pc = new PasswordCtrl();
input.val('abc');
pc.grade();
expect(span.text()).toEqual('weak');
$('body').empty();
```
In angular the controllers are strictly separated from the DOM manipulation logic and this results in
a much easier testability story as the following example shows:
```js
function PasswordCtrl($scope) {
$scope.password = '';
$scope.grade = function() {
var size = $scope.password.length;
if (size > 8) {
$scope.strength = 'strong';
} else if (size > 3) {
$scope.strength = 'medium';
} else {
$scope.strength = 'weak';
}
};
}
```
and the test is straight forward:
```js
var $scope = {};
var pc = $controller('PasswordCtrl', { $scope: $scope });
$scope.password = 'abc';
$scope.grade();
expect($scope.strength).toEqual('weak');
```
Notice that the test is not only much shorter, it is also easier to follow what is happening. We say
that such a test tells a story, rather than asserting random bits which don't seem to be related.
## Filters
## Testing Filters
{@link ng.$filterProvider Filters} are functions which transform the data into a user readable
format. They are important because they remove the formatting responsibility from the application
logic, further simplifying the application logic.
@@ -273,12 +259,20 @@ myModule.filter('length', function() {
}
});
var length = $filter('length');
expect(length(null)).toEqual(0);
expect(length('abc')).toEqual(3);
describe('length filter', function() {
it('returns 0 when given null', function() {
var length = $filter('length');
expect(length(null)).toEqual(0);
});
it('returns the correct value when given a string of chars', function() {
var length = $filter('length');
expect(length('abc')).toEqual(3);
});
});
```
## Directives
## Testing Directives
Directives in angular are responsible for encapsulating complex functionality within custom HTML tags,
attributes, classes or comments. Unit tests are very important for directives because the components
you create with directives may be used throughout your application and in many different contexts.
@@ -309,28 +303,28 @@ verify this functionality. Note that the expression `{{1 + 1}}` times will also
```js
describe('Unit testing great quotes', function() {
var $compile;
var $rootScope;
var $compile,
$rootScope;
// Load the myApp module, which contains the directive
beforeEach(module('myApp'));
// Load the myApp module, which contains the directive
beforeEach(module('myApp'));
// Store references to $rootScope and $compile
// so they are available to all tests in this describe block
beforeEach(inject(function(_$compile_, _$rootScope_){
// The injector unwraps the underscores (_) from around the parameter names when matching
$compile = _$compile_;
$rootScope = _$rootScope_;
}));
// Store references to $rootScope and $compile
// so they are available to all tests in this describe block
beforeEach(inject(function(_$compile_, _$rootScope_){
// The injector unwraps the underscores (_) from around the parameter names when matching
$compile = _$compile_;
$rootScope = _$rootScope_;
}));
it('Replaces the element with the appropriate content', function() {
// Compile a piece of HTML containing the directive
var element = $compile("<a-great-eye></a-great-eye>")($rootScope);
// fire all the watches, so the scope expression {{1 + 1}} will be evaluated
$rootScope.$digest();
// Check that the compiled element contains the templated content
expect(element.html()).toContain("lidless, wreathed in flame, 2 times");
});
it('Replaces the element with the appropriate content', function() {
// Compile a piece of HTML containing the directive
var element = $compile("<a-great-eye></a-great-eye>")($rootScope);
// fire all the watches, so the scope expression {{1 + 1}} will be evaluated
$rootScope.$digest();
// Check that the compiled element contains the templated content
expect(element.html()).toContain("lidless, wreathed in flame, 2 times");
});
});
```
@@ -431,4 +425,3 @@ Otherwise you may run into issues if the test directory hierarchy differs from t
## Sample project
See the [angular-seed](https://github.com/angular/angular-seed) project for an example.