Codeception in practice
Codeception is a framework designed for creating unit tests, functional tests, and acceptance tests. In this article, I’ll focus on the process of creating an automated acceptance test, locating objects, and reporting results.
Installation
The installation process is very easy. The only requirement is to have a PHP interpreter installed, and optionally a Composer. Next, you can install Codeception using composer require "codeception/codeception". To create a test environment, run the php codecept.phar bootstrap command.
Creating a test
Files for the initial test are created by running a Cept generator: codecept generate:cept acceptance logowanie
Sample test:
[code_highlight language="php"]
<?php
$I->new AcceptanceTester($scenario);
$I->wantTo("Login as a regular user");
$I->amOnPage("https://system.trans.eu");
$I->see("login");
$I->fillField("login", "ja");
$I->fillField("password", "haslo");
$I->click("submit");
[/code_highlight]
The idea of Codeception is to create instances of testers and use scenarios to be executed by them. In this case, the first line creates an acceptance tester and passes a default scenario to it. The tester informs what type of operation it will attempt to execute (wantTo), proceeds to the login page (amOnPage), and performs an initial assertion. The ‘see’ method is an assertion that checks whether there is an element matching the ‘login’ pattern on the downloaded page. Comparison is done by matching object IDs, class names, attributes, etc. Two subsequent fillField methods fill the input fields with IDs: ‘login’ and ‘password’. A click results in the selection of an element matching the ‘submit’ string, and submits the form.
The above test is the very essence of Codeception – it uses the basic components of the framework.
Configuration
Codeception is configured with the use of .yml files. They are available globally as well as separately for each type of tests. Configuration file for acceptance tests is called: acceptance.suite.yml
To use the WebDriver protocol and this driver, activate the appropriate module using the ‘enabled’ option and the host and port data. Sample section of the file:
[code_highlight language="xml"]
class_name: AcceptanceTester
modules:
enabled:
- WebDriver:
browser: firefox
window_size: 1280x800
wait: 10
[/code_highlight]
Running
The basic run is initiated by executing the codecept run command.
Useful execution option is -d for running in debug mode, displaying details of test execution as well as additional values that the developer might want to view in the console.
Test result PASSED
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Acceptance Tests (1) -----------------------
Modules: WebDriver, \Helper\Acceptance
>Functional Tests (0) ------------------------
Modules: \Helper\Functional
---------------------------------------------
---------------------------------------------
Unit Tests (0) ------------------------------
Modules: Asserts, \Helper\Unit
---------------------------------------------
---------------------------------------------
Time: 0.18 minutes, Memory: 7.50Mb
OK (1 test, 1 assertions)
The information above inform us about the execution of a single test with one assertion. The test was successful.
Page object pattern
Codeception supports the Page Object pattern. Built-in generators create classes for selected pages of tested application:
codecept generate:pageobject Login
Next, object definitions along with their locators and methods for controlling the flow of data and actions on a given page are put in the class.
Locating elements
Matching can be done based on strict locators:
[code_highlight language="php"]
['id'=>'object_id']
['name'=>'objectName']
['xpath'=>'//div[@class="search-button"]']
['link'=>'Click this link!']
['css'=>'[role=dialog]']
[/code_highlight]
You can also leave the Codeception matching and use fuzzy locators, as presented in previous examples ($I->see("login") )
Retrieving text from an object
A set of commands called grabbers allows you to read texts from div elements or inputs and use it e.g. in assertion or print it to the console: $I->grabTextFrom('#div')
Environments
Codeception uses numerous config files that can help you run tests for different testing environments.
The ‘env’ section of the file contains definitions specific to a given environment, such as the URL, driver used, etc. An environment (or many environments) is selected at execution, using the -env option of the framework, e.g. codecept run -d --env prod
Screenshots
Codeception automatically makes screenshots (and downloads HTML code) for any errors found, but you can also perform manual download at any stage of the script. This can be done with the use of the makeScreenshot command.
Example:
$I->makeScreenshot($scenario->current('name').'_screenshot.png');
Reporting
By default, Codeception prints a test result to the system console and makes screenshots of any error found. In addition, numerous formats can be used. It is possible thanks to the --xml and --html options. The former generates a JUnit XML output, and the latter creates an HTML report.
