This tutorial assumes that you use PHP 7.0. You will learn how to write simple unit tests as well as how to download and run PHPUnit.
Go here if you use PHP 7.1 (or later).
Go here if you use PHP 5.6.
Go here if you use PHP 5.3, PHP 5.4, or PHP 5.5.
The documentation for PHPUnit 6 can be found here.
We distribute a PHP Archive (PHAR) that contains everything you need in order to use PHPUnit 6, the latest version of PHPUnit that is compatible with PHP 7.0. Simply download it from here and make it executable:
You can add PHPUnit as a local, per-project, development-time dependency to your project using Composer:
➜ wget -O phpunit https://phar.phpunit.de/phpunit-6.phar ➜ chmod +x phpunit ➜ ./phpunit --version PHPUnit 6.5.5 by Sebastian Bergmann and contributors.
➜ composer require --dev phpunit/phpunit ^6 ➜ ./vendor/bin/phpunit --version PHPUnit 6.5.5 by Sebastian Bergmann and contributors.
Please refer to the documentation for details on how to verify PHAR releases of PHPUnit.
The example shown above assumes that composer
is on your $PATH
.
Your composer.json
should look similar to this:
{
"autoload": {
"classmap": [
"src/"
]
},
"require-dev": {
"phpunit/phpunit": "^6"
}
}
src/Email.php
<?php
declare(strict_types=1);
final class Email
{
private $email;
private function __construct(string $email)
{
$this->ensureIsValidEmail($email);
$this->email = $email;
}
public static function fromString(string $email): self
{
return new self($email);
}
public function __toString(): string
{
return $this->email;
}
private function ensureIsValidEmail(string $email)
{
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
throw new InvalidArgumentException(
sprintf(
'"%s" is not a valid email address',
$email
)
);
}
}
}
tests/EmailTest.php
<?php
declare(strict_types=1);
use PHPUnit\Framework\TestCase;
final class EmailTest extends TestCase
{
public function testCanBeCreatedFromValidEmailAddress()
{
$this->assertInstanceOf(
Email::class,
Email::fromString('user@example.com')
);
}
public function testCannotBeCreatedFromInvalidEmailAddress()
{
$this->expectException(InvalidArgumentException::class);
Email::fromString('invalid');
}
public function testCanBeUsedAsString()
{
$this->assertEquals(
'user@example.com',
Email::fromString('user@example.com')
);
}
}
➜ ./phpunit --bootstrap src/autoload.php tests/EmailTest PHPUnit 6.5.5 by Sebastian Bergmann and contributors. ... 3 / 3 (100%) Time: 70 ms, Memory: 10.00MB OK (3 tests, 3 assertions)
The above assumes that you have downloaded phpunit.phar
and put it into your $PATH
as phpunit
and that src/autoload.php
is a script that sets up autoloading for the classes that are to be tested. Such a script is commonly generated using a tool such as phpab.
➜ ./vendor/bin/phpunit --bootstrap vendor/autoload.php tests/EmailTest PHPUnit 6.5.5 by Sebastian Bergmann and contributors. ... 3 / 3 (100%) Time: 70 ms, Memory: 10.00MB OK (3 tests, 3 assertions)
--bootstrap src/autoload.php
instructs the PHPUnit command-line test runner to include src/autoload.php
before the tests are run.
tests/EmailTest
instructs the PHPUnit command-line test runner to execute the tests of the EmailTest
class that is declared in tests/EmailTest.php
.
Using tests
instead of tests/EmailTest
would instruct the PHPUnit command-line test runner to execute all tests found declared in *Test.php
sourcecode files in the tests
directory.
--bootstrap vendor/autoload.php
instructs the PHPUnit command-line test runner to include vendor/autoload.php
before the tests are run.
tests/EmailTest
instructs the PHPUnit command-line test runner to execute the tests of the EmailTest
class that is declared in tests/EmailTest.php
.
Using tests
instead of tests/EmailTest
would instruct the PHPUnit command-line test runner to execute all tests found declared in *Test.php
sourcecode files in the tests
directory.
Below you see an alternative output which is based on the idea that the name of a test can be used to document the behavior that is verified by the test:
➜ ./phpunit --bootstrap src/autoload.php --testdox tests PHPUnit 6.5.5 by Sebastian Bergmann and contributors. Email [x] Can be created from valid email address [x] Cannot be created from invalid email address [x] Can be used as string
➜ ./vendor/bin/phpunit --bootstrap vendor/autoload.php --testdox tests PHPUnit 6.5.5 by Sebastian Bergmann and contributors. Email [x] Can be created from valid email address [x] Cannot be created from invalid email address [x] Can be used as string