Create a Joomla website in your local web server.
Go to the folder where your website is located and run:
composer require codeception/codeception codeception/module-phpbrowser codeception/module-asserts --dev
Then run:
vendor/bin/codecept bootstrap --empty
Previous command will have createed codeception.yml
and tests
directory.
To test the User Interface of a Joomla Template or an Extension (plugin, module, component, language pack,…) you should simulate the user interaction with a browser.
For UI testing you will the first step will be to create an acceptance tests suite:
vendor/bin/codecept generate:suite acceptance
This will create acceptance.suite.yml
and acceptance
folder inside tests
.
class_name: AcceptanceTester
modules:
enabled:
- PhpBrowser:
url: http://joomla.box/codeception/
- \Helper\Acceptance
Acceptance tests should be described in Cest format. Run Cest test generator to generate your very first test tests/acceptance/AdminLoginCest.php
:
vendor/bin/codecept generate:cest acceptance AdminLoginCest
Each method of a Cest class (except _before
and _after
) is a test. Tests use $I
object (instance of AcceptanceTester
class) to perform actions on a webpage.
Modify your tests/acceptance/AdminLoginCest.php
using the following example code:
<?php
class AdminLoginCest
{
public function login(AcceptanceTester $I)
{
$I->amOnPage('/administrator/index.php');
$I->comment('Fill Username Text Field');
$I->fillField('#mod-login-username', 'admin');
$I->comment('Fill Password Text Field');
$I->fillField('#mod-login-password', 'admin');
$I->comment('I click Login button');
$I->click('Log in');
$I->comment('I see Administrator Control Panel');
$I->see('Control Panel', '.page-title');
}
}
To generate method stubs for AcceptanceTester
run:
vendor/bin/codecept build
Now you are able to run your first test:
vendor/bin/codecept run acceptance
Or, try this command to see the execution step by step:
vendor/bin/codecept run acceptance --steps
Previous execution was done using a headless browser: PHPBrowser. This is the fastest way to run User Interface tests since it doesn’t require running an actual browser. Instead, uses a PHP web scraper, which acts like a browser (it sends a request, then receives and parses the response). Read more about PHPBrowser at http://codeception.com/docs/03-AcceptanceTests#PHP-Browser.
If you prefer to run your test on a real browser like Firefox you are required to use the Codeception Webdriver Module. Unlike PHPBrowser it will allow you to test the visibility of elements or test javascript interactions (but the test execution will be considerably slower).
The Joomla Community provides an extended Webdriver Codeception Module called Joomla-Browser. With Joomla-Browser you can execute, with one command, common joomla actions like: install Joomla, do Adminitrator Login, publish a module, and many more. See the full list at Joomla Browser Documentation.
In the following example we are going to refactor our previous “administrator login test” by using Joomla-Browser and executing it in a Firefox browser:
First, install Joomla-browser:
composer require joomla-projects/joomla-browser --dev
Modify your acceptance.suite.yml file like as follows:
class_name: AcceptanceTester
modules:
enabled:
- JoomlaBrowser
- AcceptanceHelper
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3' # the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
capabilities:
unexpectedAlertBehaviour: 'accept'
username: 'admin' # UserName for the Administrator
password: 'admin' # Password for the Administrator
database host: 'localhost' # place where the Application is Hosted #server Address
database user: 'root' # MySQL Server user ID, usually root
database password: '' # MySQL Server password, usually empty or root
database name: 'testjoomla' # DB Name, at the Server
database type: 'mysqli' # type in lowercase one of the options: MySQL\MySQLi\PDO
database prefix: 'jos_' # DB Prefix for tables
install sample data: 'No' # Do you want to Download the Sample Data Along with Joomla Installation, then keep it Yes
sample data: 'Default English (GB) Sample Data' # Default Sample Data
admin email: '[email protected]' # email Id of the Admin
language: 'English (United Kingdom)' # Language in which you want the Application to be Installed
joomla folder: 'home/.../path to Joomla Folder' # Path to Joomla installation where we execute the tests
Modify your previous tests/acceptance/AdminLoginCest.php
using the following example code:
<?php
class AdminLoginCest
{
public function login(AcceptanceTester $I)
{
$I->doAdministratorLogin();
}
}
Run the test:
vendor/bin/codecept run acceptance --steps
Important note, in order to run the previous test you need to have Selenium running in your system. If you are new to Selenium, you can find an example of useage at the Weblinks Joomla Official supported extension. Just follow the “running the tests” instructions to learn how to easily lauch Selenium in your system.
If you prefer to describe application with feature files, Codeception can turn them to acceptance tests.
Your previous test would look like:
Feature: administrator login
In order to manage my web application
As administrator
I need to be able to login
Scenario: Successful login
Given I am registered administrator named "admin"
When I login into Joomla Administrator with username "admin" and password "admin"
Then I should see administrator dashboard