mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-07-03 18:09:53 +02:00
Testing docs recommend "phpunit" over "sake"
- Moved some docs around to reflect this change - Described how to symlink from vendor/bin/phpunit - Added note about browser-runs not being recommended - Added more examples on how to run through "sake", to complement the existing descriptions for "phpunit"
This commit is contained in:
Ingo Schommer
parent
e4d71c2a20
commit
4fcdfe8d64
|
|
@ -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).
|
||||
<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
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
<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,
|
||||
|
|
|
|||
|
|
@ -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/<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
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user