Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 15 additions & 13 deletions docs/APITesting.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ modules:
depends: PhpBrowser
```

The REST module will connect to `PhpBrowser` according to this configuration. Depending on the web service we may deal with XML or JSON responses. Codeception handles both data formats well, however If you don't need one of them, you can explicitly specify that the JSON or XML parts of the module will be used:
The REST module will connect to `PhpBrowser` according to this configuration. Depending on the web service we may deal with XML or JSON responses. Codeception handles both data formats well, however, if you don't need one of them, you can explicitly specify that the JSON or XML parts of the module will be used:

```yaml
actor: ApiTester
Expand All @@ -46,7 +46,7 @@ modules:
part: Json
```

API tests can be functional and be executed using Symfony, Laravel, Yii2, or any other framework module. You will need slightly update configuration for it:
API tests can be functional and be executed using Symfony, Laravel, Yii2, or any other framework module. You will need to slightly update the configuration for it:

```yaml
actor: ApiTester
Expand Down Expand Up @@ -160,7 +160,7 @@ and rebuild actions:
php vendor/bin/codecept build
```

> `sendGetAsJson`, `sendPutAsJson`, and others, are implemented as a [Step Decorator](https://codeception.com/docs/08-Customization#Step-Decorators).
> `sendGetAsJson`, `sendPutAsJson`, and others, are implemented as a [Step Decorator](https://codeception.com/docs/Customization#Step-Decorators).


### JSON Structure Validation
Expand All @@ -177,7 +177,7 @@ $I->seeResponseJsonMatchesXpath('//user/login');
```

