mirror of
https://github.com/zhigang1992/angular.js.git
synced 2026-04-24 03:55:49 +08:00
docs(guide/e2e-testing): improve formatting and clarity
This commit is contained in:
@@ -3,10 +3,12 @@
|
||||
@name E2E Testing
|
||||
@description
|
||||
|
||||
**Angular Scenario Runner is in maintenance mode - If you're starting a new Angular project,
|
||||
consider using [Protractor](https://github.com/angular/protractor).**
|
||||
|
||||
<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).
|
||||
</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.
|
||||
@@ -14,16 +16,22 @@ verify the correctness of new features, catch bugs and notice regressions.
|
||||
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.
|
||||
|
||||
# Overview
|
||||
## Overview
|
||||
|
||||
You write scenario tests in JavaScript. These tests describe how your application should behave
|
||||
given a certain interaction in a specific state. A scenario is comprised of one or more `it` blocks
|
||||
(you can think of these as the requirements of your application), which in turn 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), and expectations tell the Runner to assert
|
||||
something about the state (such as the value of a field or the current URL). If any expectation
|
||||
fails, the runner marks the `it` as "failed" and continues on to the next one. Scenarios may also
|
||||
have **beforeEach** and **afterEach** blocks, which will be run before (or after) each `it` block,
|
||||
regardless of whether they pass or fail.
|
||||
given a certain interaction in a specific state.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
each `it` block regardless of whether the block passes or fails.
|
||||
|
||||
<img src="img/guide/scenario_runner.png">
|
||||
|
||||
@@ -54,136 +62,136 @@ the only button on the page, and then it verifies that there are 10 items listed
|
||||
|
||||
The API section below lists the available commands and expectations for the Runner.
|
||||
|
||||
# API
|
||||
## API
|
||||
Source: https://github.com/angular/angular.js/blob/master/src/ngScenario/dsl.js
|
||||
|
||||
## pause()
|
||||
### `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)
|
||||
### `sleep(seconds)`
|
||||
Pauses the execution of the tests for the specified number of `seconds`.
|
||||
|
||||
## browser().navigateTo(url)
|
||||
### `browser().navigateTo(url)`
|
||||
Loads the `url` into the test frame.
|
||||
|
||||
## browser().navigateTo(url, fn)
|
||||
### `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()
|
||||
### `browser().reload()`
|
||||
Refreshes the currently loaded page in the test frame.
|
||||
|
||||
## browser().window().href()
|
||||
### `browser().window().href()`
|
||||
Returns the window.location.href of the currently loaded page in the test frame.
|
||||
|
||||
## browser().window().path()
|
||||
### `browser().window().path()`
|
||||
Returns the window.location.pathname of the currently loaded page in the test frame.
|
||||
|
||||
## browser().window().search()
|
||||
### `browser().window().search()`
|
||||
Returns the window.location.search of the currently loaded page in the test frame.
|
||||
|
||||
## browser().window().hash()
|
||||
### `browser().window().hash()`
|
||||
Returns the window.location.hash (without `#`) of the currently loaded page in the test frame.
|
||||
|
||||
## browser().location().url()
|
||||
### `browser().location().url()`
|
||||
Returns the {@link ng.$location $location.url()} of the currently loaded page in
|
||||
the test frame.
|
||||
|
||||
## browser().location().path()
|
||||
### `browser().location().path()`
|
||||
Returns the {@link ng.$location $location.path()} of the currently loaded page in
|
||||
the test frame.
|
||||
|
||||
## browser().location().search()
|
||||
### `browser().location().search()`
|
||||
Returns the {@link ng.$location $location.search()} of the currently loaded page
|
||||
in the test frame.
|
||||
|
||||
## browser().location().hash()
|
||||
### `browser().location().hash()`
|
||||
Returns the {@link ng.$location $location.hash()} of the currently loaded page in
|
||||
the test frame.
|
||||
|
||||
## expect(future).{matcher}
|
||||
### `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}
|
||||
### `expect(future).not().{matcher}`
|
||||
Asserts the value of the given `future` satisfies the negation of the `matcher`.
|
||||
|
||||
## using(selector, label)
|
||||
### `using(selector, label)`
|
||||
Scopes the next DSL element selection.
|
||||
|
||||
## binding(name)
|
||||
### `binding(name)`
|
||||
Returns the value of the first binding matching the given `name`.
|
||||
|
||||
## input(name).enter(value)
|
||||
### `input(name).enter(value)`
|
||||
Enters the given `value` in the text field with the corresponding ng-model `name`.
|
||||
|
||||
## input(name).check()
|
||||
### `input(name).check()`
|
||||
Checks/unchecks the checkbox with the corresponding ng-model `name`.
|
||||
|
||||
## input(name).select(value)
|
||||
### `input(name).select(value)`
|
||||
Selects the given `value` in the radio button with the corresponding ng-model `name`.
|
||||
|
||||
## input(name).val()
|
||||
### `input(name).val()`
|
||||
Returns the current value of an input field with the corresponding ng-model `name`.
|
||||
|
||||
## repeater(selector, label).count()
|
||||
### `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)
|
||||
### `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)
|
||||
### `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)
|
||||
### `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...)
|
||||
### `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()
|
||||
### `element(selector, label).count()`
|
||||
Returns the number of elements that match the given jQuery `selector`. The `label` is used for test
|
||||
output.
|
||||
|
||||
## element(selector, label).click()
|
||||
### `element(selector, label).click()`
|
||||
Clicks on the element matching the given jQuery `selector`. The `label` is used for test output.
|
||||
|
||||
## element(selector, label).query(fn)
|
||||
### `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.
|
||||
|
||||
## element(selector, label).{method}()
|
||||
### `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.
|
||||
|
||||
## element(selector, label).{method}(value)
|
||||
### `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.
|
||||
|
||||
## element(selector, label).{method}(key)
|
||||
### `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)
|
||||
### `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
|
||||
|
||||
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')`.
|
||||
@@ -221,10 +229,10 @@ expect(value).toBeLessThan(expected)
|
||||
expect(value).toBeGreaterThan(expected)
|
||||
```
|
||||
|
||||
# Example
|
||||
## Example
|
||||
See the [angular-seed](https://github.com/angular/angular-seed) project for more examples.
|
||||
|
||||
## Conditional actions with element(...).query(fn)
|
||||
### 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
|
||||
@@ -308,6 +316,6 @@ element('.btn-danger').click();
|
||||
element('.btn-danger').click();
|
||||
```
|
||||
|
||||
# Caveats
|
||||
## Caveats
|
||||
|
||||
`ngScenario` does not work with apps that manually bootstrap using `angular.bootstrap`. You must use the `ng-app` directive.
|
||||
|
||||
Reference in New Issue
Block a user