Joomla! Documentation - User contributions [en]

Unit Test Tutorial 1

2010-05-25T06:04:40Z

Jedbox: /* Link to Tutorial Part 2 */

= Unit Testing and Joomla! =

As we move forward with Joomla! Development one element that is going to be playing a larger and larger role is unit testing. My hope with this short series is to provide some basic background on unit testing, to demonstrate how essential unit tests are to stable software and to give practical instruction and examples that illustrate how to write unit tests.

As co-maintainer of the Joomla! Bug Squad, there is a question that repeatedly pops up: 'What is this change going to break?'. There are certain elements of the code base that can be rather fragile and this makes it very difficult to know what things are safe to touch and what things aren't. The component routers are a good example of this. We are very very hesitant to touch this because many people are very particular about their URLs, and past experience has shown that small changes can cause significant, unforeseen problems.

Good unit tests take a great deal of the anxiety out of such changes because you can be confident that the change you are introducing is not going to have nasty, unforeseen consequences.

== What is Unit Testing? ==

In its purest form, unit tests are tests that are designed to ensure that small units of code behave as they are intended. Pure unit testing means that each method is tested in isolation from all other methods. That is to say, for example, that if we are writing a test for JApplication, and JApplication happens to use the JDatabase class, we want to try and design our tests such that a bug in the JDatabase class won't affect our test written for the JApplication class.

In practice, this can be difficult because sometimes class references are hardcoded. Static methods are very difficult in this regard because you can't redefine classes and all tests in PHPUnit are executed in the same process.

On the other end of the scale is system testing. System tests are tests that are written to test a system as a whole. In these tests, the goal isn't to isolate particular units of code. Rather, it is to ensure that all the parts work together in the way they were intended. For web applications, these tests are often developed using a product called Selenium which allows you to control a web browser in order to simulate a user actually using your web application.

== Installing PHPUnit ==

We are slowing building up an extensive suite of unit tests for the Joomla! Framework. The tests are built on a unit testing framework called PHPUnit. In order to run the tests, you need to obtain PHPUnit.
To get PHPUnit, head over to [http://www.phpunit.de/manual/current/en/installation.html PHPUnit Installation] and follow the instructions to install PHPUnit.

== Running Tests ==

Unit tests are typically run from the command line. While this may be daunting for some, once you get the hang of things it is actually quite easy.
Once you have PHPUnit installed and your path setup correctly, it is as simple as changing to the unit test directory and typing 'phpunit':
cd /path/to/joomla/tests/unit
phpunit
After you run this command, you should see output that looks something like:

<pre>PHPUnit 3.4.11 by Sebastian Bergmann.

IIIIIIIIIIIIIIIIIIIII...III..IIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 60 / 2207
III...SIIIIII.IIIIIIIIIIIIII....................F.IIIIIIIIII 120 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 180 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 240 / 2207
IIIIIIIIIIIIIII.......................I.I...FFFFFEEEEEEEEEE. 300 / 2207
....FFFFF.EEEIIIIIIIII...IIIFFFFF.....SSSSFSSSSSSFSSSSSSSSSS 360 / 2207
SSSSSFSS......IIF.SFFFFFFF.......I........I................. 420 / 2207
.........III.II.IIII.IIII.I.........I.IIIII.IIII..........II 480 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 540 / 2207
IIIIIIIIIIIIIIIII.IIIIIIIIIIIIIII........................... 600 / 2207
...IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 660 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIII.................................. 720 / 2207
....................................................FFFF.... 780 / 2207
............................................................ 840 / 2207
............................................................ 900 / 2207
............................................................ 960 / 2207
............................................IIIIIIIIIIIIIIII 1020 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 1080 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 1140 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 1200 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 1260 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 1320 / 2207
IIIIIIIIIIIIIIIIIIII...I.....II.IIIIIIIIIIIIIIIIIIIIIIIIIIII 1380 / 2207
IIIIIIIIIIIIII.IIIIIIIIIII.........IIIIII.IIIIIIIIIIIIIIIIII 1440 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII..II.............. 1500 / 2207
.........F.F...........F..FFF................II....I...F..II 1560 / 2207
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 1620 / 2207
IIIIIIIIIIIIIIIIIII...F........IIIIIIIIIIIIIIIIIIIIIIIIIIIII 1680 / 2207
IIIIIIIIIIIIII..IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII........... 1740 / 2207
...F........................................................ 1800 / 2207
............................................................ 1860 / 2207
............................................................ 1920 / 2207
............................................................ 1980 / 2207
............................................................ 2040 / 2207
.........................F.................................. 2100 / 2207
............................F............................... 2160 / 2207
...............................F..I............

Time: 14 seconds, Memory: 89.50Mb

There were 13 errors:

1) JCacheTest::testSetCaching with data set "simple" ('output', array())
Undefined property: JCacheControllerOutput::$_options

2) JCacheTest::testSetCaching with data set "complexOutput" ('output', array('', '/home/ian/www/ut_work/unittest/cache', 900, 'file'))
Undefined property: JCacheControllerOutput::$_options

3) JCacheTest::testSetCaching with data set "complexPage" ('page', array('', '/home/ian/www/ut_work/unittest/cache', 900, 'file'))
Undefined property: JCacheControllerPage::$_options

...

--

There were 43 failures:

1) JControllerFormTest::testConstructor
_asset_name has not been defined for structure
Failed asserting that an array has the key <string:_asset_name>.

2) JCacheTest::testGetInstance with data set "simple" ('output', array(), 'JCacheOutput')
Failed asserting that <JCacheControllerOutput> is an instance of class "JCacheOutput".

3) JCacheTest::testGetInstance with data set "complexOutput" ('output', array('', '/home/ian/www/ut_work/tests/unit/cache', 900, 'file'), 'JCacheOutput')
Failed asserting that <JCacheControllerOutput> is an instance of class "JCacheOutput".

4) JCacheTest::testGetInstance with data set "complexPage" ('page', array('', '/home/ian/www/ut_work/tests/unit/cache', 900, 'file'), 'JCachePage')
Failed asserting that <JCacheControllerPage> is an instance of class "JCachePage".

...

FAILURES!
Tests: 2207, Assertions: 1751, Failures: 43, Errors: 13, Incomplete: 1063, Skipped: 29.
</pre>

There are many situations where you may not want to run the whole test suite. See the [[Running Unit Tests]] page for details on how to be selective with the tests that you run.

== Anatomy of a Test ==

Unit tests are merely small chunks of PHP code that:
# Setup certain preconditions for the code to be tested (inputs).
# Execute the code to be tested.
# Tests assertions about the results (outputs).

We will see these basic elements in each of the example tests that are provided below.

== Writing Our First Test ==

The easiest and most simple type of unit test to write is a test for code that is stateless. That is, a test for which the return value of the method depends solely on the inputs to the method. Most of the basic PHP functions are examples of stateless functions. The strtoupper function, for example, takes one parameter – a string – and returns a string value. You can easily create a set of inputs and corresponding outputs and write a test.
Examples in the Joomla! Framework include much of the JArrayHelper class. Most of these methods are static methods and don't depend on anything except the data passed to the method. For this example, we will use the JArrayHelper::getColumn method. This method takes two parameters and returns an array.
So, following the three steps outlined above, we break things down into three elements:

=== 1. Setup Preconditions ===

In this case, there are no preconditions because our method does not depend on anything other than the parameters that are passed to it. Our only preconditions are the parameters that we pass to the method.

=== 2. Execute the code to be tested ===

So, our method in question will take an array of associative arrays or objects and will return an array of the values of the specified index.
So, to test our method, we first need to create an array of associative arrays:

