G'day:
Please note that I initially intended this to be a single article, but by the time I had finished the first two sections, it was way too long for a single read, so I've split it into the following sections, each as their own article:
- Intro / Nginx
- PHP
- PHPUnit (this article)
- Tweaks I made to my Bash environment in my Docker containers
- MariaDB
- Installing Symfony
- Using Symfony
- Testing a simple web page built with Vue.js using Mocha, Chai and Puppeteer
- I mess up how I configure my Docker containers
- An article about moving files and changing configuration
- Setting up a Vue.js project and integrating some existing code into it
- Unit testing Vue.js components
As indicated: this is the third article in the series, and follows on from Part 2: PHP. It's probably best to go have a breeze through the earlier articles first.
PHPUnit
I got slightly ahead of myself and added PHPUnit into composer.json when I was working through the PHP configuration part of this exercise, so it's already installed. Before I run it though, I need a phpunit.xml file, so I'll chuck one of those in:
<?xml version="1.0" encoding="UTF-8"?>
<phpunit
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.5/phpunit.xsd"
colors="true"
forceCoversAnnotation="true"
cacheResult="false"
>
<coverage>
<include>
<directory suffix=".php">src</directory>
</include>
<report>
<html outputDirectory="public/test-coverage-report/" />
</report>
</coverage>
<testsuites>
<testsuite name="Functional tests">
<directory>test/functional/</directory>
</testsuite>
<testsuite name="Unit tests">
<directory>test/unit/</directory>
</testsuite>
</testsuites>
</phpunit>
There's no real surprises here. I've got two separate test suits: one for functional tests in which I'll test those test web-browseable files I created in the previous article; and one for unit tests. To test the code coverage config here I'll need some actual code to test and cover.
I had some drama getting PHPUnit working with code coverage, and that in itself is covered in a separate article, PHPUnit: get code coverage reporting working on PHP 8 / PHPUnit 9.5. The stuff I've written there is very focused on PHPUnit and not so much on the Docker side of things, or the testing in the context of this notional application I'm putting together, hence splitting it out into its own article, and also so I can focus on the Docker side of things here.
First things first, I need some tests! I decided to functional-test the two web browseable files: gdayWorld.html and gdayWorld.php. As a reminder their contents are (respectively):
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>G'day world</title>
</head>
<body>
<h1>G'day world</h1>
<p>G'day world</p>
</body>
</html>
And:
<?php
$message = "G'day World";
echo $message;
So for the tests I'm just gonna make sure I can hit them, and the HTML one has the expected title, heading and content; and the PHP one just has the expected string. I could horse around with PHP's native curl implementation to make these work, but its programming interface written like something out of 1995, so I tend to avoid it where I can. I'm gonna use Guzzle instead. Also, and this is slightly OTT I know, but I like using Symfony's Response constants when checking for HTTP status codes to make the code more clear, so I'm adding in symfony/http-foundation. Lastly as I'll be using PHP's DOM API for testing the HTML, I'm placating a warning in PHPStorm that says "ooh but ext-dom might not be installed!" So I'm forcing that too. Oh and I like keeping my code tidy so I'm also slinging PHPMD and PHPCS in there too. My composer.json file becomes:
{
"name": "adamcameron/full-stack-exercise",
"description": "Full Stack Exercise",
"license": "GPL-3.0-or-later",
"require-dev": {
"phpunit/phpunit": "^9.5",
"guzzlehttp/guzzle": "^7",
"symfony/http-foundation": "^5.2",
"ext-dom": "*",
"phpmd/phpmd": "^2.9",
"squizlabs/php_codesniffer": "^3.5"
},
"autoload": {
"psr-4": {
"adamCameron\\fullStackExercise\\": "src/"
}
},
"autoload-dev": {
"adamCameron\\fullStackExercise\\test\\": "test/"
}
}
Now I can write some tests. I did all this incrementally, but you know how to do that, so here is the "final" (see below for why I put that in quotes) version of WebServerTest:
namespace adamCameron\fullStackExercise\test\functional\_public; // "public" is reserved
use GuzzleHttp\Client;
use PHPUnit\Framework\TestCase;
use Symfony\Component\HttpFoundation\Response;
class WebServerTest extends TestCase
{
/** @coversNothing */
public function testGdayWorldHtmlReturnsExpectedContent()
{
$expectedContent = "G'day world";
$client = new Client([
'base_uri' => 'http://localhost/'
]);
$response = $client->get('gdayWorld.html');
$this->assertEquals(Response::HTTP_OK, $response->getStatusCode());
$html = $response->getBody();
$document = new \DOMDocument();
$document->loadHTML($html);
$xpathDocument = new \DOMXPath($document);
$hasTitle = $xpathDocument->query('/html/head/title[text() = "' . $expectedContent . '"]');
$this->assertCount(1, $hasTitle);
$hasHeading = $xpathDocument->query('/html/body/h1[text() = "' . $expectedContent . '"]');
$this->assertCount(1, $hasHeading);
$hasContent = $xpathDocument->query('/html/body/p[text() = "' . $expectedContent . '"]');
$this->assertCount(1, $hasContent);
}
}
And I triumphantly run this:
PHPUnit 9.5.0 by Sebastian Bergmann and contributors.
Warning: No code coverage driver available
E 1 / 1 (100%)
Time: 00:00.438, Memory: 6.00 MB
There was 1 error:
1) adamCameron\fullStackExercise\test\functional\_public\WebServerTest::testGdayWorldHtmlReturnsExpectedContent
GuzzleHttp\Exception\ConnectException: cURL error 7: Failed to connect to localhost port 80: Connection refused (see https://curl.haxx.se/libcurl/c/libcurl-errors.html) for http://localhost/gdayWorld.html
Doh! But… but… but… I quickly went and hit http://localhost/gdayWorld.html in my browser and it was fine. Then the penny dropped. I'm not running the tests from my host machine. I'm running them from with the PHP container. I've told the host machine about the Nginx container's web server; but I've not told the PHP container about it. Reminder as to what the docker-compose.yml is like at the moment:
version: '3'
services:
nginx:
build:
context: ./nginx
volumes:
- ../public:/usr/share/fullstackExercise/public
- ./nginx/nginx.conf:/etc/nginx/nginx.conf
- ./nginx/sites/:/etc/nginx/sites-available
- ./nginx/conf.d/:/etc/nginx/conf.d
- ../log:/var/log
depends_on:
- php-fpm
ports:
- "80:80"
stdin_open: true # docker run -i
tty: true # docker run -t
php-fpm:
build:
context: ./php-fpm
volumes:
- ..:/usr/share/fullstackExercise
stdin_open: true # docker run -i
tty: true # docker run -t
I read a whole bunch of stuff on networking in Docker. I didn't find the Docker docs very useful at the time, but now I re-read them knowing how I'm supposed to interpret them, they seem clear. Not sure if that's an indictment of me or the docs. Or both. I also looked at a whole bunch of Stack Overflow Q&A and the answers were conflicting and divergent. However after distilling what I could from all these sources, it's really pretty easy. Here's the updated version:
version: '3'
services:
nginx:
build:
context: ./nginx
volumes:
- ../public:/usr/share/fullstackExercise/public
- ./nginx/nginx.conf:/etc/nginx/nginx.conf
- ./nginx/sites/:/etc/nginx/sites-available
- ./nginx/conf.d/:/etc/nginx/conf.d
- ../log:/var/log
depends_on:
- php-fpm
ports:
- "80:80"
stdin_open: true # docker run -i
tty: true # docker run -t
networks:
- backend
php-fpm:
build:
context: ./php-fpm
volumes:
- ..:/usr/share/fullstackExercise
stdin_open: true # docker run -i
tty: true # docker run -t
networks:
- backend
networks:
backend:
driver: "bridge"
I just added the networks section, and then told the Nginx and PHP containers to be on that backend network. NB: backend has no significance as a word here, it's just a label, and one used in the docs I was reading. After rebuild, I could now see the Nginx server from the PHP container:
/usr/share/fullstackExercise # curl http://nginx/gdayWorld.php
G'day World
/usr/share/fullstackExercise #
Note that I'm using the Nginx services container name there as the host name, ie:
services:
nginx:
Not that it matters, but that seems a bit manky to me, so I wanted to specify a hostname here. That's just a matter of giving the Nginx container a hostname:
services:
nginx:
build:
context: ./nginx
hostname: webserver.backend
volumes:
# etc
/usr/share/fullstackExercise # curl http://webserver.backend/gdayWorld.php
G'day World
/usr/share/fullstackExercise #
Now my functional tests should work, provided I use that new hostname:
PHPUnit 9.5.0 by Sebastian Bergmann and contributors.
Warning: No code coverage driver available
.. 1 / 1 (100%)
Time: 00:00.462, Memory: 6.00 MB
OK (2 test, 6 assertions)
/usr/share/fullstackExercise #
Cool!
Oh there was a separate test for gdayWorld.php too:
namespace adamCameron\fullStackExercise\test\functional\_public; // "public" is reserved
use GuzzleHttp\Client;
use PHPUnit\Framework\TestCase;
use Symfony\Component\HttpFoundation\Response;
class PhpTest extends TestCase
{
/** @coversNothing */
public function testGdayWorldPhpReturnsExpectedContent()
{
$client = new Client([
'base_uri' => 'http://webserver.backend/'
]);
$response = $client->get('gdayWorld.php');
$this->assertEquals(Response::HTTP_OK, $response->getStatusCode());
$content = $response->getBody()->getContents();
$this->assertSame("G'day world", $content);
}
}
I'm glad I wrote these tests, because this one identified a small bug I had introduced into gdayWorld.php. I'd fixed it by the time I catpured that output above, but the first run was less positive:
PHPUnit 9.5.0 by Sebastian Bergmann and contributors.
Warning: No code coverage driver available
F. 2 / 2 (100%)
Time: 00:00.509, Memory: 6.00 MB
There was 1 failure:
1) adamCameron\fullStackExercise\test\functional\_public\PhpTest::testGdayWorldPhpReturnsExpectedContent
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
-'G'day world'
+'G'day World'
/usr/share/fullstackExercise/test/functional/PhpTest.php:24
FAILURES!
Tests: 2, Assertions: 6, Failures: 1.
/usr/share/fullstackExercise #
Yay for testing! I did not contrive this situation as an example of "always test first!", but there it is. This is hugely trivial code, but I still messed it up, and simply eyeballing it did not spot the bug.
Speaking of being observant… you will no-doubt have noticed the warning about code coverage driver above. I still need to install XDebug to make this work. This is a matter of adding this into the Dockerfile:
FROM php:fpm-alpine
RUN apk --update --no-cache add git
RUN docker-php-ext-install pdo_mysql
RUN pecl install xdebug-3.0.1 && docker-php-ext-enable xdebug
COPY --from=composer /usr/bin/composer /usr/bin/composer
WORKDIR /usr/share/fullstackExercise/
CMD composer install ; php-fpm
EXPOSE 9000
Or at least that was the theory:
Creating network "docker_backend" with driver "bridge"
Building php-fpm
Step 1/8 : FROM php:fpm-alpine
---> 6bd7d9173974
Step 2/8 : RUN apk --update --no-cache add git
---> Using cache
---> 098d91282e3e
Step 3/8 : RUN docker-php-ext-install pdo_mysql
---> Using cache
---> 6f74a2ec5bb1
Step 4/8 : RUN pecl install xdebug-3.0.1 && docker-php-ext-enable xdebug
---> Running in 12444e0a094c
downloading xdebug-3.0.1.tgz ...
Starting to download xdebug-3.0.1.tgz (214,467 bytes)
.............................................done: 214,467 bytes
87 source files, building
running: phpize
Configuring for:
PHP Api Version: 20200930
Zend Module Api No: 20200930
Zend Extension Api No: 420200930
Cannot find autoconf. Please check your autoconf installation and the
$PHP_AUTOCONF environment variable. Then, rerun this script.
ERROR: `phpize' failed
ERROR: Service 'php-fpm' failed to build : The command '/bin/sh -c pecl install xdebug-3.0.1 && docker-php-ext-enable xdebug' returned a non-zero code: 1
adam@DESKTOP-QV1A45U:/mnt/c/src/fullstackExercise/docker$
Sigh. I have encountered this sort of thing before with other containers. Alpine is really really pared down, and doesn't include a bunch of packages that tools might need to run. This is fine for a lot of situations, but it's also a pain in the arse for others. In this case I added in autoconf, but then I needed to install a C compiler too. And then after that I think it wanted something else. Sod that. I just stopped using Alpine and wend back to the Debian version of the container, in the Dockerfile:
FROM FROM php:8.0-fpm
RUN apt-get update --yes && apt-get install git --yes
ENV XDEBUG_MODE=coverage
FROM :fpm-alpine
RUN apk --update --no-cache add git
Note: the apk / apt-get change is just the difference in package manager between Alpine and Debian. I won't show you the installation of this because it's 70kB of telemetry, all of which culminates in:
And now we can run our functional tests, and the code coverage report should create (even if it hasn't got anything in it yet, cos I'm not code-covering those functional tests):
PHPUnit 9.5.0 by Sebastian Bergmann and contributors.
Warning: Incorrect filter configuration, code coverage will not be processed
.. 2 / 2 (100%)
Time: 00:00.493, Memory: 6.00 MB
OK (2 tests, 6 assertions)
root@2e5f56af2f54:/usr/share/fullstackExercise#
Grrrr… what now?. I reviewed the docs and my phpunit.xml was legit-looking, and validated fine, so I was flumoxed. But then I came across this issue with PHPUnit: Misleading error message when no files present in coverage path. That sums it up. I have this in my phpunit.xml file:
<coverage>
<include>
<directory suffix=".php">src</directory>
</include>
<report>
<html outputDirectory="public/test-coverage-report/" />
</report>
</coverage>
But I don't actually have a src/ directory yet. Once I added that, and also added the public/ directory into that <include> block, I get a report. At the same time, I will add a stub PHP class and test thereof into the src/ directory as well, to better test the reporting:
PHPUnit 9.5.0 by Sebastian Bergmann and contributors.
... 3 / 3 (100%)
Time: 00:02.050, Memory: 12.00 MB
OK (3 tests, 7 assertions)
Generating code coverage report in HTML format ... done [00:00.780]
root@2e5f56af2f54:/usr/share/fullstackExercise#
And the coverage report generates fine too:
above
below
The test for MyClass's needsTesting method is as simple as you might imagine:
namespace adamCameron\fullStackExercise\test\unit;
use adamCameron\fullStackExercise\MyClass;
use PHPUnit\Framework\TestCase;
/** @coversDefaultClass adamCameron\fullStackExercise\MyClass */
class MyClassTest extends TestCase
{
private $myClass;
protected function setUp(): void
{
$this->myClass = new MyClass();
}
/** @covers ::needsTesting */
public function testNeedsTesting()
{
$needsTesting = $this->myClass->needsTesting();
$this->assertTrue($needsTesting);
}
}
OK, so I'm in a good place to be able to TDD some PHP code now. But before I do that, I want to get a MariaDB container added into the mix as well, and write an intergration test for its connectivity. Before I get to that though, as I've been doing the work on this project up until now - especially when troubleshooting the networking and the PHPUnit issue I had - I've tweaked some stuff with my Bash environment, and I wanted to rip that out into a separate wee article. So before we get onto MariaDB, I'll write that up: Tweaks I made to my Bash environment in my Docker containers.
Righto.
--
Adam
