Test-Driven Development with PHP 8

1The need first: code comes after

Not a line of PHP at the start. Museum volunteers log donations in a shared spreadsheet: a car's colour is typed "blue", "flames" or with a typo, and nobody can find anything. Sarabia derives needs, problems and constraints from it, then user stories (a feature described from the user's point of view) filed under epics (the big batches) in Jira, the task tracker. Writing code straight from a story is, for him, "a recipe for future disaster" (lesson 7), and he admits: "this is how I used to develop software" (lesson 7). His chain: the need becomes a scenario, the scenario a test, the test dictates the code.

2Gherkin, Behat, Mink: a shared language for the business

BDD (Behavior-Driven Development) has you write first what the system must do, in a language the business side can read. Gherkin is that language: "a language used to define business scenarios and goals" (lesson 34), in plain English. Behat is the PHP framework that runs those scenarios. Mink is a library that drives a simulated browser: "think about a robot version of yourself testing your program for you through a web browser" (lesson 34).

Feature: Home page
  In order to welcome visitors
  As a visitor
  I need to be able to see the Symfony logo
  Scenario: See the Symfony logo
    Given I have access to the home page URL
    When I visit the home page
    Then I should see the Symfony Logo

Given sets the starting state, When the action, Then the expected result. Behat generates the empty PHP methods (--append-snippets), for you to fill in. Sarabia had wanted to skip Gherkin, until a project with a third-party company whose tests lived inside his application: "I wish there were a common format that we could share" (lesson 36).

3One thread from ticket to unit test

Beck, in his book, stays at the unit test (a test of a single class or method, with no database or network). Here the levels chain together on one ticket, registering a clerk for the museum's inventory. That ticket becomes a Gherkin feature that Behat runs and that fails. A Symfony functional test fails next: it sends an HTTP request to a controller and checks the response. Then comes an integration test, which makes several classes work with a real database set aside for tests, then the unit tests. To turn green, the author leans on the security component: "Luckily, Symfony makes it easy to implement security" (lesson 40). The make:user and make:registration-form generators write the user and the registration (lessons 40 and 41).

4Red first, even for a test that tests nothing

The first rule is "We should always fail our test first" (lesson 29), for four reasons (lesson 3). The first: prove that PHPUnit recognizes the test, so that the environment is properly set up. Hence the cycles opened by $this->fail("--- RED ---"). The other three: define what the code must do, list the remaining work, make sure that code gets tested. The first real example (lesson 24) fails through a subtraction placed there on purpose:

// ✗ BEFORE: the test expects 6, it gets 0
return $a + $b - $c;
// ✓ AFTER: we add $c, the test passes
return $a + $b + $c;

To turn green, the rule is "We did the minimum work to pass the test" (lesson 38).

Tests are grouped into suites (Unit, Integration) declared in phpunit.xml, PHPUnit's configuration. The author has known a single suite of thousands of tests: "you run the suite and wait an hour, only to find out there's one broken unit test" (lesson 28). On code coverage (the share of the code executed by the tests): "I still believe that 50% test coverage is better than 0% test coverage" (lesson 25).

5SOLID driven by failing tests

SOLID is an acronym for five design principles:

• S (single responsibility): one class, one reason to change.
• O (open/closed): open for extension, closed for modification.
• L (Liskov): one implementation must be able to replace another without breaking the behaviour.
• I (narrow interfaces): no useless method forced on classes.
• D (dependency inversion): depend on abstractions rather than on concrete classes.

The running example is a car validator, and each principle is born from a red test. For the S, the ToyCar object holds only data, and a separate class orchestrates. For the O, a YearValidator and a NameValidator, each tested, slip into an array, and a future colour validator won't force you to reopen the main class:

$validator = new ToyCarValidator();
$validator->setValidators([
    'year' => new YearValidator(),
    'name' => new NameValidator(),
]);

For the L, the year validator throws a ToyCarTooOldException that extends \Exception. Nobody catches it and the test blows up, because the interface promises a different exception.

// ✗ BEFORE: outside the interface contract
class ToyCarTooOldException extends \Exception {}
// ✓ AFTER: the interface declares ToyCarValidationException
class ToyCarTooOldException extends ToyCarValidationException {}

For the I, adding validateLength to the shared interface doesn't suit a colour validator: the colour is a ToyColor object, not a string. So a StringValidatorInterface is split out. Sarabia admits to interfaces full of empty methods and "TODO"s.

6Inject, double, and keep the domain away from Doctrine

For the D, Sarabia calls this principle "In terms of making a class more testable, the DIP is probably the most important principle on the list for me" (lesson 51). The validator no longer creates its dependencies, they are passed in. The test replaces the missing classes with test doubles (fake objects whose answer you fix), which saves waiting for the colleague who takes two weeks to write the database save:

$validatorStub = $this->createMock(ToyCarValidatorInterface::class);
$validatorStub->method('validate')->willReturn($validationResultStub);
$toyWriterStub = $this->createMock(WriterInterface::class);
$toyWriterStub->method('write')->willReturn(true);
$processor = new ToyCarCreator($validatorStub, $toyWriterStub);

ToyCarCreator, the processing class (the book says processor), validates, then writes. It handles a ToyCar object with no Doctrine annotation (a special comment that ties a class to a table), a POPO (a PHP object with no dependency). Yet the book gives the same name to the Doctrine entity (lesson 30), which its annotations tie to the ORM. For SOLID, Sarabia injects by hand.

Symfony can inject by itself, and the book shows it once (lesson 31). A coffee service there saves a total in the test database. The services.yaml file, where Symfony declares its services, turns on autowiring: Symfony reads the constructor and supplies the requested objects by itself. The test extends KernelTestCase, the test class that boots Symfony. It asks the container, the object that builds services, for the service instead of writing new.

7CI replays everything on every push

CI (continuous integration) runs the tests on every change. Bitbucket Pipelines, Bitbucket's CI service, reads a YAML file. The book's file (excerpt, image installation omitted) brings up the Docker containers. It then runs the Symfony tests with coverage and the Behat scenarios (five announced, four written out):

script:
  - cd docker
  - docker-compose build && docker-compose up -d
  - docker exec -i docker_server-web_1 /var/www/html/symfony/setup.sh
  - docker exec -i docker_server-web_1 /var/www/html/symfony/runCoverage.sh
  - docker exec -i docker_server-web_1 /var/www/html/behat/runBehatTests.sh

The setup.sh scripts install the packages and prepare the database. CD (continuous delivery, automatic release to production) goes through AWS. Its pipeline has three steps: the tests, uploading the archive to S3 (Amazon's storage), installing on the server with CodeDeploy (the AWS service that deploys). That pipeline runs in 18 minutes (lesson 59), then the author checks the application by hand.