<source lang="php">$test_array = array(
array(
'sport' => 'football',
'teams' => '16',
'country' => 'United States'
).
array(
'sport' => 'badminton',
'teams' => '12',
'country' => 'Germany'
),
array(
'sport' => 'basketball',
'teams' => '20',
'country' => 'Canada'
)
);</source>

Now we execute the method and retrieve the results:

<source lang="php">$result_array = JArrayHelper::getColumn($test_array, 'country');</source>

We have now executed the method we want to test. We can now examine the results.

=== 3. Tests assertions about the results (outputs) ===

Since this method is fairly simple, testing the results is also simple. What we need to do is figure out what we expect to get back from the method. In this case, we expect to get an array containing an array of the countries.

<source lang="php">$this->assertThat(
$result_array,
$this->equalTo(array('United States', 'Germany', 'Canada')),
'We did not get the proper column data back'
);</source>

Our final test looks like:
<source lang="php">
public function testGetColumnTutorial()
{
$test_array = array(
array(
'sport' => 'football',
'teams' => '16',
'country' => 'United States'
),
array(
'sport' => 'badminton',
'teams' => '12',
'country' => 'Germany'
),
array(
'sport' => 'basketball',
'teams' => '20',
'country' => 'Canada'
)
);

$result_array = JArrayHelper::getColumn($test_array, 'country');

$this->assertThat(
$result_array,
$this->equalTo(
array('United States', 'Germany', 'Canada')
),
'We did not get the proper column data back'
);
}
</source>

== How a Unit Test should NOT be written ==

