Skip to content

Commit 3cd8367

Browse files
DavertMikDavertMik
committed
updated docs
1 parent bc56101 commit 3cd8367

4 files changed

Lines changed: 147 additions & 20 deletions

File tree

‎docs/acceptance.md‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
# Acceptance Testing
22

3-
How does your client, manager, or tester, or any other non-technical person, know your web application is working? By opening the browser, accessing a site, clicking on links, filling in the forms, and actually seeing the content on a web page.
3+
How does your client, manager, or tester, or any other non-technical person, know your web application is working? By opening the browser, accessing a site, clicking on links, filling in the forms, and actually seeing the content on a web page.
44

55
Acceptance (also called End to End) tests can cover standard but complex scenarios from a user's perspective. With acceptance tests you can be confident that users, following all defined scenarios, won't get errors. We check **not just functionality of application but a user interface** (UI) as well.
66

7-
By default CodeceptJS uses [WebDriverIO](http://127.0.0.1:8000/helpers/WebDriverIO/) helper and **Selenium** to automate browser. Within web page you can locate elements, interact with them, and check that expected elements are present on a page. That is what a test look like.
7+
By default CodeceptJS uses [WebDriverIO](/helpers/WebDriverIO/) helper and **Selenium** to automate browser. Within web page you can locate elements, interact with them, and check that expected elements are present on a page.
8+
However, you can also choose [SeleniumWebdriver](/helpers/SeleniumWebdriver) or [Protractor](/helpers/Protractor) helpers, driven by corresponding libraries.
9+
No matter of helper and library you use for acceptance testing, CodeceptJS should execute same actions in similar manner.
10+
11+
That is what a test look like.
812

913
In case of CodeceptJS you can be sure that in code it will be as easy as it sounds. You just describe a test scenario with JavaScript DSL and allow the framework to handle the rest.
1014

@@ -20,16 +24,16 @@ This is how we can check that login form of a simple web application works. At f
2024

2125
## Locating Element
2226

23-
Element can be found by CSS or XPath locators. Practically every steps
24-
in WebDriverIO helper accept them both.
27+
Element can be found by CSS or XPath locators. Practically every steps
28+
in WebDriverIO helper accept them both.
2529

2630
```js
2731
I.seeElement('.user'); // element with CSS class user
2832
I.seeElement('//button(contains(., "press me")]'); // button
2933
```
3034

31-
By default CodeceptJS tries to guess the locator type.
32-
In order to specify exact locator type you can pass a hash called **strict locator**.
35+
By default CodeceptJS tries to guess the locator type.
36+
In order to specify exact locator type you can pass a hash called **strict locator**.
3337

3438
```js
3539
I.seeElement({css: 'div.user'});
@@ -72,9 +76,9 @@ In this case you are not limited to buttons and links. Any element found by that
7276

7377
```js
7478
// click element by CSS
75-
I.click('#signup');
79+
I.click('#signup');
7680
// click element located by name inside a form
77-
I.click({name: 'submit'}, '#user>form');
81+
I.click({name: 'submit'}, '#user>form');
7882
```
7983

8084
## Filling Fields
@@ -88,12 +92,12 @@ Let's submit this sample form for a test:
8892
<label for="user_name">Name</label>
8993
<input type="text" name="user[name]" id="user_name" />
9094
<label for="user_email">Email</label>
91-
<input type="text" name="user[email]" id="user_email" />
95+
<input type="text" name="user[email]" id="user_email" />
9296
<label for="user_gender">Gender</label>
9397
<select id="user_gender" name="user[gender]">
9498
<option value="m">Male</option>
9599
<option value="f">Female</option>
96-
</select>
100+
</select>
97101
<input type="submit" name="submitButton" value="Update" />
98102
</form>
99103
```
@@ -125,8 +129,8 @@ I.click('submitButton', '#update_form');
125129

126130
## Assertions
127131

128-
In order to verify the expected behavior of a web application, web page connects should be checked.
129-
CodeceptJS provides built-in assertions for that. They start with `see` (or `dontSee`) prefix, as they describe user's current vision.
132+
In order to verify the expected behavior of a web application, web page connects should be checked.
133+
CodeceptJS provides built-in assertions for that. They start with `see` (or `dontSee`) prefix, as they describe user's current vision.
130134

131135
The most general and common assertion is `see`:
132136

@@ -185,7 +189,7 @@ Scenario('use page title', function*(I) {
185189

186190
## Waiting
187191

188-
In modern web applications rendering is happen on client side.
192+
In modern web applications rendering is happen on client side.
189193
Sometimes that may cause delays. A test may fail while trying to click an element which has not appeared on a page yet.
190194
To handle this cases `wait*` methods introduced.
191195

‎docs/angular.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -262,4 +262,27 @@ Scenario('create todo item', (I) => {
262262

263263
To learn more about refactoring options in CodeceptJS read [PageObjects guide](http://codecept.io/pageobjects/).
264264

265-
### done()
265+
### Extending
266+
267+
What if CodeceptJS doesn't provide some of Protractor functionality you actually need? Sure its API is to general,
268+
and this case is possible. If you don't know how to do something with CodeceptJS - revert back to Protractor syntax!
269+
270+
Create custom helper, define methods for it, and use it inside the I object. Your Helper can access `browser` from Protractor
271+
by accessing Protractor helper:
272+
273+
```js
274+
let browser = this.helpers['Protractor'].browser;
275+
```
276+
277+
or use global `element` and `by` variables to locate elements:
278+
279+
```js
280+
element.all(by.repeater('result in memory'));
281+
```
282+
283+
This way we recommend to implement all custom logic using low-level Protractor syntax and using it inside scenario tests.
284+
Please see an [example of such helper](http://codecept.io/helpers/#protractor-example).
285+
286+
### done()
287+
288+
Almost ) This example is [available on GitHub](https://github.com/DavertMik/codeceptjs-angular-todomvc).

‎docs/helpers.md‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Every method should return a value in order to be appended into promise chain.
5151

5252
Next example demonstrates how to use WebDriverIO library to create your own test action.
5353
Method `seeAuthentication` will use `client` instance of WebDriverIO to get access to cookies.
54-
Standard NodeJS assertion library will be used.
54+
Standard NodeJS assertion library will be used (you can use any).
5555

5656
```js
5757
'use strict';
@@ -85,6 +85,36 @@ class MyHelper extends Helper {
8585
}
8686
```
8787

88+
## Protractor Example
89+
90+
```js
91+
'use strict';
92+
let Helper = codecept_helper;
93+
94+
// use any assertion library you like
95+
var chai = require('chai');
96+
var chaiAsPromised = require('chai-as-promised');
97+
chai.use(chaiAsPromised);
98+
var expect = chai.expect;
99+
100+
class MyHelper extends Helper {
101+
/**
102+
* checks that authentication cookie is set
103+
*/
104+
seeInHistory(historyPosition, value) {
105+
// access browser instance from Protractor helper
106+
this.helpers['Protractor'].browser.refresh();
107+
108+
// you can use `element` as well as in protractor
109+
var history = element.all(by.repeater('result in memory'));
110+
111+
// use chai as promised for better assertions
112+
// end your method with `return` to handle promises
113+
return expect(history.get(historyPosition).getText()).to.eventually.equal(value);
114+
}
115+
}
116+
```
117+
88118
## Initialization
89119

90120
Helpers can be configured in `codecept.json` and config values are passed into constructor.

‎docs/quickstart.md‎

Lines changed: 75 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,19 @@
11
# QuickStart
22

3-
**NodeJS v 4.2.0** and higher required to start.
3+
**NodeJS v 4.2.0** and higher required to start.
44
Install **CodeceptJS** with NPM:
55

6+
You can install it globally:
7+
68
```
7-
npm install -g codeceptjs
9+
[sudo] npm install -g codeceptjs
810
```
911

10-
(you may need `sudo` to do it).
12+
or locally
13+
14+
```
15+
npm install --save-dev codeceptjs
16+
```
1117

1218
## Setup
1319

@@ -19,14 +25,18 @@ codeceptjs init
1925

2026
It will create `codecept.json` config in current directory (or provide path in the first argument).
2127

22-
You will be asked for tests location (they will be searched in current dir by default).
28+
You will be asked for tests location (they will be searched in current dir by default).
2329

2430
On next step you are asked to select **Helpers**. Helpers include actions which can be used in tests.
2531
We recommend to start with **WebDriverIO** helper in order to write acceptance tests using webdriverio library and Selenium Server as test runner.
32+
If you want to test AngularJS application, use Protractor helper, or if you are more familiar with official Selenium Webdriver JS library, choose it.
33+
No matter what helper you've chosen they will be similar in use.
2634

2735
```
28-
? What helpers do you want to use?
36+
? What helpers do you want to use?
2937
❯◉ WebDriverIO
38+
◯ Protractor
39+
◯ SeleniumWebdriver
3040
◯ FileSystem
3141
```
3242

@@ -52,5 +62,65 @@ WebDriverIO helper will ask for additional configuration as well:
5262

5363
If you agree with defaults, finish the installation.
5464

65+
Depending on a helper you've chosen you will be asked to install corresponding package manually in the end of init.
66+
In case of webdriver you will need to run
67+
68+
```
69+
[sudo] npm install -g webdriverio
70+
```
71+
72+
for global installation. In case CodeceptJS is installed locally, webdriverio can be installed locally as well.
73+
In a similar way you may install `protractor` or `selenium-webdriver`.
74+
5575
## Creating First Test
5676

77+
Tests can be easily created by running
78+
79+
```bash
80+
codeceptjs gt
81+
```
82+
83+
*(or `generate test`)*
84+
85+
Provide a test name and open generated file in your favorite JavaScript editor (with ES6 support).
86+
87+
```js
88+
Feature('My First Test');
89+
90+
Scenario('test something', (I) => {
91+
92+
});
93+
```
94+
95+
Inside the scenario block you can write your first test scenario by using [actions from WebDriverIO helper](/helpers/WebDriverIO/). Let's assume we have a web server on `localhost` is running and there is a **Welcome** text on the first page. The simplest test will look like this:
96+
97+
```js
98+
Feature('My First Test');
99+
100+
Scenario('test something', (I) => {
101+
I.amOnPage('/');
102+
I.see('Welcome');
103+
});
104+
```
105+
106+
Before running this test we should ensure that [Selenium Web Server is running](/helpers/WebDriverIO/#selenium-installation). Then we can execute tests with
107+
108+
```bash
109+
codeceptjs run --steps
110+
```
111+
112+
*steps option will display test execution process in console*
113+
114+
If everything is done right, you will see in console:
115+
116+
```bash
117+
My First Test --
118+
test something
119+
• I am on page "/"
120+
• I see "Welcome"
121+
✓ OK
122+
```
123+
124+
## Congrats! Your first test is running.
125+
126+
Wasn't it hard, right?

0 commit comments

Comments
 (0)