Skip to content

Commit 157b3d5

Browse files
javigomezDavertMik
javigomez
authored and
DavertMik
committed
Add starting guide for testing Joomla Extensions (Codeception#93)
* Joomla instructions * Update Joomla documentation
1 parent f909fb2 commit 157b3d5

File tree

1 file changed

+207
-0
lines changed

1 file changed

+207
-0
lines changed

‎for/joomla.md

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
layout: page
3+
title: Codeception for Joomla
4+
hero: joomla_hero.html
5+
sidebar: |
6+
7+
## Codeception Tests
8+
9+
* Combine **all testing levels** (acceptance, functional, unit)
10+
* **Scenario-Driven**: described in easy to get PHP DSL
11+
* Provide common actions and assertions
12+
13+
## Reference
14+
15+
* [Joomla Browser](http://codeception.com/addons#joomla-browserhttpsgithubcomjoomla-projectsjoomla-browser)
16+
* [Demo Tested Extension](https://github.com/joomla-extensions/weblinks#tests)
17+
18+
---
19+
20+
## Setup
21+
Create a Joomla website in your local web server.
22+
23+
Go to the folder where your website is located and run:
24+
25+
```bash
26+
composer require codeception/codeception --dev
27+
```
28+
29+
Then run:
30+
31+
```
32+
vendor/bin/codecept bootstrap --empty
33+
```
34+
35+
Previous command will have createed `codeception.yml` and `tests` directory.
36+
37+
### Acceptance Testing
38+
39+
#### Using headless browser
40+
41+
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.
42+
43+
For UI testing you will the first step will be to create an acceptance tests suite:
44+
45+
```
46+
vendor/bin/codecept generate:suite acceptance
47+
```
48+
49+
This will create `acceptance.suite.yml` and `acceptance` folder inside `tests`.
50+
51+
```yaml
52+
class_name: AcceptanceTester
53+
modules:
54+
enabled:
55+
- PhpBrowser:
56+
url: http://joomla.box/codeception/
57+
- \Helper\Acceptance
58+
```
59+
60+
Acceptance tests should be described in Cest format. Run Cest test generator to generate your very first test `tests/acceptance/AdminLoginCest.php`:
61+
62+
```
63+
vendor/bin/codecept generate:cest acceptance AdminLoginCest
64+
```
65+
66+
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.
67+
68+
Modify your `tests/acceptance/AdminLoginCest.php` using the following example code:
69+
70+
```php
71+
<?php
72+
73+
class AdminLoginCest
74+
{
75+
public function login(AcceptanceTester $I)
76+
{
77+
$I->amOnPage('/administrator/index.php');
78+
$I->comment('Fill Username Text Field');
79+
$I->fillField('#mod-login-username', 'admin');
80+
$I->comment('Fill Password Text Field');
81+
$I->fillField('#mod-login-password', 'admin');
82+
$I->comment('I click Login button');
83+
$I->click('Log in');
84+
$I->comment('I see Administrator Control Panel');
85+
$I->see('Control Panel', '.page-title');
86+
}
87+
}
88+
```
89+
90+
To generate method stubs for `AcceptanceTester` run:
91+
92+
```
93+
vendor/bin/codecept build
94+
```
95+
96+
Now you are able to run your first test:
97+
98+
99+
```
100+
vendor/bin/codecept run acceptance
101+
```
102+
103+
Or, try this command to see the execution step by step:
104+
105+
```
106+
vendor/bin/codecept run acceptance --steps
107+
```
108+
109+
#### Using a real browser
110+
111+
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](http://codeception.com/docs/03-AcceptanceTests#PHP-Browser).
112+
113+
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).
114+
115+
The Joomla Community provides an extended Webdriver Codeception Module called [Joomla-Browser](http://codeception.com/addons#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](https://github.com/joomla-projects/joomla-browser#joomla-browser-codeception-module).
116+
117+
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:
118+
119+
First, install Joomla-browser:
120+
121+
```bash
122+
composer require joomla-projects/joomla-browser --dev
123+
```
124+
125+
Modify your acceptance.suite.yml file like as follows:
126+
127+
```yaml
128+
class_name: AcceptanceTester
129+
modules:
130+
enabled:
131+
- JoomlaBrowser
132+
- AcceptanceHelper
133+
config:
134+
JoomlaBrowser:
135+
url: 'http://localhost/tests/joomla-cms3' # the url that points to the joomla installation at /tests/system/joomla-cms
136+
browser: 'firefox'
137+
window_size: 1024x768
138+
capabilities:
139+
unexpectedAlertBehaviour: 'accept'
140+
username: 'admin' # UserName for the Administrator
141+
password: 'admin' # Password for the Administrator
142+
database host: 'localhost' # place where the Application is Hosted #server Address
143+
database user: 'root' # MySQL Server user ID, usually root
144+
database password: '' # MySQL Server password, usually empty or root
145+
database name: 'testjoomla' # DB Name, at the Server
146+
database type: 'mysqli' # type in lowercase one of the options: MySQL\MySQLi\PDO
147+
database prefix: 'jos_' # DB Prefix for tables
148+
install sample data: 'No' # Do you want to Download the Sample Data Along with Joomla Installation, then keep it Yes
149+
sample data: 'Default English (GB) Sample Data' # Default Sample Data
150+
admin email: 'admin@mydomain.com' # email Id of the Admin
151+
language: 'English (United Kingdom)' # Language in which you want the Application to be Installed
152+
joomla folder: 'home/.../path to Joomla Folder' # Path to Joomla installation where we execute the tests
153+
154+
```
155+
156+
Modify your previous `tests/acceptance/AdminLoginCest.php` using the following example code:
157+
158+
```php
159+
<?php
160+
161+
class AdminLoginCest
162+
{
163+
public function login(AcceptanceTester $I)
164+
{
165+
$I->doAdministratorLogin();
166+
}
167+
}
168+
```
169+
170+
Run the test:
171+
172+
```
173+
vendor/bin/codecept run acceptance --steps
174+
```
175+
176+
**Important note**, in order to run the previous test you need to have [Selenium](http://docs.seleniumhq.org/download/) running in your system. If you are new to Selenium, you can find an example of useage at the [Weblinks Joomla Official supported extension](https://github.com/joomla-extensions/weblinks#tests). Just follow the "running the tests" instructions to learn how to easily lauch Selenium in your system.
177+
178+
<div class="alert alert-warning">
179+
<span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span>
180+
Continue to <a href="http://codeception.com/docs/03-AcceptanceTests">Acceptance Testing Guide &raquo;</a>
181+
</div>
182+
183+
184+
185+
### BDD
186+
187+
If you prefer to describe application with feature files, Codeception can turn them to acceptance tests.
188+
189+
Your previous test would look like:
190+
191+
```gherkin
192+
Feature: administrator login
193+
In order to manage my web application
194+
As administrator
195+
I need to be able to login
196+
197+
Scenario: Successful login
198+
Given I am registered administrator named "admin"
199+
When I login into Joomla Administrator with username "admin" and password "admin"
200+
Then I should see administrator dashboard
201+
```
202+
203+
<div class="alert alert-warning">
204+
<span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span>
205+
Continue to <a href="http://codeception.com/docs/07-BDD">Behavior Driven Development Guide &raquo;</a>
206+
</div>
207+

0 commit comments

Comments
 (0)