Merge pull request #940 from chillu/pulls/phpunit-composer

Fetch PHPUnit dependency through composer

core/Core.php

@@ -275,10 +275,16 @@ $flush = (isset($_GET['flush']) || isset($_REQUEST['url']) && (
 ));
 $manifest = new SS_ClassManifest(BASE_PATH, false, $flush);
 
+// Register SilverStripe's class map autoload
 $loader = SS_ClassLoader::instance();
 $loader->registerAutoloader();
 $loader->pushManifest($manifest);
 
+// Fall back to Composer's autoloader (e.g. for PHPUnit), if composer is used
+if(file_exists(BASE_PATH . '/vendor/autoload.php')) {
+	require_once BASE_PATH . '/vendor/autoload.php';
+}
+
 // Now that the class manifest is up, load the configuration
 $configManifest = new SS_ConfigManifest(BASE_PATH, false, $flush);
 Config::inst()->pushConfigManifest($configManifest);

docs/en/howto/phpunit-configuration.md

@@ -3,51 +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).
-
-## Usage of "phpunit" 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)
-
 ## 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.
+	<filter>
-File-based configuration has the advantage of enforcing certain rules across
+		<blacklist>
-test executions (e.g. excluding files from code coverage reports), and of course this
+			<directory suffix=".php">framework/dev/</directory>
-information can be version controlled and shared with other team members.
+			<directory suffix=".php">framework/thirdparty/</directory>
-
+			<directory suffix=".php">cms/thirdparty/</directory>
-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
+			<!-- Add your custom rules here -->
-its existence, and prioritize it over the default file.
+			<directory suffix=".php">mysite/thirdparty/</directory>
-
+		</blacklist>
-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)).
+	</filter>
-For example, you could have a `phpunit-unit-tests.xml` and `phpunit-functional-tests.xml` file (see below).
 
 ## Running unit and functional tests separately
 
@@ -76,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
-
-	<filter>
-		<blacklist>
-			<directory suffix=".php">framework/dev/</directory>
-			<directory suffix=".php">framework/thirdparty/</directory>
-			<directory suffix=".php">cms/thirdparty/</directory>
-			
-			<!-- Add your custom rules here -->
-			<directory suffix=".php">mysite/thirdparty/</directory>
-		</blacklist>
-	</filter>
-
-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,

docs/en/topics/testing/index.md

@@ -16,66 +16,92 @@ 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](#glossary).
-
 To get started now, follow the installation instructions below, and check
 [Troubleshooting](/topics/testing/testing-guide-troubleshooting) in case you run into any problems.
 
 ## Installation
 
-The framework has a required dependency on [PHPUnit](http://www.phpunit.de/) and an optional dependency on
+### Via Composer
-[SimpleTest](http://simpletest.org/), the two premiere PHP testing frameworks.
 
-To run SilverStripe tests, you'll need to be able to access PHPUnit on your include path. First, you'll need to make sure
+Unit tests are not included in the normal SilverStripe downloads,
-that you have the PEAR command line client installed. To test this out, type `pear help` at your prompt. You should
+you are expected to work with local git repositories 
-see a bunch of generic PEAR info. If it's not installed, you'll need to set it up first (see: [Getting Started with
+([installation instructions](/topics/installation/composer)).
-PEAR](http://www.sitepoint.com/article/getting-started-with-pear/)) or else manually install PHPUnit (see: [Installation
-instructions](http://www.phpunit.de/pocket_guide/3.3/en/installation.html)).
 
-The PHPUnit installation via PEAR is very straightforward.
+Once you've got the project up and running,
-You might have to perform the following commands as root or super user (sudo).
+check out the additional requirements to run unit tests:
 
-<del>We need a specific version of PHPUnit (3.3.x), as 3.4 or higher breaks our test runner (see [#4573](http://open.silverstripe.com/ticket/4573))</del>
+	composer update --dev
 
-At your prompt, type the following commands:
+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:
 
-	pear channel-discover pear.phpunit.de 
+	ln -s vendor/bin/phpunit phpunit
-	pear channel-discover pear.symfony-project.com
+
-	pear install 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
+Executing tests from the command line is recommended, since it most closely reflects
-their own:
+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
-
-
-### Partial Test Runs
-
-
-Run specific tests:
-
-	dev/tests/MyTest,MyOtherTest
-
-
-Run all tests in a module folder, e.g. "framework"
-
-	dev/tests/module/<modulename>
-
-
-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
@@ -92,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.