Introduction to PHP Unit Testing with PHPUnit

Unit testing is a key practice in software development that ensures your code behaves as expected. By testing individual units or components of your application in isolation, you can catch bugs early and ensure that your code is both reliable and maintainable. PHPUnit is the most widely used testing framework in PHP, offering powerful tools to automate the testing process, verify code behavior, and ensure that your code evolves without breaking existing functionality.

In this blog, we’ll introduce you to PHPUnit, covering how to install it, write your first unit tests, and explore best practices for using PHPUnit effectively in your projects.

What is Unit Testing?

Unit testing is a type of software testing where individual units (small pieces of code, typically functions or methods) are tested in isolation. The goal is to verify that each unit of code works as expected.

For example, if you have a function that calculates the total price of items in a shopping cart, you can create a unit test to ensure that it returns the correct total given different inputs.

Unit tests are usually written before or during the development process and serve as a safety net that helps developers refactor code with confidence, knowing that tests will catch any potential issues.

What is PHPUnit?

PHPUnit is a testing framework specifically designed for PHP. It allows developers to write automated tests that can be executed to check whether their code behaves as expected. With PHPUnit, you can:

Test individual methods or functions.
Write both unit tests and integration tests.
Generate test coverage reports.
Organize tests into suites for efficient execution.

PHPUnit also integrates seamlessly with continuous integration (CI) tools like Jenkins, Travis CI, and GitHub Actions, making it ideal for automated testing workflows.

Installing PHPUnit

Before you can start writing tests, you need to install PHPUnit in your project. The recommended way to install PHPUnit is via Composer, PHP's dependency manager.

Step 1: Install Composer

If you haven't already installed Composer, you can download it from Composer's official website and follow the instructions provided.

Step 2: Install PHPUnit via Composer

To install PHPUnit in your project, run the following command in your terminal:

composer require --dev phpunit/phpunit

This installs PHPUnit as a development dependency, meaning it will only be available in the development environment and not in production.

Step 3: Verify Installation

Once PHPUnit is installed, you can verify the installation by running:

./vendor/bin/phpunit --version

This command will output the installed PHPUnit version, indicating that it’s ready to use.

Writing Your First PHPUnit Test

Now that PHPUnit is installed, let's write a simple unit test.

Step 1: Create a Class to Test

First, we need a class with some functionality to test. Let's create a simple Calculator class with a method to add two numbers:

<?php

class Calculator
{
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }
}

Step 2: Create a Test Class

Next, create a test class that will contain the unit test for the add() method. PHPUnit tests are typically stored in the tests directory.

<?php

use PHPUnit\Framework\TestCase;

class CalculatorTest extends TestCase
{
    public function testAdd()
    {
        $calculator = new Calculator();
        $result = $calculator->add(2, 3);

        $this->assertEquals(5, $result);
    }
}

Explanation:

use PHPUnit\Framework\TestCase;: This imports the TestCase class, which is the base class for all PHPUnit test classes.
testAdd(): This is the actual test method that checks if the add() method in the Calculator class works correctly. It calls the add() method with two numbers (2 and 3) and asserts that the result is 5 using the assertEquals() method.

Step 3: Running the Test

To run the test, open your terminal and execute:

./vendor/bin/phpunit tests/CalculatorTest.php

If the test passes, PHPUnit will display an output like this:

OK (1 test, 1 assertion)

This indicates that one test was executed, and one assertion was made, with no errors or failures.

Common PHPUnit Assertions

PHPUnit provides various assertions to verify that your code behaves as expected. Here are some commonly used assertions:

assertEquals($expected, $actual): Checks if two values are equal.
assertTrue($condition): Asserts that the condition is true.
assertFalse($condition): Asserts that the condition is false.
assertNull($variable): Verifies that a variable is null.
assertCount($expectedCount, $array): Asserts that the number of elements in an array matches the expected count.
assertInstanceOf($expectedClass, $object): Checks if an object is an instance of a specific class.

Example:

<?php

use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    public function testAssertions()
    {
        $array = [1, 2, 3];
        $this->assertCount(3, $array); // Asserts that the array has 3 elements

        $this->assertTrue(true);       // Asserts that the value is true
        $this->assertFalse(false);     // Asserts that the value is false
    }
}

Use Mocks for Dependencies

In larger applications, functions and classes often depend on other objects or services. When testing such code, it's not always practical to use real objects (e.g., making actual database queries or API calls). Instead, you can use mock objects to simulate dependencies.

PHPUnit allows you to create mock objects with its createMock() method.

Example:

<?php

use PHPUnit\Framework\TestCase;

class OrderTest extends TestCase
{
    public function testProcessOrder()
    {
        $paymentGateway = $this->createMock(PaymentGateway::class);
        $paymentGateway->method('charge')->willReturn(true);

        $order = new Order($paymentGateway);
        $result = $order->process(100);

        $this->assertTrue($result);
    }
}

In this example, we create a mock of the PaymentGateway class, and instead of actually charging a payment, the charge() method always returns true.

Automate Tests with Continuous Integration (CI)

To ensure that your tests are run automatically, integrate PHPUnit into your CI pipeline. Tools like GitHub Actions, Travis CI, and Jenkins can run your tests automatically every time code is pushed, ensuring that any new changes don’t break existing functionality.

Generating Code Coverage Reports

Code coverage helps you understand how much of your code is being tested by your unit tests. PHPUnit can generate code coverage reports to show which lines of code are covered by tests and which are not.

To generate a code coverage report, run the following command:

./vendor/bin/phpunit --coverage-html coverage/

This will generate an HTML report in the coverage/ directory, which you can open in a browser to view detailed code coverage information.

Conclusion

Unit testing is an essential part of modern PHP development, and PHPUnit is the perfect tool to get started with automated testing in your projects. By writing unit tests, you can:

Ensure that individual parts of your application work as expected.
Catch bugs early in the development process.
Refactor your code with confidence, knowing that the tests will catch any issues.

Remember to follow best practices such as testing small units of code, handling edge cases, and using mocks when needed. By integrating PHPUnit into your workflow and setting up continuous integration, you can maintain high code quality and prevent regressions as your application evolves.

Now that you’ve had an introduction to PHPUnit, it's time to start writing your own tests and experience the benefits of automated testing firsthand!