2011-02-07 07:48:44 +01:00
# Unit and Integration Testing
2013-10-04 03:24:56 +02:00
For behaviour testing in SilverStripe, check out [SilverStripe Behat Documentation ](https://github.com/silverstripe-labs/silverstripe-behat-extension/ ).
## Introduction
2012-03-24 22:16:59 +01:00
The SilverStripe core contains various features designed to simplify the process of creating and managing automated tests.
2011-02-07 07:48:44 +01:00
2013-10-04 03:24:56 +02:00
SilverStripe uses [PHPUnit ](http://www.phpunit.de ) 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 ](glossary ). To get started now, follow the installation instructions below, and check
[Troubleshooting ](testing-guide-troubleshooting ) in case you run into any problems.
2014-09-08 07:13:36 +02:00
If you are familiar with PHP coding but new to unit testing then check out Mark's presentation [Getting to Grips with SilverStripe Testing ](http://www.slideshare.net/maetl/getting-to-grips-with-silverstripe-testing ).
2013-10-04 03:24:56 +02:00
[Why Unit Test? ](why-should-i-test ) will give you reasons why you should be testing your code.
2011-02-07 07:48:44 +01:00
You should also read over [the PHPUnit manual ](http://www.phpunit.de/manual/current/en/ ). It provides a lot of
fundamental concepts that we build on in this documentation.
2014-09-08 07:13:36 +02:00
Unit tests are not included in the normal SilverStripe downloads so you need to install them through git repositories
2013-10-04 03:24:56 +02:00
([installation instructions](/installation/composer)).
2011-02-07 07:48:44 +01:00
2014-09-08 07:13:36 +02:00
## Install with Composer
2014-09-12 07:02:04 +02:00
Once you've got your project up and running, open a terminal and cd to your project root.
composer require --dev "phpunit/phpunit:3.7.*@stable"
This will install [PHPUnit ](http://www.phpunit.de/ ) dependency, which is the framework we're
building our unit tests on. Composer installs it alongside the required PHP classes into the `vendor/bin/` directory.
2012-11-15 14:15:46 +01:00
2014-09-08 07:13:36 +02:00
Open a browser at `http://localhost/dev/tests` to see a list of available tests. Run a test to ensure the installation is complete.
2011-02-07 07:48:44 +01:00
2014-09-08 07:13:36 +02:00
### Symlinking the PHPUnit Binary
You can either use PHPUnit through its full path (`vendor/bin/phpunit`), or symlink it into the root directory of your website:
2011-02-07 07:48:44 +01:00
2014-09-08 07:13:36 +02:00
ln -s vendor/bin/phpunit phpunit
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
## Configuration
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
### phpunit.xml
2011-02-07 07:48:44 +01:00
2013-10-04 03:24:56 +02:00
The `phpunit` executable can be configured by command line arguments or through an XML file. File-based configuration has
2013-09-12 19:22:46 +02:00
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.
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
**Note: This doesn't apply for running tests through the "sake" wrapper**
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
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
file.
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
There's nothing stopping you from creating multiple XML files (see the `--configuration` flag in
[PHPUnit documentation ](http://www.phpunit.de/manual/current/en/textui.html )). For example, you could have a
`phpunit-unit-tests.xml` and `phpunit-functional-tests.xml` file (see below).
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
### Database Permissions
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
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.
2011-02-07 07:48:44 +01:00
## Writing Tests
Tests are written by creating subclasses of `[api: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
2012-03-24 22:16:59 +01:00
`framework/tests/SiteTreeTest.php`
2011-02-07 07:48:44 +01:00
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.
2012-03-24 22:16:59 +01:00
Tutorials and recipes for creating tests using the SilverStripe framework:
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
* [Creating a SilverStripe test ](creating-a-silverstripe-test ): Writing tests to check core data objects
* [Creating a functional test ](creating-a-functional-test ): An overview of functional tests and how to write a functional test
* [Testing Outgoing Email ](testing-email ): An overview of the built-in email testing code
2012-11-15 14:15:46 +01:00
2013-09-12 19:22:46 +02:00
## Running Tests
2012-11-15 14:15:46 +01:00
2013-09-12 19:22:46 +02:00
### Via the "phpunit" Binary on Command Line
2012-11-15 14:15:46 +01:00
2013-09-12 19:22:46 +02:00
The `phpunit` binary should be used from the root directory of your website.
2012-11-15 14:15:46 +01:00
2013-09-24 22:09:30 +02:00
# Runs all tests defined in phpunit.xml
phpunit
2012-11-15 14:15:46 +01:00
2013-09-24 22:09:30 +02:00
# Run all tests of a specific module
phpunit framework/tests/
2012-11-15 14:15:46 +01:00
2013-09-24 22:09:30 +02:00
# Run specific tests within a specific module
phpunit framework/tests/filesystem
2011-02-07 07:48:44 +01:00
2013-09-24 22:09:30 +02:00
# Run a specific test
phpunit framework/tests/filesystem/FolderTest.php
2011-02-07 07:48:44 +01:00
2013-09-24 22:09:30 +02:00
# Run tests with optional `$_GET` parameters (you need an empty second argument)
phpunit framework/tests '' flush=all
2012-11-09 19:16:16 +01:00
2013-09-12 19:22:46 +02:00
All command-line arguments are documented on
[phpunit.de ](http://www.phpunit.de/manual/current/en/textui.html ).
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
### Via the "sake" Wrapper on Command Line
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
The [sake ](/topics/commandline ) executable that comes with SilverStripe can trigger a customized
2013-09-21 21:24:32 +02:00
`[api:TestRunner]` class that handles the PHPUnit configuration and output formatting.
2013-09-12 19:22:46 +02:00
While the custom test runner a handy tool, its also more limited than using `phpunit` directly,
particularly around formatting test output.
2011-02-07 07:48:44 +01:00
2013-09-24 22:09:30 +02:00
# Run all tests
sake dev/tests/all
2011-02-07 07:48:44 +01:00
2013-09-24 22:09:30 +02:00
# Run all tests of a specific module (comma-separated)
sake dev/tests/module/framework,cms
2011-02-07 07:48:44 +01:00
2013-09-24 22:09:30 +02:00
# Run specific tests (comma-separated)
sake dev/tests/FolderTest,OtherTest
2011-02-07 07:48:44 +01:00
2013-09-24 22:09:30 +02:00
# Run tests with optional `$_GET` parameters
sake dev/tests/all flush=all
2011-02-07 07:48:44 +01:00
2013-09-24 22:09:30 +02:00
# Skip some tests
sake dev/tests/all SkipTests=MySkippedTest
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
### Via Web Browser
2011-02-07 07:48:44 +01:00
2013-09-12 19:22:46 +02:00
Executing tests from the command line is recommended, since it most closely reflects
2014-09-08 07:13:36 +02:00
test runs in any automated testing environments. However, you can also run tests through the browser:
2011-02-07 07:48:44 +01:00
2013-09-24 22:09:30 +02:00
http://localhost/dev/tests