Skip to content

Commit 316c20b

Browse files
MargaritaLosevaMargaritaLoseva
committed
GS added
1 parent b37d237 commit 316c20b

File tree

3 files changed

+198
-3
lines changed

3 files changed

+198
-3
lines changed

‎docs/articles/documentation/getting-started/index.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
layout: docs
3+
title: Getting Started
4+
permalink: /documentation/getting-started/
5+
---
6+
# Getting Started
7+
8+
This guide will provide you with step-by-step instructions on how to create a functional web test with TestCafe.
9+
You will learn how to install TestCafe, write a test, run the test on multiple browsers and view test results.
10+
During creating a test, you will learn the basics of TestCafe API, advancing step by step, from the simple to more elaborate testing techniques.
11+
12+
All tests in this guide target a sample page available at [http://testcafe.devexpress.com/Example](http://testcafe.devexpress.com/Example). You can try running each of them against this page by yourself.
13+
14+
This topic contains the following sections.
15+
16+
* [Setting up Test Project](#setting-up-test-project)
17+
* [Installing TestCafe](#installing-testcafe)
18+
* [Writing Test](#writing-test)
19+
* [General Code Structure](#general-code-structure)
20+
* [Performing Actions on Page](#performing-actions-on-page)
21+
* [Assertions](#assertions)
22+
* [Dialog Handling](#dialog-handling)
23+
* [Authentication](#authentication)
24+
* [Running Test](#running-test)
25+
* [Viewing Test Results](#viewing-test-results)
26+
27+
## Setting up Test Project
28+
29+
A TestCafe project is just a file system directory that contains *test fixtures* - JavaScript files with tests.
30+
It is recommended to create this directory as a subdirectory of the project you are going to test.
31+
32+
This tutorial will demonstrate how to test not a developing project, but the published web page.
33+
To create tests for this page, create the *my-project* directory anywhere on your computer and the *tests* subdirectory in it.
34+
You can do this from a command line.
35+
36+
```bash
37+
mkdir -p my-project\tests
38+
```
39+
40+
## Installing TestCafe
41+
42+
Make sure that Node.js and npm are installed on your computer. Then go to the tested project directory (*my-project*) and run a single command:
43+
44+
```bash
45+
npm install --save-dev testcafe
46+
```
47+
48+
This will create the *node_modules* directory in your current directory (if the first one doesn't exist yet) and will download the TestCafe package to that directory.
49+
50+
## Writing Test
51+
52+
### General Code Structure
53+
54+
TestCafe organizes tests into fixtures. Test fixtures are JavaScript files that contain one or more tests for a single target URL.
55+
Therefore, you will usually have one test fixture per website page/route.
56+
57+
To create a test fixture, just create a .js file in the *tests* directory and add code to the file.
58+
59+
The following snippet illustrates basic elements of a TestCafe fixture:
60+
61+
* fixture declaration - is added by using the the `fixture` keyword;
62+
* target webpage - is specified by using the `page` function;
63+
* test code - is placed within the `test` function.
64+
65+
```js
66+
fixture `Fixture name`
67+
.page('http://testcafe.devexpress.com/Example');
68+
69+
test('Test 1 name', func t => {
70+
//Test 1 code
71+
});
72+
73+
test('Test 2 name', func t => {
74+
//Test 2 code
75+
});
76+
```
77+
78+
### Performing Actions on Page
79+
80+
Every test should be capable of interacting with a page content. To perform user actions, TestCafe provides a number of methods: `click`, `hover`, `typeText`, `upload`, etc.
81+
They can be called in a chain.
82+
83+
For example, the following fixture contains a simple test that types a developer name into a text editor and then clicks the Submit button.
84+
All test actions are implemented as functions of the test controller object `t`. This object is used to access test run API.
85+
86+
```js
87+
fixture `Getting Started - Test 1`
88+
.page('http://testcafe.devexpress.com/Example');
89+
90+
test('MyTest', async t => {
91+
await t
92+
.typeText('#Developer_Name', 'John Smith')
93+
.click('#submit-button');
94+
});
95+
```
96+
97+
For more information, see [Actions](../test-api/actions.md).
98+
99+
### Assertions
100+
101+
A functional test should also check the result of actions performed. For example, clicking the Submit button on the sample web page opens a "Thank you" page whose header addresses a user by the entered name.
102+
To check if the name is correct, you have to add an assertion to the test.
103+
104+
TestCafe allows you to use any assertion library to perform verifications. Before calling assertions, you need to install the assertion library into your tested project.
105+
106+
The following test demonstrates how to use an assertion from [Chai Assertion Library](http://chaijs.com/api/bdd/).
107+
Before running the test, install the assertion library: go to the tested project directory (*my-project*) and run `npm install chai`.
108+
109+
```js
110+
fixture `Getting Started - Test 2`
111+
.page('http://testcafe.devexpress.com/Example');
112+
113+
test('MyTest', async t => {
114+
await t
115+
.typeText('#Developer_Name', 'John Smith')
116+
.click('#submit-button');
117+
118+
expect(await t.eval( () => document.querySelector('#article-header').text )).to.equal('Thank You, John Smith!');
119+
};
120+
```
121+
122+
To check if the actual text is equal to the expected one, the `.equal(value)` assertion method is used.
123+
It is called within the special `t.eval` function provided by TestCafe. This function allows you to obtain the state of the element you verify on the client side.
124+
For more information, see [Executing Client Code](../test-api/executing-client-code.md).
125+
126+
### Dialog Handling
127+
128+
Note the Populate button on the sample page. This button fills the Developer Name text editor with a predefined name. Before it does so, a confirmation dialog is invoked. You must answer OK to proceed.
129+
To close this dialog from the test, you can use the special `handleConfirm` function. The following code snippet demonstrates how to do this.
130+
131+
```js
132+
fixture `Getting Started - Test 3`
133+
.page('http://testcafe.devexpress.com/Example');
134+
135+
test('MyTest', async t => {
136+
await t
137+
.click('.populate-form')
138+
.handleConfirm('OK')
139+
.click('#submit-button');
140+
141+
expect(await t.eval( () => document.querySelector('#article-header').text )).to.equal('Thank You, Peter Parker!');
142+
};
143+
```
144+
145+
Besides, TestCafe API provides special methods to handle other native dialogs such as alerts and prompts. For more information, see [Handling Native Dialog](../test-api/handling-native-dialogs.md).
146+
147+
### Authentication
148+
149+
At this step, you will see how TestCafe handles webpage authentication.
150+
151+
The subsequent test clicks the Authentication button that performs Http Basic authentication, opens a Personal Cabinet and checks whether the user name is correct. To provide the user credentials, the `httpAuth` function is used.
152+
153+
```js
154+
fixture `Getting Started - Test 4`
155+
.page('http://testcafe.devexpress.com/Example')
156+
.httpAuth('test', '1234');
157+
158+
test('MyTest', async t => {
159+
await t
160+
.click('.populate-form')
161+
.handleConfirm('OK')
162+
.click('.personal-cabinet-button');
163+
164+
expect(await t.eval( () => document.querySelector('.user-name').text )).to.equal('Peter Parker');
165+
};
166+
```
167+
168+
See [Http Authentication](../test-api/http-authentication.md) to learn more about authentication.
169+
170+
## Running Test
171+
172+
You can simply run tests from a command shell, by calling a single command where you specify target browsers and tests.
173+
174+
```bash
175+
testcafe ie,chrome my-project/tests/test1.js
176+
```
177+
178+
TestCafe will automatically open the chosen browsers and start test execution within them simultaneously.
179+
180+
You can run tests in [local browsers](../using-testcafe/command-line-interface.html#local-browsers) as well as on [remote devices](../using-testcafe/command-line-interface.html#remote-browsers) (including mobile phones and tablets).
181+
The only requirement for a device to run TestCafe tests is that it should have network access to the TestCafe application.
182+
183+
TestCafe provides a number of additional options for the `testcafe` command to configure test run.
184+
Among them, there are options that allow you to enable screenshot capturing, specify a reporter to generate reports, enable the quarantine mode, etc.
185+
For more information, see [Options](../using-testcafe/command-line-interface.md#options).
186+
187+
## Viewing Test Results
188+
189+
While a test is running, TestCafe is gathering information about the test run and outputing it right into a command shell. After the test run has finished, you can view a complete report there.
190+
191+
IMAGE
192+
193+
If errors occurred during test run, a report includes detailed information about them. Fancy call sites, clean stacks and screenshots will help you easily detect the cause of an error.
194+
195+
Test reports are generated by TestCafe [reporters](../using-testcafe/common-concepts/reporters.md). By default, the spec reporter is used, but you can select any other built-in reporter or create and use your own custom reporter.

‎docs/articles/documentation/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ inMainMenu: true
66
---
77
# Documentation
88

9-
* [Getting Started](.)
9+
* [Getting Started](getting-started/index.md)
1010
* [Test API](.)
1111
* [Using TestCafe](using-testcafe/index.md)
12-
* [Extending TestCafe](.)
12+
* [Extending TestCafe](extending-testcafe/index.md)
1313
* [Recipes](.)

‎docs/nav/nav-menu.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
- item: GETTING STARTED
2-
url: .
2+
url: /testcafe/documentation/getting-started/
33
- folder: TEST API
44
url: /testcafe/documentation/test-api/
55
content:

0 commit comments

Comments
 (0)