Testing and Unit Testing

To allow you to write as bug free as possible web application, Pluf include a unit testing framework. Wikipedia is providing background information about unit testing.

Several unit testing framework exist, but to simplify your life, the choice has already be made for you. Pluf, by default, uses the SimpleTest testing framework. You can use another one if you want, but we are providing some helper tools for SimpleTest.

Tests are classes extending the UnitTestCase class. These classes are placed in the YourApp/Tests/ folder and follow the Pluf naming conventions. That is, the file Pluf/Tests/Fixture/LoadDump.php contains the class Pluf_Tests_Fixture_LoadDump class. For example LoadDump.php.

The test runner

To run your tests, a test runner is available.

Configure the test runner

First you need to download SimpleTest on your computer and extract the archive somewhere. Then create a copy of your application configuration file as YourApp/conf/yourapp.test.php. Do not forget to use another database or another prefix to avoid impacting your development or production databases.

In this file, set the path to SimpleTest the following way:

$cfg['simple_test_path'] = '/home/you/path/to/simpletest';

Now, the test runner is configured to use SimpleTest.

Run your tests

The test runner is run the following way:

1. Go in the folder in which the folder of your application is. For example, go in /home/you/Projects if your tests are in /Home/you/Projects/YourApp/Tests.
2. Execute the following command: $ php /path/to/testrunner.php YourApp

This will run the tests in YourApp/Tests for you.

Tools to help testing

Load test data in the database

To load test data in your database, the Pluf_Test_Fixture class is available. This class allow you to load JSON formatted data into the database.

The methods available are:

$created = Pluf_Test_Fixture::load($jsonstring);
$created = Pluf_Test_Fixture::loadFile($jsonfile);
$jsonstring = Pluf_Test_Fixture::dump($model); 
$jsonstring = Pluf_Test_Fixture::dump('Model_Name'); 

A JSON string is an array formatted the following way:

[
 {"model":"Pluf_Permission",
  "pk":1,
  "fields":{
            "id":1,
            "name":"test permission",
            "code_name":"test",
            "description":"Simple test permission.",
            "application":"Pluf"
           }
 },
 {"model":"Pluf_Permission",
  "pk":2,
  "fields":{
            "id":2,
            "name":"test permission 2",
            "code_name":"test2",
            "description":"Simple test permission 2.",
            "application":"Pluf"
           }
 }
]

model is the name of the model, pk is the primary key and then fields is an associative array of the field data.

The $created array, is just an array of pairs. Each pair, contains the model name and the primary key of the created object.

Suppose you load the example JSON string, you would get as result the following:

array(
      array('Pluf_Permission', '1'),
      array('Pluf_Permission', '2'),
     );

This allows you after your tests to easily clean your database as you know what you have created.

Preload test data

If you provide a file YourApp/Tests/init.json, this file will be loaded prior to run all the tests. After the tests, the created models, if they still exist, will be removed.

This file is load only once before the full test run. If you need to load for a single test, use the setUp and tearDown methods.

Tests the views

A special test client - Pluf_Test_Client - is available to easily test your views. With this special client, you can simulate a connection to your website without a running webserver!

For example, you can write that in your test code:

Pluf::loadFunction('Pluf_HTTP_URL_urlForView');
$url = Pluf_HTTP_URL_urlForView('YourApp_Views::index');
$client = new Pluf_Test_Client(Pluf::f('yourapp_views'));
$reponse = $client->get($url, array('optional_get_param' => 'toto'));
$this->assertEqual(200, $response->status_code);
// print $response->content;
// print_r($response->template); 

The very interesting point is that you can directly access the content of the response and if used, the template instance used to render the response. This way you can test that the context used to render your template is correct as it is available as $response->templates->context. If you have used several templates to build the response, for example, if you have used one template for the response page and one to send an email, $response->template will be an array of template instances.

What is really practical is that the client is stateful, that is, you can use it to login you in and then access a page which requires to be signed in:

$client->post('/login/', array('login' => 'toto', 
                               'password' => 'secret'));
$client->get('/privatepage/');

You should use the Pluf_HTTP_URL_urlForView function to generate the URLs to avoid hard coding URLs.

Report issues in the documentation

If you find errors or issues in the documentation, report a bug with the label Component-Docs. We will update the documentation accordingly.