This document contains information about a future release and not the current stable version (3.1).
Be aware that information on this page may change and API's may not be stable for production use.
Unit and Integration Testing
For behaviour testing in SilverStripe, check out SilverStripe Behat Documentation.
The SilverStripe core contains various features designed to simplify the process of creating and managing automated tests.
SilverStripe uses PHPUnit for unit tests, and the framework contains features to simplify the process of creating and managing tests.
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.
Why Unit Test? will give you reasons why you should be testing your code.
You should also read over the PHPUnit manual. It provides a lot of fundamental concepts that we build on in this documentation.
Unit tests are not included in the normal SilverStripe downloads, you are expected to work with local git repositories (installation instructions).
Once you've got the project up and running, check out the additional requirements to run unit tests:
composer update --dev
This will install (among other things) the PHPUnit dependency, which is the framework we're
building our unit tests on. Composer installs it alongside the required PHP classes into the
You can either use it through its full path (
vendor/bin/phpunit), or symlink it into the root directory of your website:
ln -s vendor/bin/phpunit phpunit
Alternatively, you can check out PHPUnit globally via the PEAR package manager (instructions).
pear config-set auto_discover 1 pear install pear.phpunit.de/PHPUnit
phpunit executable can be configured by command line arguments or through an XML file. File-based configuration has
the advantage of enforcing certain rules across test executions (e.g. excluding files from code coverage reports), and
of course this information can be version controlled and shared with other team members.
Note: This doesn't apply for running tests through the "sake" wrapper
SilverStripe comes with a default
phpunit.xml.dist that you can use as a starting point. Copy the file into a new
phpunit.xml and customize to your needs - PHPUnit will auto-detect its existence, and prioritize it over the default
There's nothing stopping you from creating multiple XML files (see the
--configuration flag in
PHPUnit documentation). For example, you could have a
phpunit-functional-tests.xml file (see below).
SilverStripe tests create thier own database when they are run. Because of this the database user in your config file should have the appropriate permissions to create new databases on your server, otherwise tests will not run.
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
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
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 SilverStripe framework:
- Creating a SilverStripe test: Writing tests to check core data objects
- Creating a functional test: An overview of functional tests and how to write a functional test
- Testing Outgoing Email: An overview of the built-in email testing code
Via the "phpunit" Binary on Command Line
phpunit binary should be used from the root directory of your website.
# Runs all tests defined in phpunit.xml phpunit
# Run all tests of a specific module phpunit framework/tests/
# Run specific tests within a specific module phpunit framework/tests/filesystem
# Run a specific test phpunit framework/tests/filesystem/FolderTest.php
# Run tests with optional `$_GET` parameters (you need an empty second argument) phpunit framework/tests '' flush=all
All command-line arguments are documented on phpunit.de.
Via the "sake" Wrapper on Command Line
The sake executable that comes with SilverStripe can trigger a customized
TestRunner class that handles the PHPUnit configuration and output formatting.
While the custom test runner a handy tool, its also more limited than using
particularly around formatting test output.
# Run all tests sake dev/tests/all
# Run all tests of a specific module (comma-separated) sake dev/tests/module/framework,cms
# Run specific tests (comma-separated) sake dev/tests/FolderTest,OtherTest
# Run tests with optional `$_GET` parameters sake dev/tests/all flush=all
# Skip some tests sake dev/tests/all SkipTests=MySkippedTest
Via Web Browser
Executing tests from the command line is recommended, since it most closely reflects test runs in any automated testing environments. If for some reason you don't have access to the command line, you can also run tests through the browser.