Introduction

What are tests?

Tests are organized into PHP classes called *test cases* that are stored within protected/tests/unit (unit tests) or protected/tests/functional (functional tests). Test cases extend one of the following classes:

CTestCase

For ordinary, non-databse unit tests; best for component classes that don't rely on tables or data that is specific to a HTTP request

CDbTestCase

For tests involving communication with a MySQL database, especially if that communication involves a change in any data.

WebTestCase (extends CWebTestCase)

For tests that involve web browser actions.

Anatomy of a typical test case

Running test cases

phpunit path/to/TestCase.php

phpunit directory/

Installation

For the most up-to-date information on how to install PHPUnit, see Chapter 3: Installing PHPUnit in the official PHPUnit manual. In addition to PHPUnit, you will need each of the following PHPUnit extensions:

• DBUnit
• PHP_Invoker
• PHPUnit_Selenium
• PHPUnit_Story

See the installation guide for more information on how to obtain these extensions.

Setting up a test database

A few very important points to note about tests involving a database connection:

• A different database will be used than the live database
• The contents of each of the test database's tables will be fixed at the beginning of each test using *fixtures*
• All database records generated during tests or through manual interaction will be purged when fixtures for the table in question are used

After creating the test database, the following steps can be used to set it up for database testing:

1. Copy the installer files back into the root of the web application: index.php, initialize.php, requirements.php, and initialize_pro.php if on professional edition.
2. Re-run the installer, but enable "Testing Database".

Functional Testing with Selenium

An advanced PHPUnit/Selenium configuration involving multiple network hosts, operating systems and web browsers. PHPUnit (1) begins a test by starting browser sessions on a remote host running Selenium RC (2). Selenium then commands the web browsers to open the web application in testing mode (3) and run automated instructions, sending results back to PHPUnit (i.e. whether a test has passed or failed). All logos are © their respective owners.

If it is desired to automate in-browser tests, the following conditions must be ensured:

1. The <selenium> section in the configuration file protected/tests/phpunit.xml is set properly. For information on how to configure this, see The PHPUnit Manual Appendix C: The XML Configuration File
2. Selenium RC on all the hosts defined in phpunit.xml are accessible from the web server on the specified ports (note: if they are behind a firewall, it will be necessary to set up NAT in order to properly use them)
3. The URL defined as constant TEST_BASE_URL in protected/tests/WebTestConfig.php resolves properly (points to index-test.php/ on the web server).
4. PHPUnit and the necessary extensions are installed on the web server

Creating Selenium test cases

1. Create a class that extends WebTestCase
2. Note that at the beginning of the execution of a test case's method, the method WebTestCase::setUp will be called, and this will create a session as the admin user.
3. In the test method, open the URL where the test is to begin by calling WebTestCase::openX2(), passing it as an argument the URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root relative to the base URL (what would come after index-test.php).
4. Note the availability of CWebTestCase's methods, especially those inherited from PHPUnit_Framework_TestCase, PHPUnit_Framework_Assert and PHPUnit_Extensions_SeleniumTestCase, in addition to WebTestCase::session() (which will ensure the session matches the user/password defined in WebTestCase::$login, logging the browser out/in as necessary) and the aforementioned methods that will be inherited from WebTestCase.

Using test cases built with Selenium IDE

Building functional tests involving browser automation with Selenium can be done with PHPUnit browser commands, i.e. assertTextPresent. However, it is far more easy, convenient and quick to build them using Selenium IDE. To run a native Selenese .html test case created in Selenium IDE:

1. Save the .html in the same folder as the PHP test case class.
2. In the test method, open the URL where the Selenese test case is to begin.
3. Call the method WebTestCase::localSelenese() with the filename of the Selenese test case as the sole argument.