How to Write PHP UI tests¶
Test Tools to Use¶
The FOSSology project has decided to use the PHPUnit framework to write PHP tests. All UI unit tests should extend the FOSSology class found in svn at:
There is a class template that can be used to create a test. It's found at:
Make a copy of it and use the comments inside of it to get started.
There is also some test specific classes that can be used by the tests. These classes are found at:
Creating a Test¶
It is a really good idea to read the other sections below. In the interest of getting you started on actually writing a test we will just jump in.
The test framework consists of a set of classes that provide an API for creating tests and then an API/utility to run the tests in either a cli or a web framework. Using the test framework, all tests extend the test classes in some way. That's how the framework works.
All FOSSology tests use a common php include file. This file is used for setting the URL to test and to supply the DB user name and DB user password. The template already includes the file and makes the 3 variables global. All tests need the URL, only the login test needs the user name and password.
- For this example we will use the templateTest.php
- Make a copy of the template, let's create mytest.php
- The template tries to be self documenting, follow the steps outlined in the template. Edit mytest.php and change the following according to the the instructions.
- Remove abstract from the class, any abstract classes are NOT run
- Give the class a name ending in Test, e.g. ''myfirstTest''. Notice we extend the fossologyTestCase class rather than the standard WebTestCase or the fossologyTest class.
- add any needed checks in the setUp method after logging in. For example if the test needs to make sure a folder exists it should check for it in setUp.
- change the name of the method (function) from ''testsome''.... we will use ''testmytest''.
- if your test needs to clean up after itself (remove files, folders etc...) then use the tearDown method.
- save your test as ''mytest.php''
Setting the Test Environment¶
There is a small amount of test environment setup that should be done before running any test. This is documented in this wiki at How to configure and run UI Tests. All the steps below are automated with scripts. Here is a brief summary of the steps used to set up the test environment.
Running the Install.php as sudo does the following
- set up the test users on the system and in the UI.
- copy over some test data into the test users home directory
These steps must still be done by hand, but take very little time.
- set the test environment by running configTestEnv.php to create the TestEnvironment.php include file.
- check the link for fo-runTests
If all you need to use is the test environment for logins then just setting the test environment should be enough. But at some point the new tests should be run with the other tests and for that all the steps will need to be done anyway. The setup is designed to be lightweight and quick to run/setup.
Running your Test¶
There are multiple ways to run a test. All methods use a simpletest run script. During the initial construction of the UI test suite, separate run scripts were constructed for each test suite. This is no longer needed. When tests are created, that method can still be used, but is no longer recommended.
A generalized run script has been created called fo-runTests. Fo-runTests can run 1 or more tests. Usage is:
fo-runTests -l "list of tests space seperated"
If you ran the Install.php script or ran lnfo-runTests.php then a sym link should exist in /usr/local/bin/fo-runTests back to the source tree that you plan to test from. Cd into the where the test is, run it with fo-runTests. You can use fo-runTests to run everything in a directory or that you can wildcard with the shell.
fo-runTests -l "`ls`" run one test: fo-runTests -l ./test-name
If you wish to create your own run script, then start with the template or copy fo-runTests.
Use the comments in the file as a guide. Replace the line $test->addTestFile('atest'); with $test->addTestFile('mytest.php'); Save the run script: myrun.php. Make it executable.
Make sure the test environment has been set.
Use the run script to run your test ./myrun.php
Test ran/didn't run - Now What?¶
For a discussion of how to interpret test output and failure please see How to configure and run UI Tests.
FOSSology Test Areas¶
This is just a stab at some the larger areas that need to be tested in fossology in no particular order or priority.
- License Matches