How to Test PHP Code With PHPUnit

There are many different ways to test your software application, and unit testing is an important one.

So what is unit testing and how can you do it? You'll learn that and more in this article.

What is Unit Testing?

Unit testing is a software development process in which the smallest testable parts of an application, called units, are individually and independently scrutinised for process operation. - SearchSoftwareQuality

In basic terms, unit testing means that you break your application down to its simplest pieces and test these small pieces to ensure that each part is error free (and secure).

This testing is automated and written by software engineers as part of their development process. This is a very important step during development as it helps developers build better applications with fewer bugs.

What is PHPUnit?

You can perform unit testing in PHP with PHPUnit, a programmer-oriented testing framework for PHP. PHPUnit is an instance of the xUnit architecture for unit testing frameworks. It is very easy to install and get started with.

PHPUnit Installation

You can install PHPUnit globally on your server. You can also install it locally, on a per-project, development-time basis as a dependency to your project using composer. This article will explain how to use it on a per project basis.

To get started, create and initiate a new project with composer using these commands:

$ mkdir test-project
$ cd test-project
$ composer init

The first command creates a folder in your current directory, test-project and the second command moves into it. The last command starts an interactive shell.

Follow the prompt, filling in the details as required (the default values are fine). You can set the project description, author name (or contributors' names), minimum stability for dependencies, project type, license, and define your dependencies.

You can skip the dependencies part, as we are not installing any dependencies. PHPUnit is supposed to be a dev-dependency because testing as a whole should only happen during development.

Now, when the prompt asks Would you like to define your dev dependencies (require-dev) interactively [yes]?, press enter to accept. Then type in phpunit/phpunit to install PHPUnit as a dev-dependency.

Accept the other defaults and proceed to generating the composer.json file. The generated file should look like this currently:

{
    "name": "zubair/test-project",
    "require-dev": {
        "phpunit/phpunit": "^9.5"
    },
    "autoload": {
        "psr-4": {
            "Zubair\\TestProject\\": "src/"
        }
    },
    "authors": [
        {
            "name": "Idris Aweda Zubair",
            "email": "zubairidrisaweda@gmail.com"
        }
    ],
    "require": {}
}

To learn how to install PHPUnit globally on your server, read here.

How to Write Tests in PHPUnit

Writing tests in PHPUnit is quite simple. Here are a few conventions to get you started:

• To test a class in PHP, you'll create a test class named after that class. For example, if I had some sort of User class, the test class would be named UserTest.
• The test class, UserTest, will usually inherit the PHPUnit\Framework\TestCase class.
• Individual tests on the class are public methods named with test as a prefix. For example, to test a sayHello method on the User class, the method will be named testSayHello.
• Inside the test method, say testSayHello, you use PHPUnit's method like assertSame to see that some method returns some expected value.

A popular convention is to have all tests in a tests directory, and all source code in the src directory.

PHPUnit Testing Example

To help understand this article, here's a sample User class with simple methods that will be tested:

<?php

namespace Zubair\TestProject;

use InvalidArgumentException;

class User
{
    public int $age;
    public array $favorite_movies = [];
    public string $name;

    /**
     * @param int $age
     * @param string $name
     */
    public function __construct(int $age, string $name)
    {
        $this->age = $age;
        $this->name = $name;
    }

    public function tellName(): string
    {
        return "My name is " . $this->name . ".";
    }

    public function tellAge(): string
    {
        return "I am " . $this->age . " years old.";
    }

    public function addFavoriteMovie(string $movie): bool
    {
        $this->favorite_movies[] = $movie;

        return true;
    }

    public function removeFavoriteMovie(string $movie): bool
    {
        if (!in_array($movie, $this->favorite_movies)) throw new InvalidArgumentException("Unknown movie: " . $movie);

        unset($this->favorite_movies[array_search($movie, $this->favorite_movies)]);

        return true;
    }
}

This user class could be the User class in your movie streaming application. The user has a name, age, and a list of favourite movies that can be updated. For the rest of the article we will test that all these features work as they're expected to.

Create a UserTest class in the tests folder. Paste this in to start:

<?php

namespace Zubair\TestProject;

use PHPUnit\Framework\TestCase;

final class UserTest extends TestCase
{
    // Tests will go here
}

Test Constructor

Normally, you wouldn't be testing the __construct method. However, since we're setting values in it, it only makes sense to be sure that the values are being set correctly.

This seems like a very small thing to test, but that's the whole point of unit tests – to ensure that the smallest parts of your application function as expected.

Create a testClassConstructor method to test the constructor:

public function testClassConstructor()
{
    $user = new User(18, 'John');

    $this->assertSame('John', $user->name);
    $this->assertSame(18, $user->age);
    $this->assertEmpty($user->favorite_movies);
}

Let's take a quick break now, to see how to run the tests.

How to Run Tests in PHPUnit

You can run all the tests in a directory using the PHPUnit binary installed in your vendor folder.

$ ./vendor/bin/phpunit --verbose tests

You can also run a single test by providing the path to the test file.

$ ./vendor/bin/phpunit --verbose tests/UserTest.php

You use the --verbose flag to get more information on the test status.

Now, we can run the test and see the output:

The output shows that we ran 1 test, and made 3 assertions in it. We also see how long it took to run the test, as well as how much memory was used in running the test.

These assertions are what PHPUnit uses to compare values returned from the methods to their expected value.

This example uses assertSame to check if the name and age properties on the user object match the entered values. It also uses assertEmpty to check that the favorite_movies array is empty.

To see a list of all these assertions, you can check out PHPUnit's docs here.

Edit the code to check if the user age is the same as 21.

public function testClassConstructor()
{
    $user = new User(18, 'John');

    $this->assertSame('John', $user->name);
    $this->assertSame(21, $user->age);
    $this->assertEmpty($user->favorite_movies);
} 

Running the test again this time gives this output:

The output now shows that we ran 1 test, with 2 successful assertions, and also a failed one. We can see some explanation of the failure, showing the expected value, the gotten value, and the line where the error is from.

Test testName and tellAge

Next, we can test the testName method. This method tells the name of a user as a sentence. So, we can write the test to check:

• If the returned value is a string.
• If the returned string has the user's name in it (with or without case sensitivity).

public function testTellName()
{
    $user = new User(18, 'John');

    $this->assertIsString($user->tellName());
    $this->assertStringContainsStringIgnoringCase('John', $user->tellName());
}

The test uses the assertions assertIsString  and assertStringContainsStringIgnoringCase to check that the return value is a string and that it contains the string John, respectively.

The testAge method is very similar to testName and uses the same logic. Its test will be similar to the previous one:

public function testTellAge()
{
    $user = new User(18, 'John');

    $this->assertIsString($user->tellAge());
    $this->assertStringContainsStringIgnoringCase('18', $user->tellAge());
}

Test addFavoriteMovie

We can test this method, too. This method adds a movie to the list of movies. To test it, we can check if the newly added movie is in the list, and that the number of items in the list actually increased.

The latter is for confirming that items are not being displaced. Also, since the function returns some value at the end, we can check that this value is correct too.

public function testAddFavoriteMovie()
{
    $user = new User(18, 'John');

    $this->assertTrue($user->addFavoriteMovie('Avengers'));
    $this->assertContains('Avengers', $user->favorite_movies);
    $this->assertCount(1, $user->favorite_movies);
}

Here, we use a few new assertions – assertTrue, assertContains, and assertCount – to check that the returned value is true, that it contains the newly added string, and that the array now has one item in it.

Test removeFavoriteMovie

Finally, we can test that the method to remove a movie works.

public function testRemoveFavoriteMovie()
{
    $user = new User(18, 'John');

    $this->assertTrue($user->addFavoriteMovie('Avengers'));
    $this->assertTrue($user->addFavoriteMovie('Justice League'));

    $this->assertTrue($user->removeFavoriteMovie('Avengers'));
    $this->assertNotContains('Avengers', $user->favorite_movies);
    $this->assertCount(1, $user->favorite_movies);
}

Here, we're adding some movies to the list. Then, we remove one of them, and confirm that the function returned true. Next, we confirm the removal by checking that the value is no longer in the list. Finally, we confirm that we have only one movie in the list, instead of two.

Conclusion

Now you know how to set up PHPUnit in your projects and how to test and ensure that you're building world class software. You can find all the code for this article here.

If you have any questions or relevant advice, please get in touch with me to share them.

To read more of my articles or follow my work, you can connect with me on LinkedIn, Twitter, and Github. It’s quick, it’s easy, and it’s free!