vasek-purchart / phing-tester
Helper tool for writing Phing component tests using PHPUnit
Installs: 1 199
Dependents: 2
Suggesters: 0
Security: 0
Stars: 3
Watchers: 2
Forks: 1
Open Issues: 4
Requires
- php: ~7.2
- phing/phing: ^2.16.3
- phpunit/phpunit: ^8.0
Requires (Dev)
This package is auto-updated.
Last update: 2024-10-12 06:02:35 UTC
README
Phing is a build system which you can extend by writing PHP code. This is really useful, especially for PHP projects so that you do not need any additional technologies and can potentially reuse existing code. But when you are writing such extensions, you should also test them. And because the nature of the build system is printing output, manipulating files and other "system" stuff, then writing isolated tests becomes an issue. Phing Tester should help with this task by providing a way to run Phing targets from PHPUnit tests as if they were run from the command line itself.
Usage
With Phing Tester you can write a XML buildfile as usual with Phing and then run its targets from PHP code:
<?xml version="1.0" encoding="utf-8"?> <!-- phing-tester-example.xml --> <project name="PhingTesterExample" default="lorem-ipsum"> <target name="lorem-ipsum"> <echo>Lorem ipsum dolor sit amet</echo> </target> </project>
<?php use VasekPurchart\Phing\PhingTester\PhingTester; $tester = new PhingTester(__DIR__ . '/phing-tester-example.xml'); $tester->executeTarget('lorem-ipsum');
Testing output
In the example above the target lorem-ipsum
is executed in the context of the buildfile and then you can check whatever the target was supposed to achieve, in this case it should print out a message. For testing purposes it would be problematic if the actual output would be printed out, so there are Phing Tester method for output checking such as:
<?php $tester->assertLogMessage('Lorem ipsum');
assertLogMessage
searches all log messages if any contains the given string. You can also search for log messages using regexp. It is handy to refine the results by specifying target which should produce the message and/or its priority.
Testing errors
If the build fails a \BuildException
is thrown as usual in Phing. If you only want to test the exception and its message you can use standard PHPUnits tools:
<?php $this->expectException(\BuildException::class); $this->expectExceptionMessage('My error');
But if you want to also check the state after the target execution, this is not enough since the code in the test is interrupted by the exception. If you want to do that, use expectFailedBuild
instead of executeTarget
and you can continue with asserts:
<?php $tester->expectFailedBuild($target); $tester->assertLogMessage('Fail message', $target, Project::MSG_ERR);
If you need to check the thrown exception thoroughly, you can pass a callback to expectFailedBuild
and you will get the exception as parameter:
<?php $tester->expectFailedBuild($target, function (\BuildException $e) use ($target) { $this->assertRegExp(sprintf('~%s.+not.+exist~', $target), $e->getMessage()); });
Testing properties
When writing Phing tests you might want to check the state of some properties or use them for writing other assertions:
<?php $this->assertSame('bar', $tester->getProject()->getProperty('foo'));
Convention
There is no enforced convention for using this tool, you can use it in tests however you feel right, but this approach works for me in terms of readability the most:
- Match one TestCase with one buildfile.
- Targets in the buildfile represent individual tests and their name matches (if there is no need to reuse the targets or use more targets for one test).
- When asserting log output, try to be more specific - use target name and output priority to minimalize false positives/negatives.
The pair can then look something like:
<?xml version="1.0" encoding="utf-8"?> <!-- phing-tester-convention-example.xml --> <project name="PhingTesterConventionExample" default="test"> <target name="testFoo"> <echo>Foo</echo> </target> <target name="testBar"> <echo>Bar</echo> </target> </project>
<?php use VasekPurchart\Phing\PhingTester\PhingTester; class PhingTesterConventionExampleTest extends \PHPUnit\Framework\TestCase { public function testFoo() { $tester = new PhingTester(__DIR__ . '/phing-tester-convention-example.xml'); $target = __FUNCTION__; $tester->executeTarget($target); $tester->assertLogMessage('Foo', $target, Project::MSG_INFO); } public function testBar() { $tester = new PhingTester(__DIR__ . '/phing-tester-convention-example.xml'); $target = __FUNCTION__; $tester->executeTarget($target); $tester->assertLogMessage('Bar', $target, Project::MSG_INFO); } }
Installation
- Install package
vasek-purchart/phing-tester
with Composer:
composer require --dev vasek-purchart/phing-tester
- Add Phing initialization to your tests bootstrap file (example in this repo):
Phing::startup();