mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-02 06:09:00 +02:00
Merge pull request #940 from chillu/pulls/phpunit-composer
Fetch PHPUnit dependency through composer
This commit is contained in:
Ingo Schommer
commit
8f27e7a7a5
@ -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);
|
||||
|
||||
@ -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.
|
||||
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).
|
||||
<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>
|
||||
|
||||
## 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,
|
||||
|
||||
@ -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
|
||||
[SimpleTest](http://simpletest.org/), the two premiere PHP testing frameworks.
|
||||
### Via Composer
|
||||
|
||||
To run SilverStripe 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](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)).
|
||||
Unit tests are not included in the normal SilverStripe downloads,
|
||||
you are expected to work with local git repositories
|
||||
([installation instructions](/topics/installation/composer)).
|
||||
|
||||
The PHPUnit installation via PEAR is very straightforward.
|
||||
You might have to perform the following commands as root or super user (sudo).
|
||||
Once you've got the project up and running,
|
||||
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
|
||||
pear channel-discover pear.symfony-project.com
|
||||
pear install phpunit/PHPUnit
|
||||
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
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user