phug / tester
Test and coverage utils for Pug (ex-Jade) templates rendered with the Phug engine
Fund package maintenance!
kylekatarnls
Open Collective
Tidelift
Requires
- php: >=7.1.0
- ext-xdebug: *
- phpunit/phpunit: ^6.0 || ^7.0 || ^8.0
- phug/renderer: ^0.4.0
Requires (Dev)
- phug/dev-tool: ^0.1.12
README
What is Phug Tester?
The Phug tester allow you to write unit tests easily for your Phug templates and get coverage of your tests.
As a PHPUnit extension, you can use all the features,
options and same code you use usually running phpunit
when your run the
phug-tester
command.
Installation
Install via Composer
composer require phug/tester
Requirements:
- PHP >= 7.0
- XDebug PHP extension
- PHPUnit >= 5.7 (installed automatically via composer)
Usage
./vendor/bin/phug-tester --pug-coverage-threshold=90 --pug-coverage-text --pug-coverage-html=coverage/pug
You can couple it with PHP coverage data as phug-tester use PHPUnit and is compatible with all its options:
./vendor/bin/phug-tester --coverage-text --pug-coverage-text --coverage-html=coverage --pug-coverage-html=coverage/pug
This will output in the CLI both PHP and Pug coverage summaries and it will dump as HTML PHP coverage in the directory coverage and Pug coverage in the sub-directory coverage/pug.
<?php class MyTemplatesTest extends Phug\Tester\TestCase { public function testContactView() { $html = $this->renderFile('views/contact.pug', [ 'title' => 'Add some locals', ]); self::assertContains('Bar', $html); self::assertNotContains('Foo', $html); } }
The Phug\Tester\TestCase
is needed to use Pug utils such as
renderFile
or if you need to get both PHP and Pug coverage in
a single command.
As an alternative if you extend an other class, you can use the trait:
<?php class MyTemplatesTest extends MyFramerowk\TestCase { use Phug\Tester\TestCaseTrait; }
Options
--pug-coverage-text
display Pug coverage summary in the standard
output of the CLI if present.
--pug-coverage-html
dump coverage data as HTML in a directory, you
have to specify the directory,
example: --pug-coverage-html=/path/to/output/directory
.
--pug-coverage-threshold
test the coverage rate against a threshold,
the command will fail if the threshold is not reached (status 1) and
succeed if if does (status 0), you must specify a percentage between
0 and 100, example: --pug-coverage-threshold=90
Configuration
When using TestCaseTrait
or extending TestCase
, configuration
methods are available to align the renderer behavior on your app
test needs.
getPaths
by default['views']
, allows you to change base directories where your templates live.getExtensions
by default['', '.pug', '.jade']
, allows you to change file extensions to detect as pug files (and suffixes that will be tried to be appended automatically). The default value implies for example that when calling->renderFile('contact')
it will look for the filescontact
,contact.pug
andcontact.jade
.getRenderer
by default'Phug\Renderer'
, allows you to change the renderer engine to be used. It can be a class name (then it will be created on the fly) or it can be an instance used as is. But if you return an instance, you need to set the options manually on it.getRendererOptions
by default:
[ 'extensions' => (array) $this->getExtensions(), 'paths' => (array) $this->getPaths(), 'debug' => true, 'cache_dir' => $cacheDirectory ?: sys_get_temp_dir().'/pug-cache-'.mt_rand(0, 9999999), ]
$cacheDirectory
can be passed as an argument of the method.
By returning a new array in this method, you erase and replace all the
options, but by using array_merge
you can add an merge new options.
For example to add shared variables:
protected function getRendererOptions($cacheDirectory = null) { return array_merge(parent::getRendererOptions($cacheDirectory), [ 'shared_variables' => [ 'locale' => 'en', 'user' => new User(), ], ]; }