By James Titcumb

There is a new movement in the PHP community! Well, it isn’t exactly new, but an event called PHP TestFest is back. PHP TestFest is a global event organized by the PHP community at large, where an effort is made each time to increase the test coverage of the PHP engine itself. Around eight or nine years ago, user groups around the world coordinated to organize events spanning a few months each year, with some groups continuing events annually for several years after.

PHP itself is a massive project with over 200,000 lines of code, used by possibly millions of developers. To ensure it doesn’t break in unexpected ways there needs to be a good coverage of tests. Now, before you run off, the thing that puts many people off is thinking they need to know C to contribute, but there’s some great news: the tests for PHP are written in PHP—so you don’t need to know C! PHP TestFest encourages user groups, conferences, or even just an ad-hoc gathering of developers to join forces to write these tests for the engine. PHP TestFest runs from September to December this year, so there’s a good window of opportunity to get involved.

If you attend or organize a local user group, or want to plan one of these events, it’s easy to get started. First, you’ll need to set a date for your event. Agree on a date where as many interested folks can attend as possible—that might be on an evening during the week, or even during the weekend. If you’re part of a PHP user group, it might be a cool change to replace your regular monthly meet up with a PHP TestFest event. If you’re unsure, consider sending out a poll to anyone interested to see what works best for them. For the event, you’ll need tables for laptops and so on, as well as a good, stable Wi-Fi connection—and don’t forget you’ll need more bandwidth the more attendees you have.

Writing Tests

So how does one actually write these tests? In brief, it’s a text file with a few sections: TEST, FILE, and an EXPECT or EXPECTF. The TEST section is the description of the test, and it helps to explain what behavior you’re trying to test here. The FILE section contains the PHP code that will be run. Finally, the EXPECT or EXPECTF section is for the expected output; the latter, EXPECTF, allowing for formatting marks. For example:

--TEST--
Trivial "Hello World" test
--FILE--
<?php echo "Hello world" ?>
--EXPECT--
Hello World

This is a very trivial example but also knowing how EXPECTF works proves very useful. For example, if you are writing out a file path where the document root will be different on each system, you can replace the root path with %s:

--TEST--
Example using EXPECTF
--FILE--
<?php
echo sys_get_temp_dir() . "/foo\n";
?>
--EXPECTF--
%s/foo

All the pain of running tests has been eliminated too, with the new docker-phpqa open source tool specifically designed to help create PHPT test files and run them against multiple versions of PHP simultaneously. As the name suggests, you do need Docker installed on your machine, but assuming that’s the case, it should be pretty quick to get up and running to write PHPT tests. Running the commands to test against multiple versions of PHP, seems to be immensely helpful here, for example, running:

phpqa run path/to/my/test.phpt all

will run the test against all versions of PHP the tool supports, which is currently 7.2, 7.1, 7.0, 5.6 and 5.5.

The nice thing about this process is there are a wealth of articles, videos, tutorials, and so on which document how to write, run, and contribute these tests back to PHP core. For quite some time, https://qa.php.net has existed and served as a great starting point for writing tests—including links to test result coverage on PHP’s GCOV site, guides on writing tests, running them, and more.

This year, however, Ben Ramsey has been leading an effort to re-ignite this tradition in the PHP community and has launched a shiny new site, https://phptestfest.org, which collates a huge amount of these resources. At the time of writing this, there is some basic information on how to organize an event and a list of user groups from around the world who have already opted to participate in the activity. There is a new fully comprehensive six-part video series from Sammy Kaye Powers demonstrating how to build PHP from source, running the test suite, a look into the PHPT file format and debugging, all the way to submitting a PR to the PHP repository itself. He does a fantastic job of working through the tutorial and explains everything in an easy to understand way, so I highly recommend checking this out.

Head on over to the PHP TestFest website now and check out all the useful resources and links, as well as ways to get involved, such as organizing a meetup, chatting on the IRC channel (#phptestfest on freenode), or joining the Google Group. Finally, big thanks to Ben Ramsey for leading this renewed effort, as well as the many contributors to this awesome PHP TestFest venture!

Biography

James is a consultant, trainer and developer at Roave. He is a prolific contributor to various open source projects and is a Zend Certified Engineer. He also founded the UK based PHP Hampshire user group and PHP South Coast conference. @asgrim