Skip to content

Commit

Permalink
Update test-code-structure.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@dirk-pieterse
dirk-pieterse authored May 10, 2018
1 parent 8c2964f commit 3d8d0ea
Showing 1 changed file with 35 additions and 38 deletions.
73 changes: 35 additions & 38 deletions docs/articles/documentation/test-api/test-code-structure.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,13 +42,13 @@ Parameter | Type | Description
------------- | ------ | ------------------------
`fixtureName` | String | The name of the fixture.

This function returns the `fixture` object that allows you to configure the fixture - specify the [start webpage](#specifying-the-start-webpage), [metadata](#specifying-testing-metadata) and [initialization and clean-up code](#initialization-and-clean-up) for tests included to the fixture.
This function returns the `fixture` object that allows you to configure the fixture - specify the [start webpage](#specifying-the-start-webpage), [metadata](#specifying-testing-metadata) and [initialization and clean-up code](#initialization-and-clean-up) for tests included in the fixture.

> [Tests](#tests) that constitute a fixture go after this declaration.
## Tests

To introduce a test, call the `test` function and pass test code inside.
To introduce a test, call the `test` function and pass the test code inside it.

```text
test( testName, fn(t) )
Expand All @@ -57,8 +57,8 @@ test( testName, fn(t) )
Parameter | Type | Description
---------- | -------- | --------------------------------------------------------------------
`testName` | String | The test name.
`fn` | Function | An asynchronous function that contains test code.
`t` | Object | The [test controller](#test-controller) used to access test run API.
`fn` | Function | An asynchronous function that contains the test code.
`t` | Object | The [test controller](#test-controller) used to access the test run API.

```js
fixture `MyFixture`;
Expand All @@ -72,18 +72,17 @@ test('Test2', async t => {
});
```

You are free to structure test code in any manner, and you can
reference any modules or libraries you need.
You can arrange test code in any manner and reference any modules or libraries.

TestCafe tests are executed server side. To manipulate the tested webpage, use [test actions](actions/README.md).
To determine the state of page elements or obtain any other data from the client side, use [selectors](selecting-page-elements/selectors/README.md) and
TestCafe tests are executed on the server side. You can use [test actions](actions/README.md) to manipulate the tested webpage.
To determine page elements' state or obtain any other data from the client side, use the [selectors](selecting-page-elements/selectors/README.md) and
[client functions](obtaining-data-from-the-client/README.md).

To check if the page state matches the expected one, use [assertions](assertions/README.md).

### Test Controller

A *test controller* object `t` exposes methods of test API. That is why it is
A *test controller* object `t` exposes the test API's methods. That is why it is
passed to each function that is expected to contain server-side test code (like [test](#tests),
[beforeEach](#initialization-and-clean-up) or [afterEach](#initialization-and-clean-up)).

Expand All @@ -106,15 +105,15 @@ test('My Test', async t => {
});
```

Another job of the test controller is providing access to the internal context required for test API to operate.
The test controller also provides access to the internal context the test API requires to operate.
This is why [selectors](selecting-page-elements/selectors/README.md) and
[client functions](obtaining-data-from-the-client/README.md) need the test controller object when they are
called from Node.js callbacks.

#### Using Test Controller Outside of Test Code

You may sometimes need to call test API from outside of test code. For instance, your [page model](../recipes/using-page-model.md)
can contain methods that perform common operations used in many tests, like authentication.
You may sometimes need to call the test API from outside the test code. For instance, your [page model](../recipes/using-page-model.md)
can contain methods that perform common operations used in different tests (like authentication).

```js
import { Selector } from 'testcafe';
Expand All @@ -137,7 +136,7 @@ export default class Page {
In this instance, you need to access the test controller from the page model's `login` method.

TestCafe allows you to avoid passing the test controller to the method explicitly.
Instead, you can simply import `t` to the page model file.
Instead, you can import `t` to the page model file.

```js
import { Selector, t } from 'testcafe';
Expand All @@ -157,15 +156,14 @@ export default class Page {
}
```

TestCafe will implicitly resolve test context and provide the right test controller.
TestCafe implicitly resolves test context and provides the right test controller.

### Setting Test Speed

TestCafe allows you to specify the speed of test execution.
TestCafe allows you to specify the test execution speed.

By default, tests run at the maximum speed. However, if you need to watch a test running
to understand what happens in it, this speed may seem too fast. In this instance, use the `t.setTestSpeed` method
to slow the test down.
Tests are run at the maximum speed by default. You can use the `t.setTestSpeed` method
to specify the speed.

```text
t.setTestSpeed( factor )
Expand All @@ -175,7 +173,7 @@ Parameter | Type | Description
---------- | --------- | -----------
`factor` | Number | Specifies the test speed. Must be a number between `1` (the fastest) and `0.01` (the slowest).

If speed is also specified for an [individual action](actions/action-options.md#basic-action-options), the action speed setting overrides test speed.
If the speed is also specified for an [individual action](actions/action-options.md#basic-action-options), the action's speed setting overrides the test speed.

**Example**

Expand All @@ -197,7 +195,7 @@ test(`Test Speed`, async t => {

### Setting Page Load Timeout

Page load timeout defines the amount of time passed after the `DOMContentLoaded` event, within which the `window.load` event should be raised.
The page load timeout defines the time passed after the `DOMContentLoaded` event within which the `window.load` event should be raised.

After the timeout passes or the `window.load` event is raised (whichever happens first), TestCafe starts the test.

Expand All @@ -209,7 +207,7 @@ t.setPageLoadTimeout( duration )

Parameter | Type | Description
---------- | --------- | -----------
`duration` | Number | Page load timeout, in milliseconds. `0` to skip waiting for the `window.load` event.
`duration` | Number | Page load timeout (in milliseconds). `0` to skip waiting for the `window.load` event.

You can also set the page load timeout when launching tests via the [command line](../using-testcafe/command-line-interface.md#--page-load-timeout-ms) or [API](../using-testcafe/programming-interface/runner.md#run).

Expand All @@ -230,16 +228,15 @@ test(`Page load timeout`, async t => {
## Specifying the Start Webpage

You can specify a webpage at which all tests in a fixture start.
To do this, use the `fixture.page` function.
You can specify the web page where all tests in a fixture start using the `fixture.page` function.

```text
fixture.page( url )
fixture.page `url`
```

Similarly, you can specify a start page for individual tests
using the `test.page` function that overrides `fixture.page`.
using the `test.page` function that overrides the `fixture.page`.

```text
test.page( url )
Expand Down Expand Up @@ -267,7 +264,7 @@ test

If the start page is not specified, it defaults to `about:blank`.

To test webpages in local directories, you can use the `file://` scheme or relative paths.
You can use the `file://` scheme or relative paths to test web pages in local directories.

```js
fixture `MyFixture`
Expand All @@ -283,7 +280,7 @@ fixture `MyFixture`

TestCafe allows you to specify additional information for tests in the form of *key-value metadata* and use it in reports.

To define metadata, use the `meta` method. You can call this method both for a fixture and a test.
To define metadata, use the `meta` method. You can call this method for a fixture and a test.

The `meta` method allows you to specify one or several metadata entries:

Expand Down Expand Up @@ -331,9 +328,9 @@ test
('MyTest', async t => { /* ... */});
```

All metadata entries specified for a fixture are applied to tests included to this fixture.
All metadata entries specified for a fixture are applied to tests included in this fixture.

If you specified the same entries in the `test.meta` and `fixture.meta` methods, the `test.meta` method call overrides values of these entries. The following example demonstrates the case when the `test.meta` method call overrides the **creationDate** entry.
If you specified the same entries in the `test.meta` and `fixture.meta` methods, the `test.meta` method call overrides values of these entries. The following example demonstrates a `test.meta` method call that overrides the **creationDate** entry:

```js
fixture `My fixture`
Expand All @@ -347,11 +344,11 @@ test

### Using Metadata in Reports

You can include testing metadata to reports using a [custom reporter](../extending-testcafe/reporter-plugin/README.md). The reporter's [reportFixtureStart](../extending-testcafe/reporter-plugin/reporter-methods.md#reportfixturestart) and [reportTestDone](../extending-testcafe/reporter-plugin/reporter-methods.md#reporttestdone) methods can access to the fixture and test metadata.
You can include testing metadata to reports using a [custom reporter](../extending-testcafe/reporter-plugin/README.md). The reporter's [reportFixtureStart](../extending-testcafe/reporter-plugin/reporter-methods.md#reportfixturestart) and [reportTestDone](../extending-testcafe/reporter-plugin/reporter-methods.md#reporttestdone) methods can access the fixture and test metadata.

## Initialization and Clean-Up

TestCafe allows you to specify functions that will be executed before a fixture or test is started and after it is finished.
TestCafe allows you to specify functions that are executed before a fixture or test is started and after it is finished.
These functions are called *hook functions* or *hooks*.

### Test Hooks
Expand All @@ -360,7 +357,7 @@ Test hooks are executed in each test run before a test is started and after it i

At the moment test hooks run, the tested webpage is already loaded, so that you can use [test actions](actions/README.md) and other test run API inside test hooks.

You can specify a hook for each test in a fixture by using the `beforeEach` and `afterEach` methods in the [fixture declaration](#fixtures).
You can specify a hook for each test in a fixture using the `beforeEach` and `afterEach` methods in the [fixture declaration](#fixtures).

```text
fixture.beforeEach( fn(t) )
Expand All @@ -370,7 +367,7 @@ fixture.beforeEach( fn(t) )
fixture.afterEach( fn(t) )
```

You can also specify hooks for an individual test by using the `test.before` and `test.after` methods.
You can also specify hooks for an individual test using the `test.before` and `test.after` methods.

```text
test.before( fn(t) )
Expand All @@ -383,7 +380,7 @@ test.after( fn(t) )
> If `test.before` or `test.after` is specified, it overrides the corresponding
> `fixture.beforeEach` and `fixture.afterEach` hook, so that the latter are not executed.
The `test.before`, `test.after`, `fixture.beforeEach` and `fixture.afterEach` methods take the following parameters.
The `test.before`, `test.after`, `fixture.beforeEach` and `fixture.afterEach` methods accept the following parameters:

Parameter | Type | Description
--------- | -------- | ---------------------------------------------------------------------------
Expand Down Expand Up @@ -423,7 +420,7 @@ Test context is available through the `t.ctx` property.
t.ctx
```

Instead of using a global variable, assign the object you want to share directly to `t.ctx` or create a property like in the following example.
Instead of using a global variable, assign the object you want to share directly to `t.ctx` or create a property as in the following example:

```js
fixture `Fixture1`
Expand Down Expand Up @@ -545,20 +542,20 @@ fixture.only
test.only
```

If several tests or fixtures are marked with `only`, all the marked tests and fixtures will run.
If several tests or fixtures are marked with `only`, all the marked tests and fixtures are run.

**Examples**

```js
fixture.skip `Fixture1`; // All tests in this fixture will be skipped
fixture.skip `Fixture1`; // All tests in this fixture are skipped

test('Fixture1Test1', () => {});
test('Fixture1Test2', () => {});

fixture `Fixture2`;

test('Fixture2Test1', () => {});
test.skip('Fixture2Test2', () => {}); // This test will be skipped
test.skip('Fixture2Test2', () => {}); // This test is skipped
test('Fixture2Test3', () => {});
```

Expand All @@ -573,5 +570,5 @@ test('Fixture2Test1', () => {});
test.only('Fixture2Test2', () => {});
test('Fixture2Test3', () => {});

// Only tests in Fixture1 and the Fixture2Test2 test will run
// Only tests in Fixture1 and the Fixture2Test2 test are run
```

0 comments on commit 3d8d0ea

Please sign in to comment.