More detailed check can be applied if you need to validate the type of fields in a response.
You can do that by using with a [seeResponseMatchesJsonType](https://codeception.com/docs/modules/REST#seeResponseMatchesJsonType) action in which you define the structure of JSON response.
You can do that by using a [seeResponseMatchesJsonType](https://codeception.com/docs/modules/REST#seeResponseMatchesJsonType) action in which you define the structure of JSON response.

```php
<?php
Expand All @@ -201,7 +201,8 @@ Codeception uses this simple and lightweight definitions format which can be [ea

Responses are returned from `send*` methods:

```php<?php
```php
<?php

$users = $I->sendGet('/users');

Expand All @@ -210,9 +211,10 @@ $users = $I->sendGet('/users');
$users = $I->grabResponse();
```

When you need to obtain a value from a response and use it in next requests you can use `grab*` methods. For instance, use `grabDataFromResponseByJsonPath` allows to query JSON for a value.
When you need to obtain a value from a response and use it in subsequent requests, you can use `grab*` methods. For instance, `grabDataFromResponseByJsonPath` allows querying JSON for a value.

```php<?php
```php
<?php
list($id) = $I->grabDataFromResponseByJsonPath('$.id');
$I->sendGet('/pet/' . $id);
```
Expand All @@ -223,7 +225,7 @@ The last line of the previous example verified that the response contained the p

```php
<?php
// matches {"result":"ok"}'
// matches {"result":"ok"}
$I->seeResponseContainsJson(['result' => 'ok']);
// it can match tree-like structures as well
$I->seeResponseContainsJson([
Expand All @@ -236,7 +238,7 @@ $I->seeResponseContainsJson([

```

You may want to perform even more complex assertions on a response. This can be done by writing your own methods in the [Helper](https://codeception.com/docs/06-ReusingTestCode#Modules-and-Helpers) classes. To access the latest JSON response you will need to get the `response` property of the `REST` module. Let's demonstrate it with the `seeResponseIsHtml` method:
You may want to perform even more complex assertions on a response. This can be done by writing your own methods in the [Helper](https://codeception.com/docs/ModulesAndHelpers#Helpers) classes. To access the latest JSON response you will need to get the `response` property of the `REST` module. Let's demonstrate it with the `seeResponseIsHtml` method:

```php
<?php
Expand Down Expand Up @@ -291,8 +293,8 @@ actor: ApiTester
modules:
enabled:
- SOAP:
depends: PhpBrowser
endpoint: http://serviceapp/api/v1/
depends: PhpBrowser
endpoint: http://serviceapp/api/v1/
```

SOAP request may contain application specific information, like authentication or payment. This information is provided with SOAP header inside the `<soap:Header>` element of XML request. In case you need to submit such header, you can use `haveSoapHeader` action. For example, next line of code
Expand Down Expand Up @@ -335,7 +337,7 @@ And here is the list of sample assertions that can be used with SOAP.

```php
<?php
$I->seeSoapResponseEquals('<?xml version="1.0"<error>500</error>');
$I->seeSoapResponseEquals('<?xml version="1.0"?><error>500</error>');
$I->seeSoapResponseIncludes('<result>1</result>');
$I->seeSoapResponseContainsStructure('<user><name></name><email></email>');
$I->seeSoapResponseContainsXPath('//result/user/name[@id=1]');
Expand All @@ -348,7 +350,7 @@ In the next example we will use `XmlBuilder` instead of regular XML.
```php
<?php
$I->haveSoapHeader('Session', array('token' => '123456'));
$I->sendSoapRequest('CreateUser', Xml::build()
$I->sendSoapRequest('CreateUser', \Codeception\Util\Xml::build()
->user->email->val('miles@davis.com'));
$I->seeSoapResponseIncludes(\Codeception\Util\Xml::build()
->result->val('Ok')
Expand Down
58 changes: 32 additions & 26 deletions docs/AcceptanceTests.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ We will start writing our first acceptance tests with PhpBrowser.

This is the fastest way to run acceptance tests since it doesn't require running an actual browser.
We use a PHP web scraper, which acts like a browser: It sends a request, then receives and parses the response.
Codeception uses [Guzzle](https://guzzlephp.org) and [Symfony BrowserKit](https://symfony.com/doc/current/components/browser_kit.html) to interact with HTML web pages.
Codeception uses [Guzzle](https://docs.guzzlephp.org/) and [Symfony BrowserKit](https://symfony.com/doc/current/components/browser_kit.html) to interact with HTML web pages.

Common PhpBrowser drawbacks:

Expand All @@ -74,6 +74,12 @@ php vendor/bin/codecept g:cest Acceptance Signin
It will be placed into `tests/Acceptance` directory.

```php
<?php

namespace Tests\Acceptance;

use Tests\Support\AcceptanceTester;

class SigninCest
{
public function tryToTest(AcceptanceTester $I)
Expand Down Expand Up @@ -104,7 +110,7 @@ $I->click('Log in');
// CSS selector applied
$I->click('#login a');
// XPath
$I->click('//a[@id=login]');
$I->click('//a[@id="login"]');
// Using context as second argument
$I->click('Login', '.nav');
```
Expand Down Expand Up @@ -343,7 +349,7 @@ $user_id = $I->grabFromCurrentUrl('~^/user/(\d+)/~');

## WebDriver

A nice feature of Codeception is that most scenarios are similar, no matter of how they are executed.
A nice feature of Codeception is that most scenarios are similar, no matter how they are executed.
`PhpBrowser` was emulating browser requests but how to execute such test in a real browser like Chrome or Firefox?
Selenium WebDriver can drive them so in our acceptance tests we can automate scenarios we used to test manually.
In such tests, we should concentrate more on **testing the UI** than on testing functionality.
Expand Down Expand Up @@ -376,13 +382,13 @@ Launch this command in a separate terminal:
selenium-standalone start
```

![](https://raw.githubusercontent.com/vvo/selenium-standalone/HEAD/screencast.gif)
![](https://raw.githubusercontent.com/webdriverio/selenium-standalone/HEAD/screencast.gif)

Now, you are ready to run WebDriver tests using Codeception.

> Alternatively, Selenium Server can be installed manually. [Download it](https://www.selenium.dev/downloads/) from the official site and launch a server with Java: `java -jar selenium-server-....jar`. In this case ChromeDriver and GeckoDriver must be installed separately.

* For more information refer to [Installation Instructions](https://codeception.com/docs/modules/WebDriver#Selenium)
* For more information refer to [Installation Instructions](https://codeception.com/docs/modules/WebDriver#Selenium-Recommended)
* Enable [RunProcess](https://codeception.com/extensions#RunProcess) extension to start/stop Selenium automatically *(optional)*.


Expand All @@ -397,7 +403,7 @@ actor: AcceptanceTester
modules:
enabled:
- WebDriver:
url: {{your site URL}}
url: http://localhost/myapp
browser: chrome
```

Expand All @@ -415,7 +421,7 @@ WebDriver also adds browser-specific functionality:

#### Wait

While testing web application, you may need to wait for JavaScript events to occur. Due to its asynchronous nature,
While testing a web application, you may need to wait for JavaScript events to occur. Due to its asynchronous nature,
complex JavaScript interactions are hard to test. That's why you may need to use waiters, actions with `wait` prefix.
They can be used to specify what event you expect to occur on a page, before continuing the test.

Expand All @@ -430,17 +436,17 @@ In this case, we are waiting for the 'agree' button to appear and then click it.
the test will fail. There are other `wait` methods you may use, like [waitForText](https://codeception.com/docs/modules/WebDriver#waitForText),
[waitForElementVisible](https://codeception.com/docs/modules/WebDriver#waitForElementVisible) and others.

If you don't know what exact element you need to wait for, you can simply pause execution with using `$I->wait()`
If you don't know what exact element you need to wait for, you can simply pause execution by using `$I->wait()`

```php
$I->wait(3); // wait for 3 secs
```

#### SmartWait

It is possible to wait for elements pragmatically.
If a test uses element which is not on a page yet, Codeception will wait for few extra seconds before failing.
This feature is based on [Implicit Wait](https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp#implicit-waits) of Selenium.
It is possible to wait for elements programmatically.
If a test uses an element which is not on a page yet, Codeception will wait for a few extra seconds before failing.
This feature is based on [Implicit Wait](https://www.selenium.dev/documentation/webdriver/waits/#implicit-waits) of Selenium.
Codeception enables implicit wait only when searching for a specific element and disables in all other cases. Thus, the performance of a test is not affected.

SmartWait can be enabled by setting `wait` option in WebDriver config. It expects the number of seconds to wait. Example:
Expand All @@ -458,7 +464,7 @@ With this config we have the following test:
$I->click(['css' => '#click-me']);
```

It is important to understand that SmartWait works only with a specific locators:
It is important to understand that SmartWait works only with specific locators:

* `#locator` - CSS ID locator, works
* `//locator` - general XPath locator, works
Expand All @@ -480,9 +486,9 @@ $I->seeNumberOfElements(['css' => 'button.link'], 5); // DISABLED, can wait only

#### Retry

When it's hard to define condition to wait for, we can retry a command few times until it succeeds.
For instance, if you try to click while it's animating you can try to do it few times until it freezes.
Each action and assertion have an alias prefixed with `retry` which allows to retry a flaky command.
When it's hard to define a condition to wait for, we can retry a command a few times until it succeeds.
For instance, if you try to click while it's animating you can try to do it a few times until it freezes.
Each action and assertion has an alias prefixed with `retry` which allows to retry a flaky command.

```php
$I->retryClick('flaky element');
Expand Down Expand Up @@ -552,11 +558,11 @@ For more options see [`performOn()` reference](https://codeception.com/docs/modu

#### A/B Testing

When a web site acts unpredictably you may need to react on that change.
This happens if site configured for A/B testing, or shows different popups, based on environment.
When a web site acts unpredictably you may need to react to that change.
This happens if a site is configured for A/B testing, or shows different popups, based on environment.

Since Codeception 3.0 you can have some actions to fail silently, if they are errored.
Let's say, you open a page and some times there is a popup which should be closed.
Let's say, you open a page and sometimes there is a popup which should be closed.
We may try to hit the "close" button but if this action fails (no popup on page) we just continue the test.

This is how it can be implemented:
Expand Down Expand Up @@ -634,7 +640,7 @@ class AcceptanceTester extends \Codeception\Actor

### Cloud Testing

Some environments are hard to be reproduced manually, testing Internet Explorer 6-8 on Windows XP may be a hard thing,
Some environments are hard to reproduce manually, testing Internet Explorer 6-8 on Windows XP may be a hard thing,
especially if you don't have Windows XP installed. This is where Cloud Testing services come to help you.
Services such as [SauceLabs](https://saucelabs.com), [BrowserStack](https://www.browserstack.com/)
and [others](https://codeception.com/docs/modules/WebDriver#Cloud-Testing) can create virtual machines on demand
Expand All @@ -650,12 +656,12 @@ You just need to set the [WebDriver configuration](https://codeception.com/docs/
* browser
* OS

We recommend using [params](https://codeception.com/docs/06-ModulesAndHelpers#Dynamic-Configuration-With-Params)
We recommend using [params](https://codeception.com/docs/ModulesAndHelpers#Dynamic-Configuration-With-Parameters)
to provide authorization credentials.

It should be mentioned that Cloud Testing services are not free. You should investigate their pricing models
and choose one that fits your needs. They also may work painfully slowly if ping times between the local server
and the cloud is too high. This may lead to random failures in acceptance tests.
and the cloud are too high. This may lead to random failures in acceptance tests.

### Debugging

Expand All @@ -671,8 +677,8 @@ PhpBrowser will store the HTML code and WebDriver will save a screenshot of the

Additional debugging features by Codeception:

* [Interactive Pause](https://codeception.com/docs/02-GettingStarted#Interactive-Pause) is a REPL that allows to type and check commands for instant feedback.
* [Recorder Extension](https://codeception.com/addons#CodeceptionExtensionRecorder) allows to record tests step-by-steps and show them in slideshow
* [Interactive Pause](https://codeception.com/docs/Debugging#Pause) is a REPL that allows to type and check commands for instant feedback.
* [Recorder Extension](https://codeception.com/extensions#Recorder) allows to record tests step-by-step and show them in slideshow

### Common Cases

Expand Down Expand Up @@ -751,16 +757,16 @@ Note that session restoration only works for `WebDriver` modules

By default, WebDriver module is configured to automatically start browser before the test and stop afterward.
However, this can be switched off with `start: false` module configuration.
To start a browser you will need to write corresponding methods in Acceptance [Helper](https://codeception.com/docs/06-ModulesAndHelpers#Helpers).
To start a browser you will need to write corresponding methods in Acceptance [Helper](https://codeception.com/docs/ModulesAndHelpers#Helpers).

WebDriver module provides advanced methods for the browser session, however, they can only be used from Helpers.

* [_initializeSession](https://codeception.com/docs/modules/WebDriver#_initializeSession) - starts a new browser session
* [_closeSession](https://codeception.com/docs/modules/WebDriver#_closeSession) - stops the browser session
* [_restart](https://codeception.com/docs/modules/WebDriver#_restart) - updates configuration and restarts browser
* [_capabilities](https://codeception.com/docs/modules/WebDriver#_capabilities) - set [desired capabilities](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities) programmatically.
* [_capabilities](https://codeception.com/docs/modules/WebDriver#_capabilities) - set [desired capabilities](https://www.selenium.dev/documentation/webdriver/drivers/options/) programmatically.

Those methods can be used to create custom commands like `$I->startBrowser()` or used in [before/after](https://codeception.com/docs/06-ModulesAndHelpers#Hooks) hooks.
Those methods can be used to create custom commands like `$I->startBrowser()` or used in [before/after](https://codeception.com/docs/ModulesAndHelpers#Hooks) hooks.

## Conclusion

Expand Down
20 changes: 12 additions & 8 deletions docs/AdvancedUsage.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ and keep your project better organized.

## Cest Classes
Cest is a common test format for Codeception, it is "Test" with the first C letter in it.
It is scenario-driven format so all tests written in it are executed step by step.
Unless you need direct access to application code inside a test, Cest format is recommended.
As it provides more readable code for functional, api, and acceptance tests.
It is a scenario-driven format, so all tests written in it are executed step by step.
Unless you need direct access to application code inside a test, Cest format is recommended,
as it provides more readable code for functional, API, and acceptance tests.

A new Cest class can be created via `g:cest` command:

Expand Down Expand Up @@ -103,6 +103,7 @@ namespace Tests\Acceptance;

use Codeception\Attribute\Skip;
use Codeception\Scenario;
use Tests\Support\AcceptanceTester;

class UserCest
{
Expand Down Expand Up @@ -319,6 +320,7 @@ namespace Tests\Acceptance;

use Codeception\Attribute\DataProvider;
use Codeception\Example;
use Tests\Support\AcceptanceTester;

class PageCest
{
Expand Down Expand Up @@ -401,6 +403,7 @@ If that test fails, the current test will be skipped. You should pass the method
namespace Tests\Acceptance;

use Codeception\Attribute\Depends;
use Tests\Support\AcceptanceTester;

class ModeratorCest
{
Expand Down Expand Up @@ -507,7 +510,7 @@ The tests will be executed 2 times, each time in a different browser.
It's also possible to merge multiple environments into a single configuration by separating them with a comma:

```
php vendor/bin/codecept run Acceptance --env dev,firefox --env dev,chrome --env dev,firefox
php vendor/bin/codecept run Acceptance --env dev,firefox --env dev,chrome
```

The configuration is merged in the order given.
Expand All @@ -523,6 +526,7 @@ The desired environments can be specified with the `Env` attribute:
namespace Tests\Acceptance;

use Codeception\Attribute\Env;
use Tests\Support\AcceptanceTester;

class UserCest
{
Expand All @@ -531,7 +535,7 @@ class UserCest
*/
#[Env('firefox')]
#[Env('chrome')]
public function webkitOnlyTest(AcceptanceTester $I)
public function firefoxAndChromeOnlyTest(AcceptanceTester $I)
{
// I do something
}
Expand All @@ -554,7 +558,7 @@ It is possible to combine environments. For instance, if a test should be execut

Test marked with this attribute will be executed only if both environments are set:

```php
```bash
php vendor/bin/codecept run --env chrome,staging
```

Expand Down Expand Up @@ -615,7 +619,7 @@ settings:

Alternatively, you may run tests in the shuffle without changing the config:

```yaml
```bash
codecept run -o "settings: shuffle: true"
```

Expand All @@ -630,7 +634,7 @@ Codeception PHP Testing Framework v5.3.7 https://stand-with-ukraine.pp.ua

Pass the copied seed into `--seed` option:

```yaml
```bash
codecept run --seed 1872290562
```

Expand Down
Loading