From 1f842b1c63e0f00d64268ddc694ec63046aa38d4 Mon Sep 17 00:00:00 2001 From: Brian Ford Date: Tue, 25 Mar 2014 12:38:49 -0700 Subject: [PATCH] docs(guide/e2e-testing): improve formatting and clarity --- docs/content/guide/e2e-testing.ngdoc | 108 ++++++++++++++------------- 1 file changed, 58 insertions(+), 50 deletions(-) diff --git a/docs/content/guide/e2e-testing.ngdoc b/docs/content/guide/e2e-testing.ngdoc index 606759220..290d80b44 100644 --- a/docs/content/guide/e2e-testing.ngdoc +++ b/docs/content/guide/e2e-testing.ngdoc @@ -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).** - +
+**Note:** Angular Scenario Runner is depricated. If you're starting a new Angular project, +consider using [Protractor](https://github.com/angular/protractor). +
+# 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. @@ -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.