Writing test cases

From Invenzzia wiki

For unit testing, we use the PHPUnit package. The installation instructions can be found on the package website, and here we would like to describe, how to write unit tests for bugtracking purposes.

Contents 1 Why write unit tests? 2 How the unit test should be constructed? 3 Invenzzia test filesystem 4 Open Power Template 2 tests 4.1 Instruction and template tests 4.2 Expression tests

Why write unit tests?

If you provide a unit test for the bug description, you can easily include the encountered problem into our test chain. It will become a part of the testing procedure which must be passed by every release before it is published. Thus, you may be sure that the future versions will not destroy something accidentaly that previously worked. The test also helps the bug maintainer to solve the problem, as he or she can simply download the file into the computer and run the test procedure. PHPUnit performs the tests automatically and will show the maintainer when the bug is fixed.

Another advantage of unit tests is that they are performed and checked automatically and no human attention is needed. The programmer may simply run the testing procedure, make some coffee, and if there are no problems reported, publish the code.

How the unit test should be constructed?

Each unit test checks a single feature or use case. We must provide an algorithm and specify, what output should be produced by it. For example:

$result = 2 + 2;
$expected = 4;
 
if($result == $expected)
{
   echo 'OK';
}

Any other result is not possible and if it occurs, the testing package must show that the produced output is invalid and basically we have a bug. This is a point of the unit tests - we force the tested item to perform a certain action which should produce a strictly defined result. If the expected and actual results do not match, a warning is generated.

Please note that the unit tests may contain the bugs, too. If we write a unit test that expects strange results, the testing procedure will be expecting invalid data and generating warnings even for the output that is correct. Before publishing a unit test, please check it, too.

Invenzzia test filesystem

To provide a portable and easy-to-deploy environment for the tests, we have developed a simple "testing filesystem". It is currently used by Open Power Template 2 testing procedure and allows to pack several files the test consists of into one, plain text file. Below, you can find a description of the test file:

Test description
 
>>>>file1.txt
file1 contents
 
>>>>file2.txt
file2 contents
 
>>>>directory/file3.txt
file 3 contents...

In other words, you start a new "file" with the >>>>filename string, then you write its content starting from the new line. At the beginning, you can place a description.

Open Power Template 2 tests

All the tests that check the template syntax in OPTv2 are constructed using the "Invenzzia filesystem". They have been splitted into several groups:

1. Instruction tests - check the instructions.
2. XML tests - check the XML parsing.
3. Feature tests - check the other syntax features.
4. Expression tests - check the expression syntax.

To add a unit test to the testing procedure, you have to edit one of the xxxTest.php files and add the test filename to the array returned by the correctProvider() method.

Instruction and template tests

Below, you can find a sample unit test taken from OPT testing procedure:

Check the opt:literal instruction.
 
>>>>templates/test.tpl
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<opt:root>
<opt:literal>Foo<![CDATA[Bar]]>{$joe}<![CDATA[Goo]]>Hoo</opt:literal>
</opt:root>
 
>>>>expected.txt
OUTPUT
 
>>>>result.txt
<![CDATA[FooBarJoeGooHoo]]>
 
>>>>data.php
$view->joe = 'Joe';

1. We start the file with a brief description of what we are going to test.
2. templates/test.tpl - the main template file.
3. expected.txt - what sort of results is expected (either OUTPUT or the exception class name)
4. result.txt - the expected output (if the OUTPUT has been chosen in expected.txt)
5. data.php - additional initialization PHP code. The test view is stored in $view variable.

The unit test may also use several other files (i.e. extra templates). Such situations can be found in /tests/instruction/extend_x.txt files in the OPTv2 testing procedure.

You do not have to worry about the line breaks. They are removed from the output and the expected content before they are matched.

Expression tests

The expression tests are saved in expressionTest.php file. The test cases have a form of the entry in the array:

array(false, '$foo gt 3', '$this->_data[\'foo\']>3', 0),

The description:

1. true to enable assignment operators.
2. The source expression
3. The output PHP form of the expression
4. 0 or the exception class name, if the test should generate an exception.