Skip to content

Commit

Permalink
docs(e2e-testing): deprecate ng-scenario and update E2E testing doc t…
Browse files Browse the repository at this point in the history 
…o discuss protractor
  • Loading branch information
@juliemr
juliemr committed Apr 9, 2014
1 parent 879b0bc commit acfcbdf
Showing 1 changed file with 49 additions and 285 deletions.
334 changes: 49 additions & 285 deletions docs/content/guide/e2e-testing.ngdoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,319 +3,83 @@
@name E2E Testing
@description

# E2E Testing

<div class="alert alert-danger">
**Note:** Angular Scenario Runner is depricated. If you're starting a new Angular project,
consider using [Protractor](https://github.com/angular/protractor).
**Note:** In the past, end to end testing could be done with a deprecated tool called
[Angular Scenario Runner](http://code.angularjs.org/1.2.16/docs/guide/e2e-testing). That tool
is now in maintenance mode.
</div>

# E2E Testing with the Angular Scenario Runner

As applications grow in size and complexity, it becomes unrealistic to rely on manual testing to
verify the correctness of new features, catch bugs and notice regressions.
verify the correctness of new features, catch bugs and notice regressions. End to end tests
are the first line of defense for catching bugs, but sometimes issues come up with integration
between components which can't be captured in a unit test. End to end tests are made to find
these problems.

We have built [Protractor](https://github.com/angular/protractor), an end
to end test runner which simulates user interactions that will help you verify the health of your
Angular application.

To solve this problem, we have built an Angular Scenario Runner which simulates user interactions
that will help you verify the health of your Angular application.
## Using Protractor

## Overview
Protractor is a [Node.js](http://nodejs.org) program, and runs end to end tests that are also
written in JavaScript and run with node. Protractor uses [WebDriver](https://code.google.com/p/selenium/wiki/GettingStarted)
to control browsers and simulate user actions.

You write scenario tests in JavaScript. These tests describe how your application should behave
given a certain interaction in a specific state.
For more information on Protractor, view [getting started](https://github.com/angular/protractor/blob/master/docs/getting-started.md)
or the [api docs](https://github.com/angular/protractor/blob/master/docs/api.md).

A scenario is comprised of one or more `it` blocks that describe the requirements of your
application. `it` blocks are made of **commands** and **expectations**. Commands tell the Runner
to do something with the application such as navigate to a page or click on a button. Expectations
tell the Runner to assert something about the application's state, such as the value of a field or
the current URL.
Protractor uses [Jasmine](http://jasmine.github.io/1.3/introduction.html) for its test syntax.
As in unit testing, a test file is comprised of one or
more `it` blocks that describe the requirements of your application. `it` blocks are made of
**commands** and **expectations**. Commands tell Protractor to do something with the application
such as navigate to a page or click on a button. Expectations tell Protractor to assert something
about the application's state, such as the value of a field or the current URL.

If any expectation within an `it` block fails, the runner marks the `it` as "failed" and continues
on to the next block.

Scenarios may also have `beforeEach` and `afterEach` blocks, which will be run before or after
Test files may also have `beforeEach` and `afterEach` blocks, which will be run before or after
each `it` block regardless of whether the block passes or fails.

<img src="img/guide/scenario_runner.png">

In addition to the above elements, scenarios may also contain helper functions to avoid duplicating
In addition to the above elements, tests may also contain helper functions to avoid duplicating
code in the `it` blocks.

Here is an example of a simple scenario:
Here is an example of a simple test:
```js
describe('Buzz Client', function() {
it('should filter results', function() {
input('user').enter('jacksparrow');
element(':button').click();
expect(repeater('ul li').count()).toEqual(10);
input('filterText').enter('Bees');
expect(repeater('ul li').count()).toEqual(1);
});
});
```

Note that
[`input('user')`](https://github.com/angular/angular.js/blob/master/docs/content/guide/dev_guide.e2e-testing.ngdoc#L119)
finds the `<input>` element with `ng-model="user"` not `name="user"`.

This scenario describes the requirements of a Buzz Client, specifically, that it should be able to
filter the stream of the user. It starts by entering a value in the input field with ng-model="user", clicking
the only button on the page, and then it verifies that there are 10 items listed. It then enters
'Bees' in the input field with ng-model='filterText' and verifies that the list is reduced to a single item.

The API section below lists the available commands and expectations for the Runner.

## API
Source: https://github.com/angular/angular.js/blob/master/src/ngScenario/dsl.js

### `pause()`
Pauses the execution of the tests until you call `resume()` in the console (or click the resume
link in the Runner UI).

### `sleep(seconds)`
Pauses the execution of the tests for the specified number of `seconds`.

### `browser().navigateTo(url)`
Loads the `url` into the test frame.

### `browser().navigateTo(url, fn)`
Loads the URL returned by `fn` into the testing frame. The given `url` is only used for the test
output. Use this when the destination URL is dynamic (that is, the destination is unknown when you
write the test).

### `browser().reload()`
Refreshes the currently loaded page in the test frame.

### `browser().window().href()`
Returns the window.location.href of the currently loaded page in the test frame.

### `browser().window().path()`
Returns the window.location.pathname of the currently loaded page in the test frame.

### `browser().window().search()`
Returns the window.location.search of the currently loaded page in the test frame.

### `browser().window().hash()`
Returns the window.location.hash (without `#`) of the currently loaded page in the test frame.

### `browser().location().url()`
Returns the {@link ng.$location $location.url()} of the currently loaded page in
the test frame.

### `browser().location().path()`
Returns the {@link ng.$location $location.path()} of the currently loaded page in
the test frame.

### `browser().location().search()`
Returns the {@link ng.$location $location.search()} of the currently loaded page
in the test frame.

### `browser().location().hash()`
Returns the {@link ng.$location $location.hash()} of the currently loaded page in
the test frame.

### `expect(future).{matcher}`
Asserts the value of the given `future` satisfies the `matcher`. All API statements return a
`future` object, which get a `value` assigned after they are executed. Matchers are defined using
`angular.scenario.matcher`, and they use the value of futures to run the expectation. For example:
`expect(browser().location().href()).toEqual('http://www.google.com')`. Available matchers
are presented further down this document.

### `expect(future).not().{matcher}`
Asserts the value of the given `future` satisfies the negation of the `matcher`.

### `using(selector, label)`
Scopes the next DSL element selection.

### `binding(name)`
Returns the value of the first binding matching the given `name`.

### `input(name).enter(value)`
Enters the given `value` in the text field with the corresponding ng-model `name`.

### `input(name).check()`
Checks/unchecks the checkbox with the corresponding ng-model `name`.

### `input(name).select(value)`
Selects the given `value` in the radio button with the corresponding ng-model `name`.

### `input(name).val()`
Returns the current value of an input field with the corresponding ng-model `name`.

### `repeater(selector, label).count()`
Returns the number of rows in the repeater matching the given jQuery `selector`. The `label` is
used for test output.

### `repeater(selector, label).row(index)`
Returns an array with the bindings in the row at the given `index` in the repeater matching the
given jQuery `selector`. The `label` is used for test output.

### `repeater(selector, label).column(binding)`
Returns an array with the values in the column with the given `binding` in the repeater matching
the given jQuery `selector`. The `label` is used for test output.

### `select(name).option(value)`
Picks the option with the given `value` on the select with the given ng-model `name`.

### `select(name).options(value1, value2...)`
Picks the options with the given `values` on the multi select with the given ng-model `name`.

### `element(selector, label).count()`
Returns the number of elements that match the given jQuery `selector`. The `label` is used for test
output.
describe('TODO list', function() {
it('should filter results', function() {

### `element(selector, label).click()`
Clicks on the element matching the given jQuery `selector`. The `label` is used for test output.
// Find the element with ng-model="user" and type "jacksparrow" into it
element(by.model('user')).sendKeys('jacksparrow');

### `element(selector, label).query(fn)`
Executes the function `fn(selectedElements, done)`, where selectedElements are the elements that
match the given jQuery `selector` and `done` is a function that is called at the end of the `fn`
function. The `label` is used for test output.
// Find the first (and only) button on the page and click it
element(by.css(':button')).click();

### `element(selector, label).{method}()`
Returns the result of calling `method` on the element matching the given jQuery `selector`, where
`method` can be any of the following jQuery methods: `val`, `text`, `html`, `height`,
`innerHeight`, `outerHeight`, `width`, `innerWidth`, `outerWidth`, `position`, `scrollLeft`,
`scrollTop`, `offset`. The `label` is used for test output.
// Verify that there are 10 tasks
expect(element.all(by.repeater('task in tasks')).count()).toEqual(10);

### `element(selector, label).{method}(value)`
Executes the `method` passing in `value` on the element matching the given jQuery `selector`, where
`method` can be any of the following jQuery methods: `val`, `text`, `html`, `height`,
`innerHeight`, `outerHeight`, `width`, `innerWidth`, `outerWidth`, `position`, `scrollLeft`,
`scrollTop`, `offset`. The `label` is used for test output.
// Enter 'groceries' into the element with ng-model="filterText"
element(by.model('filterText')).sendKeys('groceries');

### `element(selector, label).{method}(key)`
Returns the result of calling `method` passing in `key` on the element matching the given jQuery
`selector`, where `method` can be any of the following jQuery methods: `attr`, `prop`, `css`. The
`label` is used for test output.

### `element(selector, label).{method}(key, value)`
Executes the `method` passing in `key` and `value` on the element matching the given jQuery
`selector`, where `method` can be any of the following jQuery methods: `attr`, `prop`, `css`. The
`label` is used for test output.

## Matchers

Matchers are used in combination with the `expect(...)` function as described above and can
be negated with `not()`. For instance: `expect(element('h1').text()).not().toEqual('Error')`.

Source: https://github.com/angular/angular.js/blob/master/src/ngScenario/matchers.js

```js
// value and Object comparison following the rules of angular.equals().
expect(value).toEqual(value)

// a simpler value comparison using ===
expect(value).toBe(value)

// checks that the value is defined by checking its type.
expect(value).toBeDefined()

// the following two matchers are using JavaScript's standard truthiness rules
expect(value).toBeTruthy()
expect(value).toBeFalsy()

// verify that the value matches the given regular expression. The regular
// expression may be passed in form of a string or a regular expression
// object.
expect(value).toMatch(expectedRegExp)

// a check for null using ===
expect(value).toBeNull()

// Array.indexOf(...) is used internally to check whether the element is
// contained within the array.
expect(value).toContain(expected)

// number comparison using < and >
expect(value).toBeLessThan(expected)
expect(value).toBeGreaterThan(expected)
```

## Example
See the [angular-seed](https://github.com/angular/angular-seed) project for more examples.

### Conditional actions with element(...).query(fn)

E2E testing with angular scenario is highly asynchronous and hides a lot of complexity by
queueing actions and expectations that can handle futures. From time to time, you might need
conditional assertions or element selection. Even though you should generally try to avoid this
(as it is can be sign for unstable tests), you can add conditional behavior with
`element(...).query(fn)`. The following code listing shows how this function can be used to delete
added entries (where an entry is some domain object) using the application's web interface.

Imagine the application to be structured into two views:

1. *Overview view* which lists all the added entries in a table and
2. a *detail view* which shows the entries' details and contains a delete button. When clicking the
delete button, the user is redirected back to the *overview page*.

```js
beforeEach(function () {
var deleteEntry = function () {
browser().navigateTo('/entries');

// we need to select the <tbody> element as it might be the case that there
// are no entries (and therefore no rows). When the selector does not
// result in a match, the test would be marked as a failure.
element('table tbody').query(function (tbody, done) {
// ngScenario gives us a jQuery lite wrapped element. We call the
// `children()` function to retrieve the table body's rows
var children = tbody.children();

if (children.length > 0) {
// if there is at least one entry in the table, click on the link to
// the entry's detail view
element('table tbody a').click();
// and, after a route change, click the delete button
element('.btn-danger').click();
}

// if there is more than one entry shown in the table, queue another
// delete action.
if (children.length > 1) {
deleteEntry();
}

// remember to call `done()` so that ngScenario can continue
// test execution.
done();
});

};

// start deleting entries
deleteEntry();
// Verify that now there is only one item in the task list
expect(element.all(by.repeater('task in tasks')).count()).toEqual(1);
});
});
```

In order to understand what is happening, we should emphasize that ngScenario calls are not
immediately executed, but queued (in ngScenario terms, we would be talking about adding
future actions). If we had only one entry in our table, then the following future actions
would be queued:

```js
// delete entry 1
browser().navigateTo('/entries');
element('table tbody').query(function (tbody, done) { ... });
element('table tbody a');
element('.btn-danger').click();
```

For two entries, ngScenario would have to work on the following queue:
This test describes the requirements of a ToDo list, specifically, that it should be able to
filter the list of items.

```js
// delete entry 1
browser().navigateTo('/entries');
element('table tbody').query(function (tbody, done) { ... });
element('table tbody a');
element('.btn-danger').click();

// delete entry 2
// indented to represent "recursion depth"
browser().navigateTo('/entries');
element('table tbody').query(function (tbody, done) { ... });
element('table tbody a');
element('.btn-danger').click();
```
## Example
See the [angular-seed](https://github.com/angular/angular-seed) project for more examples, or look
at the embedded examples in the Angular documentation (For example, [$http](http://docs.angularjs.org/api/ng/service/$http)
has an end to end test in the example under the `protractor.js` tag).

## Caveats

`ngScenario` does not work with apps that manually bootstrap using `angular.bootstrap`. You must use the `ng-app` directive.
Protractor does not work out-of-the-box with apps that manually bootstrap manually using
`angular.bootstrap`. You must use the `ng-app` directive.

0 comments on commit acfcbdf

Please sign in to comment.