SilverStripe Testing Guide

The Sapphire core contains various features designed to simplify the process of creating and managing automated tests.

If you are familiar with PHP coding but new to unit testing, you should read the Introduction and check out Mark's presentation Getting to Grips with SilverStripe Testing.

You should also read over the PHPUnit manual. It provides a lot of fundamental concepts that we build on in this documentation.

If you're more familiar with unit testing, but want a refresher of some of the concepts and terminology, you can browse the Testing Glossary.

To get started now, follow the installation instructions below, and check Troubleshooting in case you run into any problems.

The framework has a required dependency on PHPUnit and an optional dependency on SimpleTest, the two premiere PHP testing frameworks.

To run Sapphire tests, you'll need to be able to access PHPUnit on your include path. First, you'll need to make sure that you have the PEAR command line client installed. To test this out, type pear help at your prompt. You should see a bunch of generic PEAR info. If it's not installed, you'll need to set it up first (see: Getting Started with PEAR) or else manually install PHPUnit (see: Installation instructions).

The PHPUnit installation via PEAR is very straightforward. You might have to perform the following commands as root or super user (sudo). We need a specific version of PHPUnit (3.3.x), as 3.4 or higher breaks our test runner (see #4573)

At your prompt, type the following commands:

pear channel-discover pear.phpunit.de 
pear channel-discover pear.symfony-project.com
pear install phpunit/PHPUnit

Go to the main test URL which will give you options for running various available test suites or individual tests on their own:

 http://mysite.com/dev/tests

cd to the root level of your project and run sake (Sapphire Make) to execute the tests:

/path/to/project$ sake dev/tests/all

Run specific tests (Minimum requirement: SilverStripe 2.4)

dev/tests/MyTest,MyOtherTest

Run all tests in a module folder, e.g. “sapphire” (Minimum requirement: SilverStripe 2.4)

dev/tests/module/<modulename>

Skip tests (Minimum requirement: SilverStripe 2.4)

dev/tests/all SkipTests=MySkippedTest

Tests are written by creating subclasses of SapphireTest. You should put tests for your site in the mysite/tests directory. If you are writing tests for a module, put them in the (modulename)/tests directory.

Generally speaking, there should be one test class for each application class. The name of the test class should be the application class, with “Test” as a suffix. For instance, we have all the tests for SiteTree in sapphire/tests/SiteTreeTest.php

You will generally write two different kinds of test classes.

• Unit Test: Test the behaviour of one of your DataObjects.
• Functional Test: Test the behaviour of one of your controllers.

Some people may note that we have used the same naming convention as Ruby on Rails.

Tutorials and recipes for creating tests using the Sapphire framework:

• Create a Sapphire Test
• Load Test Fixtures
• Create a Functional Test
• Test Outgoing Email Sending