G'day:
This is not the article I intended to write today. Today (well: I hoped to have it done by yesterday, actually) I had hoped to be writing about my happy times doing using TDD to implement a coupla end-points I need in my Symfony-driven web service. I got 404 (chuckle) words into that and then was blocked by trying to get Kahlan to play nice for about five hours (I did have dinner in that time too, but it was add my desk, and with a scowl on my face googling stuff). And that put me at 1am so I decided to go to bed. I resumed today an hour or so ago, and am just now in the position to get going again. But I've decided to document that lost six hours first.
I sat down to create a simple endpoint to fetch some data, and started by deciding on my first test case, which was "It needs to return a 200-OK status for GET requests on the /workshops endpoint". I knew Symfony did some odd shenanigans to be able to functionally test right from a route slug rather than having tests directly instantiating controller classes and such. I checked the docs and all this is done via an extension of PHPUnit, using WebTestCase. But I don't wanna use PHPUnit for this. Can you imagine my test case name? Something like: testItNeedsToReturnA200OKStatusForGetRequestsOnTheWorkshopsEndpoint. Or I could break PSR-12/PSR-1 and make it (worse) with test_it_needs_to_Return_a_200_OK_status_for_get_requests_on_the_workshops_endpoint (this is why I will never use phpspec). Screw that. I'm gonna work out how to do these Symfony WebTestCase tests in Kahlan.
Not so fast mocking PHPUNit there, Cameron
2021-03-06
Due to some - probably show-stopping - issues I'm seeing with Kahlan, I have been looking at PHPUnit some more. I just discovered the textdox reporting functionality it has, which makes giving test case names much clearer.
/** @testdox Tests the /workshops endpoint methods */
class workshopsEndPointTet {
/** @testdox it needs to return a 200-OK status for GET requests */
function testReturnStatus() {}
}
This will output in the test runs as:
Perfect. I still prefer the style of code Kahlan uses, but… this is really good to know.
First things first, I rely heavily on PHPUnit's code coverage analysis, so I wanted to check out Kahan's offering. The docs seem pretty clear ("Code Coverage"), and seems I just want to be using the lcov integration Kahlan offers, like this:
genhtml --output-directory public/lcov/ var/tmp/lcov/coverage.info
I need to install lcov first via my Dockerfile:
RUN apt-get install lcov --yes
OK so I did all that, and had a look at the report:
Pretty terrible coverage, but it's working. Excellent. But drilling down into the report I see this:
>
This is legit reporting because I have no tests for the Kernel class, but equally that class is generated by Symfony and I don't want to cover that. How do I exclude it from code coverage analysis? I'm looking for Kahlan's equivalent of PHPUnit's @codeCoverageIgnore. There's nothing in the docs, and all I found was a passing comment against an issue in Github asking the same question I was: "Exclude a folder in code coverage #321". The answer is to do this sort of thing to my kahlan-config.php file:
use Kahlan\Filter\Filters;
use Kahlan\Reporter\Coverage;
use Kahlan\Reporter\Coverage\Driver\Xdebug;
$commandLine = $this->commandLine();
$commandLine->option('no-header', 'default', 1);
Filters::apply($this, 'coverage', function($next) {
if (!extension_loaded('xdebug')) {
return;
}
$reporters = $this->reporters();
$coverage = new Coverage([
'verbosity' => $this->commandLine()->get('coverage'),
'driver' => new Xdebug(),
'path' => $this->commandLine()->get('src'),
'exclude' => [
'src/Kernel.php'
],
'colors' => !$this->commandLine()->get('no-colors')
]);
$reporters->add('coverage', $coverage);
});
That seems a lot of messing around to do something that seems like it should be very simple to me. I will also note that Kahlan - currently - has no ability to suppress code coverage at a method or code-block level either (see "Skip individual functions in code coverage? #333"). This is not a deal breaker for me in this work, but it would be a show-stopper on any of the codebases I have worked on in the last decade, as they've all been of dubious quality, and all needed some stuff to be actively "overlooked" as they're not testable as they currently stand, and we (/) like my baseline code coverage report to have 100% coverage reported, and be entirely green. This is so if any omissions creep in, they're easy to spot (see "Yeah, you do want 100% test coverage"). Anyway, I'll make that change and omit Kernel from analysis:
................. 17 / 17 (100%)
Expectations : 51 Executed
Specifications : 0 Pending, 0 Excluded, 0 Skipped
Passed 17 of 17 PASS in 0.527 seconds (using 7MB)
Coverage Summary
----------------
Total: 33.33% (1/3)
Coverage collected in 0.001 seconds
root@13038aa90234:/usr/share/fullstackExercise# genhtml --output-directory public/lcov/ var/tmp/lcov/coverage.info
Reading data file var/tmp/lcov/coverage.info
Found 2 entries.
Found common filename prefix "/usr/share/fullstackExercise"
Writing .css and .png files.
Generating output.
Processing file src/MyClass.php
Processing file src/Controller/GreetingsController.php
Writing directory view page.
Overall coverage rate:
lines......: 33.3% (1 of 3 lines)
functions..: 50.0% (1 of 2 functions)
root@13038aa90234:/usr/share/fullstackExercise#
And the report now doesn't mention Kernel:
Cool.
Now to implement that test case. I need to work out how to run a Symfony request without using WebTestCase. Well I say "I need to…" I mean I need to google someone else who's already done it, and copy them. I have NFI how to do it, and I'm not prepared to dive into Symfony code to find out how. Fortunately someone has already cracked this one: "Functional Test Symfony 4 with Kahlan 4". It says "Symfony 4", but I'll check if it works on Symfony 5 too. I also happened back to the Kahlan docs, and they mention the same guy's solution ("Integration with popular frameworks › Symfony"). This one points to a library to encapsulate it (elephantly/kahlan-bundle), but that is actively version-constrained to only Symfony 4. Plus it's not seen any work since 2017, so I suspect it's abandoned.
Anyway, back to samsonasik's blog article. It looks like this is the key bit:
$this->request = Request::createFromGlobals();
$this->kernel = new Kernel('test', false);
$request = $this->request->create('/lucky/number', 'GET');
$response = $this->kernel->handle($request);
That's how to create a Request and get Symfony's Kernel to run it. Easy. Hopefully. Let's try it.
namespace adamCameron\fullStackExercise\spec\functional\Controller;
use adamCameron\fullStackExercise\Kernel;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
describe('Tests of GreetingsController', function () {
beforeAll(function () {
$this->request = Request::createFromGlobals();
$this->kernel = new Kernel('test', false);
});
describe('Tests of doGet', function () {
it('returns a JSON greeting object', function () {
$testName = 'Zachary';
$request = $this->request->create("/greetings/$testName", 'GET');
$response = $this->kernel->handle($request);
expect($response->getStatusCode())->toBe(Response::HTTP_OK);
});
});
});
I'm not getting too ambitious here, and it's not addressing the entire test case yet. I'm just making the request and checking its response status code.
And this just goes splat:
E 18 / 18 (100%)
Tests of GreetingsController
Tests of doGet
✖ it returns a JSON greeting object
an uncaught exception has been thrown in `vendor/symfony/framework-bundle/Kernel/MicroKernelTrait.php` line 91
message:`Kahlan\PhpErrorException` Code(0) with message "`E_WARNING` require(/tmp/kahlan/usr/share/fullstackExercise/src/config/bundles.php): Failed to open stream: No such file or directory"
[NA] - vendor/symfony/framework-bundle/Kernel/MicroKernelTrait.php, line to 91
Eek. I had a look into this, and the code in question is try to do this:
$contents = require $this->getProjectDir().'/config/bundles.php';
And the code in getProjectDir is thus:
<pre class="source-code"><code>public function getProjectDir()
{
if (null === $this->projectDir) {
$r = new \ReflectionObject($this);
if (!is_file($dir = $r->getFileName())) {
throw new \LogicException(sprintf('Cannot auto-detect project dir for kernel of class "%s".', $r->name));
}
$dir = $rootDir = \dirname($dir);
while (!is_file($dir.'/composer.json')) {
if ($dir === \dirname($dir)) {
return $this->projectDir = $rootDir;
}
$dir = \dirname($dir);
}
$this->projectDir = $dir;
}
return $this->projectDir;
}
</code></pre>
The code starts in the directory of the current file, and traverses up the directory structure until it finds the directory with composer.json.If it doesn't find that, then - somewhat enigmatically, IMO - it just says "ah now, we'll just use the directory we're in now. It'll be grand". To me if it expects to find what it's looking for by looking up the ancestor directory path and that doesn't work: throw an exception. Still. In the normal scheme of things, this would work cos the app's Kernel class - by default - seems to live in the src directory, which is one down from where composer.json is.
So why didn't it work? Look at the directory that it's trying to load the bundles from: /tmp/kahlan/usr/share/fullstackExercise/src/config/bundles.php. Where? /tmp/kahlan/usr/share/fullstackExercise/. Ain't no app code in there, pal. It's in /usr/share/fullstackExercise/. Why's it looking in there? Because the Kernel object that is initiating all this is at /tmp/kahlan/usr/share/fullstackExercise/src/Kernel.php. It's not the app's own one (at /usr/share/fullstackExercise/src/Kernel.php), it's all down to how Kahlan monkey-patches everything that's going to be called by the test code, on the off chance you want to spy on anything. It achieves this by loading the source code of the classes, patching the hell out of it, and saving it in that /tmp/kahlan. The only problem with this is that when Symfony traverses up from where the patched Kernel class is… it never finds composer.json, so it just takes a guess at where the project directory is. And it's not a well-informed guess.
I'm not sure who I blame more here, to be honest. Kahlan for patching everything and running code from a different directory from where it's supposed to be; or Symfony for its "interesting" way to know where the project directory is. I have an idea here, Symfony: you could just ask me. Or even force me tell it. Ah well. Just trying to be "helpful" I s'pose.
Anyway, I can exclude files from being patched, according to the docs:
--exclude=<string> Paths to exclude from patching. (default: `[]`).
I tried sticking the path to Kernel in there: src/Kernel.php, and that didn't work. I hacked about in the code and it doesn't actually want a path, it wants the fully-qualified class name, eg: adamCameron\fullStackExercise\Kernel. I've raised a ticket for this with Kahlan, just to clarify the wording there: Bug: bad nomenclature in help: "path" != "namespace".
This does work…
E 18 / 18 (100%)
Tests of GreetingsController
Tests of doGet
✖ it returns a JSON greeting object
an uncaught exception has been thrown in `vendor/symfony/deprecation-contracts/function.php` line 25
message:`Kahlan\PhpErrorException` Code(0) with message "`E_USER_DEPRECATED` Please install the \"intl\" PHP extension for best performance."
[NA] - vendor/symfony/deprecation-contracts/function.php, line to 25
trigger_deprecation - vendor/symfony/framework-bundle/DependencyInjection/FrameworkExtension.php, line to 253
This is not exactly what I want, but it's a different error, so Symfony is finding itself this time, and then just faceplanting again. However when I look into the code, it's this:
if (!\extension_loaded('intl') && !\defined('PHPUNIT_COMPOSER_INSTALL')) {
trigger_deprecation('', '', 'Please install the "intl" PHP extension for best performance.');
}
// which in turn...
function trigger_deprecation(string $package, string $version, string $message, ...$args): void
{
@trigger_error(($package || $version ? "Since $package $version: " : '').($args ? vsprintf($message, $args) : $message), \E_USER_DEPRECATED);
}
So Symfony is very quietly raising a flag that it suggests I have that extension installed. But only as a deprecation notice, and even then it's @-ed out. Somehow Kahlan is getting hold of that and going "nonono, this is worth stopping for". No it ain't. Ticket raised: "Q: should trigger_error type E_USER_DEPRECATED cause testing to halt?".
Anyway, the point is a legit one, so I'll install the intl extension. I initially thought it was just a matter of slinging this in the Dockerfile:
RUN apt-get install --yes zlib1g-dev libicu-dev g++
RUN docker-php-ext-install intl
But that didn't work, I needed a bunch of Other Stuff too:
RUN apt-get install --yes zlib1g-dev libicu-dev g++
RUN docker-php-ext-install pdo_mysql
RUN docker-php-ext-configure intl
RUN docker-php-ext-install intl
(Thanks to the note in docker-php-ext-install intl fails #57 for solving that for me).
After rebuilding the container, let's see what goes wrong next:
> vendor/bin/kahlan --lcov="var/tmp/lcov/coverage.info" --exclude=adamCameron\\fullStackExercise\\Kernel
.................. 18 / 18 (100%)
Expectations : 52 Executed
Specifications : 0 Pending, 0 Excluded, 0 Skipped
Passed 18 of 18 PASS in 0.605 seconds (using 12MB)
Coverage Summary
----------------
Total: 100.00% (3/3)
Coverage collected in 0.001 seconds
> genhtml --output-directory public/lcov/ var/tmp/lcov/coverage.info
Reading data file var/tmp/lcov/coverage.info
Found 2 entries.
Found common filename prefix "/usr/share/fullstackExercise"
Writing .css and .png files.
Generating output.
Processing file src/MyClass.php
Processing file src/Controller/GreetingsController.php
Writing directory view page.
Overall coverage rate:
lines......: 100.0% (3 of 3 lines)
functions..: 100.0% (2 of 2 functions)
root@58e3325d1a16:/usr/share/fullstackExercise#
(I've stuck a Composer script in for this, btw):
"coverage": [
"vendor/bin/kahlan --lcov=\"var/tmp/lcov/coverage.info\" --exclude=adamCameron\\\\fullStackExercise\\\\Kernel",
"genhtml --output-directory public/lcov/ var/tmp/lcov/coverage.info"
]
And most promising of all is this:
All green! I like that.
And now I'm back to where I wanted to be, yesterday, as I typed that 404th word of the article I was meant to be working on. 24h later now.
Righto.
--
Adam
