View source for Test Suite

Geeklog has its own [http://en.wikipedia.org/wiki/Unit_testing) unit testing] suite, powered by [http://www.phpunit.de/ PHPUnit]. You can see the logging features being used at the [http://project.geeklog.net/ttt/tests/index_js.php Geeklog project site].


== What can it do? ==

Using the test suite, you can run tests on the existing code, ensuring that the code continues to do exactly what it is supposed to do in a variety of scenarios. The suite uses a GUI, which displays existing tests that can be run, returns PHPUnit's console output, and stores the results to log files that can be viewed at any time. 


== How do I use it? ==

== '''Running tests''' ==

You have two ways you can run your tests. One is by using a simple GUI included with the test package, and the second is by using the console. 

'''Note: the GUI only fully supports Firefox >3 with javascript enabled.'''

To use the GUI, navigate with your browser to the tests folder in your Geeklog site (e.g: http://localhost/public_html/tests). You should be at a page called 'index_js.php'. Under the left panel titled 'Run Tests' is a tree structure of all available tests for the Geeklog test framework. Select any number of tests you like (if you choose a folder, all the tests inside will be included), choose whether to have the console output returned, logs created, and logs immediately shown, and click 'Run Tests'. It may take a few minutes, so be patient.

To use your tests using your console, open the console and navigate to the public_html/tests folder. From here, you can type 'phpunit (path/to/testclass/testname)', and the test you specify will be run, with the results displayed in the console. If you specify a folder, all tests inside will be run. Running tests this way will not create logs or interact with the suite.

'''Note: this will only work if you are in the tests root folder (with tst.class.php). This is because of the path structure.''' 

You can find more information on running tests in the [http://www.phpunit.de/manual/3.3/en/textui.html PHPUnit manual].


== '''Viewing and deleting logs''' ==

If you are running tests with the GUI, the event will be logged in testpackage/logs/masterlog.txt, and JSON logs will be created in the same folder with information for the event. You can view these logs using the 'View logs' panel in the GUI - select the logs you want to view and press 'View'. Alternatively, you can delete old logs by selecting the logs and - you got it - pressing 'Delete'.


== Advanced details ==

== '''Structure''' ==

Here is the file structure of the test suite:    

    -testpackage (files which should be outside webroot)
        -files
            -classes (Geeklog test framework classes)
            -databases (XML 'dummy' databases for testing use)
            -dummy (Dummy file structure, this makes the test framework run on Geeklog files without Geeklog needing to be installed)
        -logs (Logs of tests run)
        -suite (This is where all the test classes are actually stored)
            -geeklog
                -public_html
                -system
                    -classes
    -tests (This should be in your webroot)
        -gui (Files for GUI)
           -css
           -development-bundle
           -images
           -js
        -jobs (Scripts which can be pointed at by GUI and cronjobs to interact with test framework)

== ''' Working with databases''' ==
   
This test package is designed to work with or without a Geeklog install. It does this by using the configuration paths you specified in the installation, and by using a XML version of Geeklog's SQL database. To write tests for a file requiring database calls, first ensure that default.xml exists (in testpackage/files/databases). This is the XML version of Geeklog's database, as appears after a fresh install. The class that handles the operations (done with simpleXML and xPath) on the database is xmldb.class.php, under testpackage/files/databases. 
    
You can use xmldb.class.php in three steps.
1. Require tst.class.php, e.g: require_once 'tst.class.php'. You should be doing this anyway.
2. Require the file, e.g: require_once Tst::$tests.'/files/databases/xmldb.class.php'. 
3. Create an object, e.g: $this->xml = new Xmldb;
4. Call the function you want, providing the database you want to load as the parameter, e.g: $_CONF = $this->xml->get_CONF('database'). If you don't specify a database, it will load default.xml.
    
== '''3. Adding tests''' ==

This will integrate new PHPUnit tests with the Geeklog test framework, (for example, if you wanted to write your own tests for Geeklog files and add them to the suite).

1) Save your test to the correct folder. Under testpackage/suite is a folder named 'geeklog'. This contains tests for Geeklog files in a folder structure mirroring that of a typical Geeklog installation. For example, lib-common.php is located under geeklog/public_html, so you would save its test under testpackage/files/suite/geeklog/public_html.  Name it as [filename]Test.php (a test for lib-common would be lib-commonTest.php).
    
2) Add these lines at the beginning of your file:
 require_once 'PHPUnit/Framework.php';
 require_once 'tst.class.php';        
These will implement the PHPUnit framework and Geeklog's framework config file.

3) Now, require the class you are writing a test for, e.g:
 require_once Tst::$root.'system/lib-mbyte.php';
If you are using the XML database, add this line:
 require_once Tst::$tests.'files/classes/xmldb.class.php';                
Your test should be ready to run!

== '''4. Adding jobs''' ==

With a few lines of code, you can interact with the Geeklog test framework's test running and logging system. These scripts are typically stored under tests/gui/jobs. You can browse through the existing scripts and tests.class.php to see how they work and are implemented. Let's take 'tests/gui/jobs/runAll.php' as an example.  
  
1) These two lines at the beginning of the script include Geeklog's test framework configuration file and tests class:
 require_once 'tst.class.php';
 require_once Tst::$tests.'files/classes/tests.class.php';
2) This creates an instance of tests.class.php:
 $tests = new Tests;
3) Now we can perform any action on the test framework already scripted in tests.class.php, if you need to do something not already provided in this class, add it if you think it may be useful to other people. If it's something that will only be used once, just put it in the script. In this example, we tell $tests->runTests() to run tests on all files under 'suite', create a JSON log for the output, and discard the console output. A cronjob could be pointed at this and run it on a specified schedule.