Unexperienced users often tap into pitfalls when writing unit test testcases.
A good tutorial on how to avoid these pitfalls, sometimes also called anti-patterns, is summarized at [http://exubero.com/junit/antipatterns.html].

= Unit Test Tutorial 2 =
This article is continued here: [[Unit Test Tutorial 2]]. This includes looking into the derived 'PHPUnit_Framework_TestCase' testclass and the minimum requirements for a standalone testclass.

[[Category:Bug Squad]] [[Category:Development]] [[Category:Testing]] [[Category:Automated Testing]]

Unit Test Tutorial 2

2010-05-24T02:56:33Z

Jedbox: /* Add Category Testing */

== Looking at the Unit Test Class ==

In our first unit test, we create a single test. This test was a part of a presumed preexisting test class. Although an individual test can be contained in a single method, these methods have to be a part of a test class.

Unit Test classes generally inherit from the class 'PHPUnit_Framework_TestCase'.

You can see a basic test class below:
<source lang="php">
<?php
/**
* @version $Id$
* @copyright Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

require_once JPATH_BASE.'/libraries/joomla/utilities/arrayhelper.php';

/**
* Test class for JArrayHelper.
*/
class JArrayHelperTest extends PHPUnit_Framework_TestCase {

/**
* Sets up the fixture, for example, opens a network connection.
* This method is called before a test is executed.
*
* @access protected
*/
protected function setUp() {

}

/**
* Tears down the fixture, for example, closes a network connection.
* This method is called after a test is executed.
*
* @access protected
*/
protected function tearDown() {

}

/**
* Simple Test for getColumn method.
*/
public function testGetColumn()
{
$test_array = array(
array(
'sport' => 'football',
'teams' => '16',
'country' => 'United States'
),
array(
'sport' => 'badminton',
'teams' => '12',
'country' => 'Germany'
),
array(
'sport' => 'basketball',
'teams' => '20',
'country' => 'Canada'
)
);

$result_array = JArrayHelper::getColumn($test_array, 'country');

$this->assertThat(
$result_array,
$this->equalTo(
array('United States', 'Germany', 'Canada')
),
'We did not get the proper column data back'
);
}
}
</source>

Okay, so some notes:

* As noted, the class extends from PHPUnit_Framework_TestCase
* Outside of our class, we do a require for the class that we want to test
* Our class name starts with the name of the class we want to test and has 'Test' appended to the end. i.e. we are testing JArrayHelper, so our test class is JArrayHelperTest.
* We have two methods that are not part of our tests: setUp() and tearDown(). As noted in the comments for these methods, setUp() is called before each test and tearDown() is called after each test. To clarify, if there are 10 tests in a class, they are each called ten times. There are two other methods available that you can supply: setUpBeforeClass() and tearDownAfterClass(). As the names imply, these are each called before and after all the tests from the class are performed, thus getting executed once each.
* Test methods start with the word test and generally end with the name of the method that is under test. We are testing the getColumn() method, therefore, our method is called testGetColumn(). As methods get more complicated, more than one method is required for testing. In this situation, method names that describe the general purpose of the method should be used.

[[Category:Testing]]

Unit Test Tutorial 1

2010-05-24T02:53:52Z

Jedbox: /* Add to category Testing */

Unit Test Tutorial 1

2010-05-24T02:49:11Z

Jedbox: /* How a Unit Test should NOT be written */

Unit Test Tutorial 1

2010-05-24T02:40:35Z

Jedbox: /* Add new Chapter */

How to add CSRF anti-spoofing to forms

2010-01-23T06:30:34Z

Jedbox: /* Protecting Against CSRF Attakcs */

== What is a CSRF Attack? ==

A Cross Site Request Forgery ([[Wikipedia:Cross-site_request_forgery WikiPedia|CSRF]]) attack relies on the trust a website has for a user to execute unauthorized requests and or transactions. For example, say a user is logged into their Joomla! websites' administrator interface in one tab and is browsing a compromised site in another tab. A simple CSRF attack can be launched simply by tampering with IMG elements in some browsers so that they point to something like
<nowiki>http://some/joomla/site/administrator/index2.php?option=com_users&task=delete...</nowiki>
When the user browses the compromised site, that image will be requested and because the user is currently logged in to the administrator interface of her Joomla! site, the forged request will be positively authenticated and executed. To prevent simple CSRF attacks like the one above, request tokens have been added to all forms in the front-end and back-end Joomla! interfaces. The tokens are randomized strings that are used to authenticate that the request being made is coming from a valid form and a valid session. This simple measure is very effective at preventing a large percentage of potential CSRF attacks, however, due to the nature of CSRF they are extremely difficult, if not impossible, to secure against completely.

== Protecting Against CSRF Attacks ==

Joomla! attempts to protect againt CSRF by inserting a random string called a token into each POST form and each GET query string that is able to modify something in the Joomla! system. This random string provides protection because not only does the compromised site need to know the URL of the target site and a valid request format for the target site, it also must know the random string which changes for each session and each user.

The {{jf}} makes it easy for you to include such protection in your components as well. This is simple to implement in both POST and GET requests.

=== POST Request ===

POST requests are submitted in HTML using forms. In order to add the token to your form, add the following line inside your form:
<?php echo JHTML::_( 'form.token' ); ?>

This will output something like the following:
<input type="hidden" name="1234567890abcdef1234567890abcdef" value="1" />

=== GET Request ===

GET requests are submitted in HTML using query strings. In order to add the token to your query string, use a URL like:
<?php
echo JRoute::_( 'index.php?option=com_example&controller=object1&task=save&'. JUtility::getToken() .'=1' );
?>

This will generate a URL with the token in the query string.

=== Checking the Token ===

Once you have included the token in your form or in your query string, you must check the token '''before your script carries out the request'''. This is done with the following line:
JRequest::checkToken() or die( 'Invalid Token' );

If the request is coming from the query string, you must specify this. The code then becomes:
JRequest::checkToken( 'get' ) or die( 'Invalid Token' );

== Recommended Security Procedures ==

While these methods help to prevent against these types of attacks, it is important to realize that as a system administrator, there are good security practices to follow which will prevent a site from being compromised.

# Don't browse other sites in the same browser while you are logged into your site.
# Log out from your site after you are done.
# Don't stay logged into your site while you are not doing anything.
# Ensure that the address in the browser bar matches the address of your site.

By practicing these safe surfing habits you will eliminate most threats to your web site.

[[Category:FAQ]]
[[Category:Security_FAQ]]
[[Category:Security]]
[[Category:Development]]

J1.5:How to create a language pack

2010-01-02T09:56:17Z

Jedbox:

{{review}}

Joomla! uses three language packages, one for the front end, one for the administrator and one for installation. Ideally you will create all three.

A translation pack consists of an xml file, a blank index file and a set of *.ini files containing the language strings for your language. The easiest way to understand this structure is to look at the files in the language/en-GB folder of your Joomla! installation.

This is an excerpt from en-GB.mod_login.ini

<code>

BUTTON_LOGIN=Login
BUTTON_LOGOUT=Logout
DESCLOGINFORM=This Module displays a username and password Login form. It also displays a link to retrieve a forgotten password. If User registration is enabled, (refer to the Global Configuration settings), then another link will be shown to invite Users to self-register.
ENCRYPT LOGIN FORM=Encrypt Login Form
FORGOT_YOUR_PASSWORD=Forgot your password?
FORGOT_YOUR_USERNAME=Forgot your username?
GREETING=Greeting
</code>

To create a package for your language you change the strings to the right of the =.

Many people find it helpful to use the [http://extensions.joomla.org/component/option,com_mtree/task,viewlink/link_id,1776/Itemid,35/ translation manager extension]. This helps by automating the creation of the files.

Language naming convention in Joomla are
language and ISO code. Use 2 letters when available. [http://www.loc.gov/standards/iso639-2/php/code_list.php The list is available here.]

[http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm This reference concerns country codes]

Because language strings may change it is best to create your packages using either [http://developer.joomla.org/code.html the nightly build or subversion].

Name of package should be: xx-XX //using your language's ISO code.

Locale:
[http://forum.joomla.org/viewtopic.php?t=25077 Information on available locales may be found here.]

If, for any reason, ini or xml language files are edited manually with a text editor, they have to be saved with the encoding UTF8 NO BOM.

For practical information on the way to make core Translation files for Joomla 1.0, please see forum: http://forum.joomla.org/viewtopic.php?f=11&t=254709.

And for Joomla 1.5 see the forum:
[http://forum.joomla.org/viewtopic.php?f=11&t=88326&start=0 Building Extension's Language Pack for J1.5]

<noinclude>
[[Category:Languages]]
</noinclude>

J1.5:How to create a language pack

2010-01-02T09:54:57Z

Jedbox: add ref to J1.5 Language pack forum

{{review}}

Joomla! uses three language packages, one for the front end, one for the administrator and one for installation. Ideally you will create all three.

A translation pack consists of an xml file, a blank index file and a set of *.ini files containing the language strings for your language. The easiest way to understand this structure is to look at the files in the language/en-GB folder of your Joomla! installation.

This is an excerpt from en-GB.mod_login.ini

<code>

BUTTON_LOGIN=Login
BUTTON_LOGOUT=Logout
DESCLOGINFORM=This Module displays a username and password Login form. It also displays a link to retrieve a forgotten password. If User registration is enabled, (refer to the Global Configuration settings), then another link will be shown to invite Users to self-register.
ENCRYPT LOGIN FORM=Encrypt Login Form
FORGOT_YOUR_PASSWORD=Forgot your password?
FORGOT_YOUR_USERNAME=Forgot your username?
GREETING=Greeting
</code>

To create a package for your language you change the strings to the right of the =.

Many people find it helpful to use the [http://extensions.joomla.org/component/option,com_mtree/task,viewlink/link_id,1776/Itemid,35/ translation manager extension]. This helps by automating the creation of the files.

Language naming convention in Joomla are
language and ISO code. Use 2 letters when available. [http://www.loc.gov/standards/iso639-2/php/code_list.php The list is available here.]

[http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm This reference concerns country codes]

Because language strings may change it is best to create your packages using either [http://developer.joomla.org/code.html the nightly build or subversion].

Name of package should be: xx-XX //using your language's ISO code.

Locale:
[http://forum.joomla.org/viewtopic.php?t=25077 Information on available locales may be found here.]

If, for any reason, ini or xml language files are edited manually with a text editor, they have to be saved with the encoding UTF8 NO BOM.

For practical information on the way to make core Translation files for Joomla 1.0, please see forum: http://forum.joomla.org/viewtopic.php?f=11&t=254709.

And for Jommla 1.5 see:
[http://forum.joomla.org/viewtopic.php?f=11&t=88326&start=0 Building Extension's Language Pack for J1.5]
<noinclude>[[Category:Languages]]</noinclude>

Joomla Translation Program

2010-01-02T09:49:39Z

Jedbox: add Languages Category

'''''"...providing support for the international community is a core value of Joomla!..."'''''
[[Image:Workgroups_translation.jpg|right]]

The purpose of the Translation Team within the Production Working Group is to be a liaison between the Joomla! Translation Teams, the International Community and the other Joomla! Teams on user and technical matters relating to the translation of the Joomla! application.

The Translation Working Group carries out its work according to the [http://community.joomla.org/translations/translation-policy.html Joomla! Translation and Localization Policy].

The Translation Working Group is also called the Joomla! Translation Coordination Team. It is composed of members of the Joomla! Translation Teams.
See a list of [http://forum.joomla.org/memberlist.php?mode=group&g=47 current members here].

We have more than 50 local language coordinators representing their local teams.
See a list of [http://forum.joomla.org/memberlist.php?mode=group&g=13 current members here].
These Teams are also listed on a per language basis: [http://community.joomla.org/translations.html current languages here]

The resources provided by these teams are available on a common repository on joomlacode: [http://joomlacode.org/gf/project/jtranslation/frs/ 1.5 language packs]

== How can you help? ==

Joomla! Project wish to see the Joomla! CMS made available in any language.

For that to become possible we need the help from talented native speakers who wish to contribute by translating Joomla! 1.5 language packages into their native language.

To create a translation you must create a [http://docs.joomla.org/How_to_create_a_language_pack Joomla! language pack]. [[Technical Guidelines for Translation]]

In case your language is not currently available at this list [http://joomlacode.org/gf/project/jtranslation/frs/ at joomlacode] and you have already created a local translation then please follow these steps:

1. Create a user and a new project at [http://joomlacode.org/gf/ joomlacode]

2. When project approved and you have uploaded your language files then please post in the Translation forum

Should your language already be listed and you wish to contribute then please start by contacting [http://community.joomla.org/translations.html the local Translation Coordinator] .

If your language is not listed and you want to join the Joomla! Translation Teams, please contact [http://forum.joomla.org/memberlist.php?mode=group&g=47 a member of the Coordination].

== Do you have language and/or translation questions? ==

For questions about language please visit language forums at:

[[jforum:309|Joomla! 1.0.x language forum]]

[[jforum:485|Joomla! 1.5.x language forum]]

For questions about translation please visit translation forum at:

[[jforum:11|Translations]]

Thanks.

<noinclude>
[[Category:Translations Working Group]]
[[Category:Languages]]
</noinclude>

Intermediate Selenium Example

2009-12-21T19:13:32Z

Jedbox:

== Writing a More Advanced Selenium Test ==

Now that you have created your first simple test, let's try something a little more advanced.

Let's write a test that verifies the functionality of creating and deleting a user.

We will start by browsing to the login screen of the administrator panel of our Joomla site.

Then, we will open up [http://docs.joomla.org/Functional_Testing Selenium] IDE.

You should notice that the record button is highlighted, which means we are recording.

Go back to the main browser window and enter the username and password for a Super Administrator user.

* Click Site, and select User Manager
* Click New
* Enter some details, such as:
** Name: My Test User
** Username: TestUser
** E-mail: test@example.com
** Password: password
** Group: Registered
* Click Save
* Highlight the text 'Successfully saved User: My Test User'
* Right Click and Select 'assertTextPresent Successfully saved User: My Test User'
* Enter TestUser into the Filter text box and click Go
* Highlight the username TestUser, right click and Select 'AssertText'
* Right click on the User link and select 'AssertText'
* Browse to the frontend of your site
* Go to the Login form and enter your credentials, and click Login
* Highlight the text 'Hi TestUser', right click and select 'AssertTextPresent 'Hi TestUser'
* Click Logout
* Browse to the admin panel of your site
* Go the user manager
* Select the Checkbox for 'My Test User'
* Click Delete
* Click Logout

And we're done recording.

Now, due to some quirks in Selenium, there are some things that we need to fix. There are two main quirks that we need to look at:
1. For some reason, entering the password in the administrator does not get recorded. We have to add a manual command for this.
2. Selenium often misses the step of going to a new URL via the browser address bar. We have to add these manually.

To fix the first problem, we do the following
* Click on the first 'ClickAndWait' (with Target link=Login).
* Right Click and select 'Insert New Command'
* The command should be Type, the Target should be modlgn_passwd and the Value should be the password for your admin user.

To fix the second problem:
* scroll down through your command list until you find the second type - modlgn_username. click on this command.
* Right Click and select 'Insert New Command'
* The command should be open, and the Target should be the path to your Joomla frontend.
* scroll down through your command list until you find clickAndWait - link=User Manager
* Enter a new command there also - the command should be open, and the Target should be the path to your Joomla Administrator panel.

Your test should then be ready to go.

[[Category:Testing]]

System Testing

2009-12-13T20:37:08Z

Jedbox: /* Running Functional Tests */

== News and Updates ==
2009 07 27 Document created.

== Functional Testing ==
Functional (or system) testing is an essential part of a good Quality Control program.
For a good general discussion of functional testing, visit the [http://en.wikipedia.org/wiki/Functional_Testing Wikipedia article].

=== Functional Testing in Open Source ===
Web applications have been notoriously difficult to do functional testing with. It has traditionally required a great deal of time and effort. This can be a special challenge for open source projects because testing is often not very popular and designing tests that can be executed in a systematic way even less so. For a complicated application like Joomla!, this means that although we might do testing, we very seldom are able to perform extensive testing on each release that covers even a fraction of the elements in the CMS.

Relatively recently, a project called Selenium has arrived on the scene. This project makes performing automated functional testing of web applications possible. This means that it is possible to devise a test and have it performed in an automated way without the requirement of somebody sitting in front of a browser and being a click monkey.

The benefits of functional testing are:
* Functional tests help highlight cases where changes in one element of the system might cause breakage in other, unexpected areas.
* Functional tests help clearly specify how the application should behave.

=== Functional Testing versus Unit Testing ===
In order to fully test an application, both functional and unit testing are essential. Each approach has their benefits and weaknesses. Unit testing is very good for isolating small chunks of code and ensuring that they are behaving as expected. Functional testing, on the other hand, is geared towards looking at the system as a whole and ensuring that the units are behaving together in a way that achieves the desired effect.

The advantages of functional testing is that functional tests are easier to understand and conceptualize by people who are unfamiliar with the underlying code. With Selenium, tests can be designed by people who are not overly familiar with PHP - they only need to understand the application and what results should be expected.

The downside of functional testing is that it will only tell you that something broke. It isn't as obvious with functional testing exactly what went wrong or where the problem is.

==== Test Objects ====
If the purpose of unit tests is to isolate a module of code, then the purpose of functional tests is to evaluate the entire system. This is much easier for those unfamiliar with what happens under the hood of Joomla! because one is not required to understand what happens during a Joomla! page request. A functional test might evaluate, for example, if unpublishing an article works properly. Therefore, to design the test, it is only necessary to figure out how to change an article from Published to Unpublished, and how to verify that the article was actually unpublished.

=== Functional Testing in Joomla! ===
I have recently been building a functional testing architecture that will make it possible to write tests once, and to execute those tests on a variety of platforms and clients. I currently have infrastructure in place that makes it possible to run one command and execute functional tests in one browser on one host system. I have designed the host system in such a way that it will run on 6 different PHP versions (stock Ubuntu PHP 5 and self-compiled PHP 4.3, 4.4, 5.0, 5.1 and 5.2) and 2 different web servers (Apache and Lighttpd). These are all currently serving from the same database.

The future steps will be to make it possible to run on multiple host systems (the requirement for this is to generalize the code that resets the database state after the tests are run) and to make it possible to use different clients (i.e. different systems with different web browsers). These steps should be fairly trivial, but I have not yet had time to focus on them.

This will eventually make it possible to run the designed tests on every major browser and on multiple server platforms (various PHP versions, various configurations, various operating systems and various web servers).

==== Writing Functional Tests ====
Selenium IDE makes it fairly easy to write functional tests. It is a Firefox extension that operates as an Integrated Development Environment for creating functional tests. In essence, it records your clicks as you navigate in your browser and encodes them into a series of commands that can control the browser.

===== Getting Selenium IDE =====
At the time of writing, the latest version of Selenium IDE is 1.0.2. You can get it at http://seleniumhq.org/download/. Click on the download link and install like you would any Firefox plugin.

===== Preparing your Environment =====
To get started, create a vanilla install of Joomla! with the standard sample data.

===== Creating a Basic Test =====
To start, open Firefox and browse to the home page of your Joomla! install. I setup my install on my localhost, and so the URL is http://127.0.0.1/selsampledata.

Then, click on Tools -> Selenium IDE. You will notice that on the right of the window that appears near the top, that there is a red circle that is highlighted. This is the start/stop recording button. When you start Selenium IDE, recording starts right away.

For our first test, all we will do is load up the home page and check to make sure that all the items in the Main Menu are present.

The commands that we use to check that items are present are called assertions. Basically, you perform your actions and make assertions about the results.

In our case, we are going to use the command assertText. This command will read the text of a specified element and ensure it matches a particular value.

So, first ensure that the Base URL displayed in the Selenium IDE window is the home page of your Joomla! install.

Then, switch to the window that has your Joomla install open.

In that window, right click on each menu item and select 'Assert Text'.

Then, switch to your Selenium IDE window and click the Red Button to stop recording.

You should see two tabs in your Selenium IDE window - one labeled Table, and one labeled Source. You don't really need to look at the Source window.

So, now our first test is done.

To run your test, you use the icons on the bar between the Base URL address bar and the Table and Source tabs. The two important buttons are the buttons with the Green Triangle with Three Solid rectangles and the one with the Green Triangle and One Solid Rectangle. The first one will execute the entire test suite and the second one will run the currently selected test case. Since we currently have only one test case, both of these currently do the same thing.

To run your test, press one of these buttons.

As you watch the Selenium IDE, you will see a yellow bar move down your list of steps. Once a step is completed, a successfully executed action (i.e. a button was successfully located and clicked) should show up in light green and a successful assertion should show up in darker green. Failed actions show up in light red and failed assertions show up in darker red.

Click on the Window Expander on the left to unhide the Test Case browser.

If your test completed successfully, you should see Runs: 1, Failures: 0 at the bottom of the Test Case browser.

==== Running Functional Tests ====

=== Joomla Core Selenium testcases ===
The testing repository for the Selenium test suite can be found here:

* [http://joomlacode.org/svn/joomla/testing/trunk/1.5/functionaltest/selenium/ http://joomlacode.org/svn/joomla/testing/trunk/1.5/functionaltest/selenium/]
* [http://joomlacode.org/svn/joomla/testing/trunk/1.6/functionaltest/selenium/ http://joomlacode.org/svn/joomla/testing/trunk/1.6/functionaltest/selenium/]

Note: If a login mask comes up, use </br>
:User: anonymous </br>
:Password: <empty>

== How to Get it Running ==

== Troubleshooting ==

== Frequently Asked Questions ==

==See also==
For writing a more advanced Selenium testcase see [http://docs.joomla.org/Intermediate_Selenium_Example here].

[http://seleniumhq.org/docs/ Selenium documentation].

[[Category:Development]]
[[Category:Testing]]
[[Category:Bug Squad]]

Unit Testing

2009-12-13T20:22:29Z

Jedbox: /* See also */

{{cookiejar}}
== News and Updates ==
2009 10 06: Tests now depend on the SVN version of PHPUnit 3.4.1.

2008 06 24: Update to reflect move of PHPUnit code from branch to trunk (former trunk now in /branches/old_simpletest).

2008 06 22: Add information on limiting tests by version.

2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with [http://seleniumhq.org/ Selenium], a browser based test automation tool. Writing a functional test using Selenium is documented [http://docs.joomla.org/Functional_Testing#Writing_Functional_Tests here].

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk used to contain code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

The PHPUnit tests are available from '''/testing/trunk'''. Some new tests have been added, any remaining tests from the SimpleTest days are completely broken. See /testing/branches/old-simpletest if you need to run something from that suite.

The unit tests are located in two places:
* /testing/trunk/1.5/unittest - these are tests for Joomla! 1.5 (/development/releases/1.5)
* /testing/trunk/1.6/unittest - there are tests for Joomla! 1.6 (/development/trunk)

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.

==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-Test.php, for example JObject-0000-class-Test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.
* The custom test runner is no longer needed. The current tests will run with the latest SVN version of PHPUnit 3.4. This code will eventually become PHPUnit 3.4.1. Thanks to Sebastian Bergmann for his excellent work on an excellent project!

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]], [[Unit_Testing_--_UI_Example|UI Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-Test.php, for example JObject-0000-class-Test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-Test.php.

Joomla unit tests use the standard PHPUnit test runner. See http://www.phpunit.de for documentation.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation. Since you will be using SVN to check out the testing project, you don't want to check out the Joomla! with SVN. Instead, simply unpack a normal Joomla! archive. If you are using Eclipse, you can create a folder in your Eclipse workspace for the Joomla! installation, but don't create an Eclipse project yet.
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/trunk/1.5/unittest"'' or ''"/testing/trunk/1.6/unittest"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation. If you are using Eclipse, Import the project from the SVN and use the same folder in your Eclipse workspace you used above.
* From the command line, change to the unittest directory.
* Run the unit test from the command prompt using the following command: <code>phpunit tests</code>

The unit test will the run, and the results are rendered. You will see a series of dots for each passed test and other letters for failed tests.

See http://www.phpunit.de/manual/current/en/textui.html for help using the --filter switch to run only certain tests. There are also many other command line switches you can use to get results in various formats.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like below, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/manual/current/en/ PHPUnit Manual]

[[Category:Development]]
[[Category:Testing]]

Intermediate Selenium Example

2009-12-13T20:21:17Z

Jedbox: /* Writing a More Advanced Test */

== Writing a More Advanced Selenium Test ==

Now that you have created your first simple test, let's try something a little more advanced.

Let's write a test that verifies the functionality of creating and deleting a user.

We will start by browsing to the login screen of the administrator panel of our Joomla site.

Then, we will open up Selenium IDE.

You should notice that the record button is highlighted, which means we are recording.

Go back to the main browser window and enter the username and password for a Super Administrator user.

* Click Site, and select User Manager
* Click New
* Enter some details, such as:
** Name: My Test User
** Username: TestUser
** E-mail: test@example.com
** Password: password
** Group: Registered
* Click Save
* Highlight the text 'Successfully saved User: My Test User'
* Right Click and Select 'assertTextPresent Successfully saved User: My Test User'
* Enter TestUser into the Filter text box and click Go
* Highlight the username TestUser, right click and Select 'AssertText'
* Right click on the User link and select 'AssertText'
* Browse to the frontend of your site
* Go to the Login form and enter your credentials, and click Login
* Highlight the text 'Hi TestUser', right click and select 'AssertTextPresent 'Hi TestUser'
* Click Logout
* Browse to the admin panel of your site
* Go the user manager
* Select the Checkbox for 'My Test User'
* Click Delete
* Click Logout

And we're done recording.

Now, due to some quirks in Selenium, there are some things that we need to fix. There are two main quirks that we need to look at:
1. For some reason, entering the password in the administrator does not get recorded. We have to add a manual command for this.
2. Selenium often misses the step of going to a new URL via the browser address bar. We have to add these manually.

To fix the first problem, we do the following
* Click on the first 'ClickAndWait' (with Target link=Login).
* Right Click and select 'Insert New Command'
* The command should be Type, the Target should be modlgn_passwd and the Value should be the password for your admin user.

To fix the second problem:
* scroll down through your command list until you find the second type - modlgn_username. click on this command.
* Right Click and select 'Insert New Command'
* The command should be open, and the Target should be the path to your Joomla frontend.
* scroll down through your command list until you find clickAndWait - link=User Manager
* Enter a new command there also - the command should be open, and the Target should be the path to your Joomla Administrator panel.

Your test should then be ready to go.

[[Category:Testing]]

System Testing

2009-12-13T20:20:25Z

Jedbox: /* See also */

== News and Updates ==
2009 07 27 Document created.

== Functional Testing ==
Functional (or system) testing is an essential part of a good Quality Control program.
For a good general discussion of functional testing, visit the [http://en.wikipedia.org/wiki/Functional_Testing Wikipedia article].

=== Functional Testing in Open Source ===
Web applications have been notoriously difficult to do functional testing with. It has traditionally required a great deal of time and effort. This can be a special challenge for open source projects because testing is often not very popular and designing tests that can be executed in a systematic way even less so. For a complicated application like Joomla!, this means that although we might do testing, we very seldom are able to perform extensive testing on each release that covers even a fraction of the elements in the CMS.

Relatively recently, a project called Selenium has arrived on the scene. This project makes performing automated functional testing of web applications possible. This means that it is possible to devise a test and have it performed in an automated way without the requirement of somebody sitting in front of a browser and being a click monkey.

The benefits of functional testing are:
* Functional tests help highlight cases where changes in one element of the system might cause breakage in other, unexpected areas.
* Functional tests help clearly specify how the application should behave.

=== Functional Testing versus Unit Testing ===
In order to fully test an application, both functional and unit testing are essential. Each approach has their benefits and weaknesses. Unit testing is very good for isolating small chunks of code and ensuring that they are behaving as expected. Functional testing, on the other hand, is geared towards looking at the system as a whole and ensuring that the units are behaving together in a way that achieves the desired effect.

The advantages of functional testing is that functional tests are easier to understand and conceptualize by people who are unfamiliar with the underlying code. With Selenium, tests can be designed by people who are not overly familiar with PHP - they only need to understand the application and what results should be expected.

The downside of functional testing is that it will only tell you that something broke. It isn't as obvious with functional testing exactly what went wrong or where the problem is.

==== Test Objects ====
If the purpose of unit tests is to isolate a module of code, then the purpose of functional tests is to evaluate the entire system. This is much easier for those unfamiliar with what happens under the hood of Joomla! because one is not required to understand what happens during a Joomla! page request. A functional test might evaluate, for example, if unpublishing an article works properly. Therefore, to design the test, it is only necessary to figure out how to change an article from Published to Unpublished, and how to verify that the article was actually unpublished.

=== Functional Testing in Joomla! ===
I have recently been building a functional testing architecture that will make it possible to write tests once, and to execute those tests on a variety of platforms and clients. I currently have infrastructure in place that makes it possible to run one command and execute functional tests in one browser on one host system. I have designed the host system in such a way that it will run on 6 different PHP versions (stock Ubuntu PHP 5 and self-compiled PHP 4.3, 4.4, 5.0, 5.1 and 5.2) and 2 different web servers (Apache and Lighttpd). These are all currently serving from the same database.

The future steps will be to make it possible to run on multiple host systems (the requirement for this is to generalize the code that resets the database state after the tests are run) and to make it possible to use different clients (i.e. different systems with different web browsers). These steps should be fairly trivial, but I have not yet had time to focus on them.

This will eventually make it possible to run the designed tests on every major browser and on multiple server platforms (various PHP versions, various configurations, various operating systems and various web servers).

==== Writing Functional Tests ====
Selenium IDE makes it fairly easy to write functional tests. It is a Firefox extension that operates as an Integrated Development Environment for creating functional tests. In essence, it records your clicks as you navigate in your browser and encodes them into a series of commands that can control the browser.

===== Getting Selenium IDE =====
At the time of writing, the latest version of Selenium IDE is 1.0.2. You can get it at http://seleniumhq.org/download/. Click on the download link and install like you would any Firefox plugin.

===== Preparing your Environment =====
To get started, create a vanilla install of Joomla! with the standard sample data.

===== Creating a Basic Test =====
To start, open Firefox and browse to the home page of your Joomla! install. I setup my install on my localhost, and so the URL is http://127.0.0.1/selsampledata.

Then, click on Tools -> Selenium IDE. You will notice that on the right of the window that appears near the top, that there is a red circle that is highlighted. This is the start/stop recording button. When you start Selenium IDE, recording starts right away.

For our first test, all we will do is load up the home page and check to make sure that all the items in the Main Menu are present.

The commands that we use to check that items are present are called assertions. Basically, you perform your actions and make assertions about the results.

In our case, we are going to use the command assertText. This command will read the text of a specified element and ensure it matches a particular value.

So, first ensure that the Base URL displayed in the Selenium IDE window is the home page of your Joomla! install.

Then, switch to the window that has your Joomla install open.

In that window, right click on each menu item and select 'Assert Text'.

Then, switch to your Selenium IDE window and click the Red Button to stop recording.

You should see two tabs in your Selenium IDE window - one labeled Table, and one labeled Source. You don't really need to look at the Source window.

So, now our first test is done.

To run your test, you use the icons on the bar between the Base URL address bar and the Table and Source tabs. The two important buttons are the buttons with the Green Triangle with Three Solid rectangles and the one with the Green Triangle and One Solid Rectangle. The first one will execute the entire test suite and the second one will run the currently selected test case. Since we currently have only one test case, both of these currently do the same thing.

To run your test, press one of these buttons.

As you watch the Selenium IDE, you will see a yellow bar move down your list of steps. Once a step is completed, a successfully executed action (i.e. a button was successfully located and clicked) should show up in light green and a successful assertion should show up in darker green. Failed actions show up in light red and failed assertions show up in darker red.

Click on the Window Expander on the left to unhide the Test Case browser.

If your test completed successfully, you should see Runs: 1, Failures: 0 at the bottom of the Test Case browser.

==== Running Functional Tests ====

== How to Get it Running ==

== Troubleshooting ==

== Frequently Asked Questions ==

==See also==
For writing a more advanced Selenium testcase see [http://docs.joomla.org/Intermediate_Selenium_Example here].

[http://seleniumhq.org/docs/ Selenium documentation].

[[Category:Development]]
[[Category:Testing]]
[[Category:Bug Squad]]

System Testing

2009-12-13T20:16:10Z

Jedbox: /* See also */

== News and Updates ==
2009 07 27 Document created.

== Functional Testing ==
Functional (or system) testing is an essential part of a good Quality Control program.
For a good general discussion of functional testing, visit the [http://en.wikipedia.org/wiki/Functional_Testing Wikipedia article].

=== Functional Testing in Open Source ===
Web applications have been notoriously difficult to do functional testing with. It has traditionally required a great deal of time and effort. This can be a special challenge for open source projects because testing is often not very popular and designing tests that can be executed in a systematic way even less so. For a complicated application like Joomla!, this means that although we might do testing, we very seldom are able to perform extensive testing on each release that covers even a fraction of the elements in the CMS.

Relatively recently, a project called Selenium has arrived on the scene. This project makes performing automated functional testing of web applications possible. This means that it is possible to devise a test and have it performed in an automated way without the requirement of somebody sitting in front of a browser and being a click monkey.

The benefits of functional testing are:
* Functional tests help highlight cases where changes in one element of the system might cause breakage in other, unexpected areas.
* Functional tests help clearly specify how the application should behave.

=== Functional Testing versus Unit Testing ===
In order to fully test an application, both functional and unit testing are essential. Each approach has their benefits and weaknesses. Unit testing is very good for isolating small chunks of code and ensuring that they are behaving as expected. Functional testing, on the other hand, is geared towards looking at the system as a whole and ensuring that the units are behaving together in a way that achieves the desired effect.

The advantages of functional testing is that functional tests are easier to understand and conceptualize by people who are unfamiliar with the underlying code. With Selenium, tests can be designed by people who are not overly familiar with PHP - they only need to understand the application and what results should be expected.

The downside of functional testing is that it will only tell you that something broke. It isn't as obvious with functional testing exactly what went wrong or where the problem is.

==== Test Objects ====
If the purpose of unit tests is to isolate a module of code, then the purpose of functional tests is to evaluate the entire system. This is much easier for those unfamiliar with what happens under the hood of Joomla! because one is not required to understand what happens during a Joomla! page request. A functional test might evaluate, for example, if unpublishing an article works properly. Therefore, to design the test, it is only necessary to figure out how to change an article from Published to Unpublished, and how to verify that the article was actually unpublished.

=== Functional Testing in Joomla! ===
I have recently been building a functional testing architecture that will make it possible to write tests once, and to execute those tests on a variety of platforms and clients. I currently have infrastructure in place that makes it possible to run one command and execute functional tests in one browser on one host system. I have designed the host system in such a way that it will run on 6 different PHP versions (stock Ubuntu PHP 5 and self-compiled PHP 4.3, 4.4, 5.0, 5.1 and 5.2) and 2 different web servers (Apache and Lighttpd). These are all currently serving from the same database.

The future steps will be to make it possible to run on multiple host systems (the requirement for this is to generalize the code that resets the database state after the tests are run) and to make it possible to use different clients (i.e. different systems with different web browsers). These steps should be fairly trivial, but I have not yet had time to focus on them.

This will eventually make it possible to run the designed tests on every major browser and on multiple server platforms (various PHP versions, various configurations, various operating systems and various web servers).

==== Writing Functional Tests ====
Selenium IDE makes it fairly easy to write functional tests. It is a Firefox extension that operates as an Integrated Development Environment for creating functional tests. In essence, it records your clicks as you navigate in your browser and encodes them into a series of commands that can control the browser.

===== Getting Selenium IDE =====
At the time of writing, the latest version of Selenium IDE is 1.0.2. You can get it at http://seleniumhq.org/download/. Click on the download link and install like you would any Firefox plugin.

===== Preparing your Environment =====
To get started, create a vanilla install of Joomla! with the standard sample data.

===== Creating a Basic Test =====
To start, open Firefox and browse to the home page of your Joomla! install. I setup my install on my localhost, and so the URL is http://127.0.0.1/selsampledata.

Then, click on Tools -> Selenium IDE. You will notice that on the right of the window that appears near the top, that there is a red circle that is highlighted. This is the start/stop recording button. When you start Selenium IDE, recording starts right away.

For our first test, all we will do is load up the home page and check to make sure that all the items in the Main Menu are present.

The commands that we use to check that items are present are called assertions. Basically, you perform your actions and make assertions about the results.

In our case, we are going to use the command assertText. This command will read the text of a specified element and ensure it matches a particular value.

So, first ensure that the Base URL displayed in the Selenium IDE window is the home page of your Joomla! install.

Then, switch to the window that has your Joomla install open.

In that window, right click on each menu item and select 'Assert Text'.

Then, switch to your Selenium IDE window and click the Red Button to stop recording.

You should see two tabs in your Selenium IDE window - one labeled Table, and one labeled Source. You don't really need to look at the Source window.

So, now our first test is done.

To run your test, you use the icons on the bar between the Base URL address bar and the Table and Source tabs. The two important buttons are the buttons with the Green Triangle with Three Solid rectangles and the one with the Green Triangle and One Solid Rectangle. The first one will execute the entire test suite and the second one will run the currently selected test case. Since we currently have only one test case, both of these currently do the same thing.

To run your test, press one of these buttons.

As you watch the Selenium IDE, you will see a yellow bar move down your list of steps. Once a step is completed, a successfully executed action (i.e. a button was successfully located and clicked) should show up in light green and a successful assertion should show up in darker green. Failed actions show up in light red and failed assertions show up in darker red.

Click on the Window Expander on the left to unhide the Test Case browser.

If your test completed successfully, you should see Runs: 1, Failures: 0 at the bottom of the Test Case browser.

==== Running Functional Tests ====

== How to Get it Running ==

== Troubleshooting ==

== Frequently Asked Questions ==

==See also==
For writing a more advanced Selenium testcase see [http://docs.joomla.org/Intermediate_Selenium_Example here].

[http://seleniumhq.org/docs/ Selenium documentation].

[[Category:Development]]
[[Category:Bug Squad]]

System Testing

2009-12-13T20:12:04Z

Jedbox: /* See also */

== News and Updates ==
2009 07 27 Document created.

== Functional Testing ==
Functional (or system) testing is an essential part of a good Quality Control program.
For a good general discussion of functional testing, visit the [http://en.wikipedia.org/wiki/Functional_Testing Wikipedia article].

=== Functional Testing in Open Source ===
Web applications have been notoriously difficult to do functional testing with. It has traditionally required a great deal of time and effort. This can be a special challenge for open source projects because testing is often not very popular and designing tests that can be executed in a systematic way even less so. For a complicated application like Joomla!, this means that although we might do testing, we very seldom are able to perform extensive testing on each release that covers even a fraction of the elements in the CMS.

Relatively recently, a project called Selenium has arrived on the scene. This project makes performing automated functional testing of web applications possible. This means that it is possible to devise a test and have it performed in an automated way without the requirement of somebody sitting in front of a browser and being a click monkey.

The benefits of functional testing are:
* Functional tests help highlight cases where changes in one element of the system might cause breakage in other, unexpected areas.
* Functional tests help clearly specify how the application should behave.

=== Functional Testing versus Unit Testing ===
In order to fully test an application, both functional and unit testing are essential. Each approach has their benefits and weaknesses. Unit testing is very good for isolating small chunks of code and ensuring that they are behaving as expected. Functional testing, on the other hand, is geared towards looking at the system as a whole and ensuring that the units are behaving together in a way that achieves the desired effect.

The advantages of functional testing is that functional tests are easier to understand and conceptualize by people who are unfamiliar with the underlying code. With Selenium, tests can be designed by people who are not overly familiar with PHP - they only need to understand the application and what results should be expected.

The downside of functional testing is that it will only tell you that something broke. It isn't as obvious with functional testing exactly what went wrong or where the problem is.

==== Test Objects ====
If the purpose of unit tests is to isolate a module of code, then the purpose of functional tests is to evaluate the entire system. This is much easier for those unfamiliar with what happens under the hood of Joomla! because one is not required to understand what happens during a Joomla! page request. A functional test might evaluate, for example, if unpublishing an article works properly. Therefore, to design the test, it is only necessary to figure out how to change an article from Published to Unpublished, and how to verify that the article was actually unpublished.

=== Functional Testing in Joomla! ===
I have recently been building a functional testing architecture that will make it possible to write tests once, and to execute those tests on a variety of platforms and clients. I currently have infrastructure in place that makes it possible to run one command and execute functional tests in one browser on one host system. I have designed the host system in such a way that it will run on 6 different PHP versions (stock Ubuntu PHP 5 and self-compiled PHP 4.3, 4.4, 5.0, 5.1 and 5.2) and 2 different web servers (Apache and Lighttpd). These are all currently serving from the same database.

The future steps will be to make it possible to run on multiple host systems (the requirement for this is to generalize the code that resets the database state after the tests are run) and to make it possible to use different clients (i.e. different systems with different web browsers). These steps should be fairly trivial, but I have not yet had time to focus on them.

This will eventually make it possible to run the designed tests on every major browser and on multiple server platforms (various PHP versions, various configurations, various operating systems and various web servers).

==== Writing Functional Tests ====
Selenium IDE makes it fairly easy to write functional tests. It is a Firefox extension that operates as an Integrated Development Environment for creating functional tests. In essence, it records your clicks as you navigate in your browser and encodes them into a series of commands that can control the browser.

===== Getting Selenium IDE =====
At the time of writing, the latest version of Selenium IDE is 1.0.2. You can get it at http://seleniumhq.org/download/. Click on the download link and install like you would any Firefox plugin.

===== Preparing your Environment =====
To get started, create a vanilla install of Joomla! with the standard sample data.

===== Creating a Basic Test =====
To start, open Firefox and browse to the home page of your Joomla! install. I setup my install on my localhost, and so the URL is http://127.0.0.1/selsampledata.

Then, click on Tools -> Selenium IDE. You will notice that on the right of the window that appears near the top, that there is a red circle that is highlighted. This is the start/stop recording button. When you start Selenium IDE, recording starts right away.

For our first test, all we will do is load up the home page and check to make sure that all the items in the Main Menu are present.

The commands that we use to check that items are present are called assertions. Basically, you perform your actions and make assertions about the results.

In our case, we are going to use the command assertText. This command will read the text of a specified element and ensure it matches a particular value.

So, first ensure that the Base URL displayed in the Selenium IDE window is the home page of your Joomla! install.

Then, switch to the window that has your Joomla install open.

In that window, right click on each menu item and select 'Assert Text'.

Then, switch to your Selenium IDE window and click the Red Button to stop recording.

You should see two tabs in your Selenium IDE window - one labeled Table, and one labeled Source. You don't really need to look at the Source window.

So, now our first test is done.

To run your test, you use the icons on the bar between the Base URL address bar and the Table and Source tabs. The two important buttons are the buttons with the Green Triangle with Three Solid rectangles and the one with the Green Triangle and One Solid Rectangle. The first one will execute the entire test suite and the second one will run the currently selected test case. Since we currently have only one test case, both of these currently do the same thing.

To run your test, press one of these buttons.

As you watch the Selenium IDE, you will see a yellow bar move down your list of steps. Once a step is completed, a successfully executed action (i.e. a button was successfully located and clicked) should show up in light green and a successful assertion should show up in darker green. Failed actions show up in light red and failed assertions show up in darker red.

Click on the Window Expander on the left to unhide the Test Case browser.

If your test completed successfully, you should see Runs: 1, Failures: 0 at the bottom of the Test Case browser.

==== Running Functional Tests ====

== How to Get it Running ==

== Troubleshooting ==

== Frequently Asked Questions ==

==See also==
For writing a more advanced Selenium testcase see [http://docs.joomla.org/Intermediate_Selenium_Example here].

[[Category:Development]]
[[Category:Bug Squad]]

Unit Testing

2009-12-13T20:07:23Z

Jedbox: /* The Testing Hierarchy: Unit, Subsystem, Integrated */

Accessing the database using JDatabase

2009-04-14T18:20:55Z

Jedbox: /* getNumRows() */

J1.5:Manifest files

2009-03-29T19:00:05Z

Jedbox: /* Packaging */

{{review}}
{{joomla version category|1.5}}
[[Category:Development]]

== Packaging ==
The script needs to be extended for sorting your files into folders within the archive, which are needed for the Joomla! extension installer API. See the recommended file locations below:

{| border=1 cellspacing=0 cellpadding=2
|-
! Development file
! Archive folder
|-
| <tt>/components/com_<component name>/**</tt>
| <tt>/site/**</tt> (mimic folder structure)
|-
| <tt>/administrator/components/com_<component name>/**</tt>
| <tt>/admin/**</tt> (mimic folder structure)
|-
| <tt>/language/en-GB/en-GB.com_<component name>.ini</tt>
| <tt>/language/site</tt> (flatten structure: discard language code subfolders)
|-
| <tt>administrator/language/en-GB/en-GB.com_<component name>.ini</tt>
| <tt>/language/admin</tt> (flatten structure: discard language code subfolders)
|-
| <tt>install.<component name>.php</tt>
| /
|-
| <tt>uninstall.<component name>.php</tt>
| /
|-
| <tt>install.<component name>.sql</tt>
| /admin
|-
| <tt>uninstall.<component name>.sql</tt>
| /admin
|-
| <tt><component name>.xml</tt> '''The manifest file'''
| /
|}

== The Component Manifest File ==

Your component needs an xml-file declaring meta data (author, license, etc.), which files are included and indicates some special files to the installer API, like the included languages and SQL-scripts for (un)installing.

The most important xml-elements are explained below. There is a [http://dev.joomla.org/xml/1.5/component-install.dtd manifest DTD for Joomla! 1.5 components] which can be used as a guide to the syntax, but it cannot be used to validate the manifest due to a problem with the 1.5 component installer. This should be corrected for Joomla! 1.6 onwards.

=== The root element ===

<install type="''component|module|...''" method="''upgrade''">
<name>''component name''</name>
<version>''x.y''</version>
...

Enter the '''type''' of your extension, and indicate whether the installer shall be able to overwrite existing files. If the '''method''' attribute is not given, the installer will quit gracefully when encountering any existing file on the webspace.

=== The file list ===

<install>
<files folder="site">
<folder>''views''</folder>
...
<filename>''component-name.php''</file>
...

<administration>
<files folder="admin">
...

List all files which make up the code of your component, which will later go to the <tt>component</tt> subfolder of the site. Same for the administration part.

=== The language files ===

<install>
<languages folder="lang/site">
<language tag="''en-GB''">en-GB.com_''<component name>''.ini</language>
...

<administration>
<languages folder="lang/admin">
<language ...

The language files for the front-end will be copied to the respective language code subfolders. Same for the administration part.

=== SQL scripts ===

<install>
<install>
<sql>
<file driver="''mysql''">''install.component.sql''</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="''mysql''">''uninstall.component.sql''</file>
</sql>
</uninstall>

If you need tables added or altered for your component, put the statements into an sql script. The sql statements will be executed by the installer after copying of the files. Do not forget to indicate '''the way back''' and develop a script for cleaning up when the components shall be uninstalled.

=== Custom install code ===

<install>
<installfile>install.component.php</installfile>
<uninstallfile>uninstall.component.php</uninstallfile>

The code in these files will be executed by the installer upon install/uninstall. See API description below.

== Custom Installer Code API ==

If you need more to be done to the live site upon (un)installation than deploying the files, languages, and executing SQL statements, the installer files are your way. For example, you might need to update existing data entries in the tables during an upgrade installation. Indicate the scripts in the manifest file (see above), and the code will be executed after deployment.

The install script should define exactly one function:

<source lang=php>
function com_install()
</source>

The uninstall script, respectively, should also define exactly one function:

<source lang=php>
function com_uninstall()
</source>

Incorrect Install File

2009-03-29T11:47:27Z

Jedbox: /* Putting the installfile in a different directory */

This error will occur when the <installfile> tag in the XML install file for a component is incorrectly specified. Commonly this occurs when an extension developer specifies the files in their administrator files section in addition to specifying an install file. Typically this doesn't cause an issue because the installer would silently ignore the error and continue working, however due to a change in 1.5.10 to fix an issue when the tag is used properly this may cause issues with extensions that use 'method="upgrade"' for the extension install files.

The <installfile> tag itself will handle copying the file denoted by that location from the root of the installation package (where the XML install file is) to the administrator section of the component.

Everything that is stated about the installfile is the same as the uninstallfile.

== Putting the installfile in a different directory ==
Say for example you didn't want the install files to live in the root of your extension but wanted to put them in a subfolder in your administrator section. You may already be doing this for pre-1.5.10 in an incorrect way.

If you create in the root of your install package a folder matching your preferred target folder (e.g. "install") and then locate the install and uninstall files in that directory then you can specify the following:
<pre>
<installfile>install/install.php</installfile>
</pre>

Doing this alone will cause your installation to still fail because in the administrator directory there still won't be an 'install' folder created. To solve this, create an 'install' folder in your administrator folder of the package and also place an 'index.html' file into this folder. Then in the files section for the administrator put the following line:
<pre>
<folder>install</folder>
</pre>
This will automatically create the install folder for you and copy the index.html file across. Then when the installer comes to copy the install file across both the source and destination files will exist properly.
[[Category:Version 1.5.10 FAQ]]

Joomla Translation Program

2008-12-13T10:46:01Z

Jedbox: /* How can you help? */

'''''"...providing support for the international community is a core value of Joomla!..."'''''
[[Image:Workgroups_translation.jpg|right]]

The purpose of the Translation Working Group is to be a liaison between the international community and the other Joomla! Teams on user and technical matters relating to the translation of the Joomla! application.

We have more than 50 local language coordinators representing their local teams in Translation Working Group.

See a list of [http://forum.joomla.org/memberlist.php?mode=group&g=13 current members here].

[http://forum.joomla.org/memberlist.php?mode=viewprofile&u=178 Group Leader]

== How can you help? ==

Joomla! Project wish to see the Joomla! CMS made available in any language.

For that to become possible we need the help from talented native speakers who wish to contribute by translating Joomla! 1.5 language packages into their native language.

To create a translation you must create a [http://docs.joomla.org/How_to_create_a_language_pack Joomla! language pack]. [[Technical Guidelines for Translation]]

In case your language is not currently available at this list [http://joomlacode.org/gf/project/jtranslation/frs/ at joomlacode] and you have already created a local translation then please follow these steps:

1. Create a user and a new project at [http://joomlacode.org/gf/ joomlacode]

2. When project approved and you have uploaded your language files then please contact [http://forum.joomla.org/memberlist.php?mode=viewprofile&u=178 Joomla! Translation Coordinator]

Should your language already be listed and you wish to contribute then please start by contacting local Translation Coordinator.

== Do you have language and/or translation questions? ==

For questions about language please visit language forums at:

[[jforum:309|Joomla! 1.0.x language forum]]

[[jforum:485|Joomla! 1.5.x language forum]]

For questions about translation please visit translation forum at:

[[jforum:11|Translations]]

Thanks.

<noinclude>
[[Category:Translations Working Group]]
</noinclude>