diff --git a/docs/en/howto/phpunit-configuration.md b/docs/en/howto/phpunit-configuration.md
index 197a3ec58..fde20de6d 100644
--- a/docs/en/howto/phpunit-configuration.md
+++ b/docs/en/howto/phpunit-configuration.md
@@ -3,55 +3,26 @@
This guide helps you to run [PHPUnit](http://phpunit.de) tests in your SilverStripe project.
See "[Testing](/topics/testing)" for an overview on how to create unit tests.
-## Should I execute through "sake dev/tests" or "phpunit"?
-
-Short answer: Both are valid ways.
-
-The `sake` executable that comes with SilverStripe can trigger a customized
-"[api:TestRunner]" class that handles the PHPUnit configuration and output formatting.
-It's tyically invoked to run all tests through `sake dev/tests/all`,
-a single test with `sake dev/tests/MyTestClass`, or tests for a module with `sake dev/tests/module/mymodulename`.
-While the custom test runner a handy tool, its also more limited than using `phpunit` directly,
-particularly around formatting test output.
-
-The `phpunit` executable uses a SilverStripe bootstrapper to autoload classes,
-but handles its own test class retrieval, output formatting and other configuration.
-It can format output in common structured formats used by "continuous integration" servers.
-If you're using [phpUnderControl](http://phpundercontrol.org/) or a similar tool,
-you will most likely need the `--log-junit` and `--coverage-xml` flags that are not available through `sake`.
-
-All command-line arguments are documented on [phpunit.de](http://www.phpunit.de/manual/current/en/textui.html).
-phpunit
-## Usage of "" executable
-
- * `phpunit`: Runs all tests in all folders
- * `phpunit framework/tests/`: Run all tests of the framework module
- * `phpunit framework/tests/filesystem`: Run all filesystem tests within the framework module
- * `phpunit framework/tests/filesystem/FolderTest.php`: Run a single test
- * `phpunit framework/tests '' flush=all`: Run tests with optional `$_GET` parameters (you need an empty second argument)
-
-Note that if you have installed PHPUnit through Composer rather than PEAR
-([instructions](/topics/installation/composer)), the binary will be placed
-in `vendor/bin/phpunit` instead of `phpunit`.
-
## Coverage reports
+PHPUnit can generate code coverage reports for you ([docs](http://www.phpunit.de/manual/current/en/code-coverage-analysis.html)):
+
* `phpunit --coverage-html assets/coverage-report`: Generate coverage report for the whole project
* `phpunit --coverage-html assets/coverage-report mysite/tests/`: Generate coverage report for the "mysite" module
-## Customizing phpunit.xml.dist
+Typically, only your own custom PHP code in your project should be regarded when
+producing these reports. Here's how you would exclude some `thirdparty/` directories:
-The `phpunit` executable can be configured by commandline 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.
-
-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.
-
-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).
+
+
+ framework/dev/
+ framework/thirdparty/
+ cms/thirdparty/
+
+
+ mysite/thirdparty/
+
+
## Running unit and functional tests separately
@@ -80,24 +51,6 @@ You can run with this XML configuration simply by invoking `phpunit --configurat
The same effect can be achieved with the `--group` argument and some PHPDoc (see [phpunit.de](http://www.phpunit.de/manual/current/en/appendixes.configuration.html#appendixes.configuration.groups)).
-## Adding/removing files for code coverage reports
-
-Not all PHP code in your project should be regarded when producing [code coverage reports](http://www.phpunit.de/manual/current/en/code-coverage-analysis.html).
-This applies for all thirdparty code
-
-
-
- framework/dev/
- framework/thirdparty/
- cms/thirdparty/
-
-
- mysite/thirdparty/
-
-
-
-See [phpunit.de](http://www.phpunit.de/manual/current/en/appendixes.configuration.html#appendixes.configuration.blacklist-whitelist) for more information.
-
## Speeding up your test execution with the SQLite3 module
Test execution can easily take a couple of minutes for a full run,
diff --git a/docs/en/topics/testing/index.md b/docs/en/topics/testing/index.md
index 6e2f4ea10..9d6ae83d6 100644
--- a/docs/en/topics/testing/index.md
+++ b/docs/en/topics/testing/index.md
@@ -21,6 +21,8 @@ To get started now, follow the installation instructions below, and check
## Installation
+### Via Composer
+
Unit tests are not included in the normal SilverStripe downloads,
you are expected to work with local git repositories
([installation instructions](/topics/installation/composer)).
@@ -32,45 +34,74 @@ check out the additional requirements to run unit tests:
The will install (among other things) the [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.
+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
+
+### Via PEAR
Alternatively, you can check out phpunit globally via the PEAR packanage manager
([instructions](https://github.com/sebastianbergmann/phpunit/)).
+ pear config-set auto_discover 1
+ pear install pear.phpunit.de/PHPUnit
+
## Running Tests
+### Via the "phpunit" Binary on Command Line
+
+The `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](http://www.phpunit.de/manual/current/en/textui.html).
+
+### Via the "sake" Wrapper on Command Line
+
+The [sake](/topics/commandline) executable that comes with SilverStripe can trigger a customized
+"[api:TestRunner]" class that handles the PHPUnit configuration and output formatting.
+While the custom test runner a handy tool, its also more limited than using `phpunit` directly,
+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
-Go to the main test URL which will give you options for running various available test suites or individual tests on
-their own:
+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.
http://localhost/dev/tests
-### Via Command Line
-
-`cd` to the root level of your project and run [sake](/topics/commandline) (SilverStripe Make) to execute the tests:
-
- /path/to/project$ sake dev/tests/all
-
-Alternatively, you can use the `phpunit` binary to run tests, see [PHPUnit Configuration](phpunit-configuration) for details.
-
-### Partial Test Runs
-
-
-Run specific tests:
-
- dev/tests/MyTest,MyOtherTest
-
-
-Run all tests in a module folder, e.g. "framework"
-
- dev/tests/module/
-
-
-Skip certain tests
-
- dev/tests/all SkipTests=MySkippedTest
-
-
## Writing Tests
Tests are written by creating subclasses of `[api:SapphireTest]`. You should put tests for your site in the
@@ -87,14 +118,30 @@ You will generally write two different kinds of test classes.
Some people may note that we have used the same naming convention as Ruby on Rails.
-## How To
-
Tutorials and recipes for creating tests using the SilverStripe framework:
* **[Create a SilverStripe Test](/topics/testing/create-silverstripe-test)**
* **[Create a Functional Test](/topics/testing/create-functional-test)**
* **[Test Outgoing Email Sending](/topics/testing/email-sending)**
+## Configuration
+
+### phpunit.xml
+
+The `phpunit` executable can be configured by commandline 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 file.
+
+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).
+
## Glossary {#glossary}
**Assertion:** A predicate statement that must be true when a test runs.