See sebastianbergmann/phpunit#936
I don't think many folks have problems downloading the library, but you can put the following into the PHAR section of the installation page (http://phpunit.de/manual/3.8/en/installation.html):
Installation:
Use your browser or a command line tool to download the PHP archive (PHAR).
Example using wget
wget http://pear.phpunit.de/get/phpunit.phar
Example using curl
curl -O http://pear.phpunit.de/get/phpunit.phar
Example using a browser
Navigate to http://pear.phpunit.de/get/phpunit.phar
in the browser of your choice.
Next, you should clarify the conventions at the top of the "Writing Tests for PHP Unit" page (http://phpunit.de/manual/3.8/en/writing-tests-for-phpunit.html), specifically number 3 should be more clear about the naming convention and it should provide an example of the docblock syntax. Consider the following:
The tests are public methods that are named test* (i.e. the function names in your class must begin with "test", e.g. "function test1" or "function test_log")
Alternatively, you can use the @test annotation in a method's docblock to mark it as a test method. For example:
/**
* This is my docblock that uses the test annotation.
* @test
*/
function test_something() {
// ... test goes here
}
-- You should clarify that the class name is not important. It normally matches the filename, but this is not required.
-- I think you also need to clarify if and when a test function accepts arguments. It would be appropriate to say something like "A test function may also accept arguments supplied by a function named "provider". See example 4.4."
However, you should probably clean up 4.4 -- it's not clear that the function name must be "provider" and it's not clear why it returns an array with 4 elements, but the function only accepts 3 arguments. Is that intentional? Or am I missing something? Is it getting the function name from the "dataProvider" docblock attribute? You can see how little things like that can be misleading. Every time you have some variation or behavior like that, you need to have at least 2 examples that demonstrate the behavior and a variant, otherwise, people fall off the wagon.
Next you need to provide full examples showing how to execute tests, including variations for executing them using the library installed via composer, via pear, or as a .phar. The following bit should be on the http://phpunit.de/manual/3.8/en/writing-tests-for-phpunit.html page. I would recommend you create a new section called "Running the Tests". Consider the following.
Running the Tests
To demonstrate how to run PHP Unit tests, let's consider a simple test that asserts that 1 + 1 = 2. Copy and paste the following into a file named "MyFirstTest.php":
<?php
class MyFirstTest extends PHPUnit_Framework_TestCase
{
public function testFirst()
{
$this->assertEquals(1 + 1, 2);
}
}
?>
Next we will demonstrate how to run these tests. In all the variations
Running the Test via PHAR
Make sure you've downloaded the PHAR into the same directory as your test class, so that your directory contents look something like this:
- MyFirstTest.php
- phpunit.phar
From that directory, run the following command:
php phpunit.phar MyFirstTest
Note that the name of the test (MyFirstTest) is the name of the file, minus the ".php" extension.
Running the Test via Composer:
If you have installed PHP Unit via Composer, you can run your tests using the "phpunit" command:
vendor/bin/phpunit MyFirstTest
Running the Test via PEAR:
This is actually the install method that's being assumed in most of the documentation.
phpunit MyFirstTest
Test Output
No matter which method you use to execute your test, you should see something like the following upon successful execution:
$ php phpunit.phar MyFirstTest.php
PHPUnit 3.7.21 by Sebastian Bergmann.
.
Time: 0 seconds, Memory: 2.50Mb
OK (1 test, 1 assertion)
Modified Test
Typically, your test classes will contain multiple testing functions. Let's augment our example of a test that succeeds (1 + 1 = 2) with a test that fails (2 + 2 = 5). Edit MyFirstTest.php so it looks like the following.
<?php
class MyFirstTest extends PHPUnit_Framework_TestCase
{
public function testFirst()
{
$this->assertEquals(1 + 1, 2);
}
public function testSecond()
{
$this->assertEquals(2 + 2, 5);
}
}
?>
Now when you run this test, your output should reflect some success and some failures. Execute the tests using the same command you used above. But now the output should look something like the following:
PHPUnit 3.7.21 by Sebastian Bergmann.
.F
Time: 0 seconds, Memory: 2.75Mb
There was 1 failure:
1) MyFirstTest::testSecond
Failed asserting that 5 matches expected 4.
/path/to/MyFirstTest.php:10
FAILURES!
Tests: 2, Assertions: 2, Failures: 1.
Sorry if this seems trivial and pedantic, but your docs are missing this section.