meyfa / phpunit-assert-gd
PHPUnit matcher/assertions for GD image resources
Installs: 444 570
Dependents: 12
Suggesters: 0
Security: 0
Stars: 12
Watchers: 5
Forks: 4
Open Issues: 0
Requires
- php: >=8.1
- ext-gd: *
- phpunit/phpunit: ^10.1
Requires (Dev)
- phpmd/phpmd: @stable
README
Trying to assert images with PHPUnit? This project provides a constraint and the required assertions that allow you do to so.
It supports comparing files on disk as well as image resources in memory.
Installation
Add this package to your Composer dev-dependencies:
composer require --dev meyfa/phpunit-assert-gd
Compatibility table
Examples
The assertions are available as a
trait, so you can easily
use
them in your test case class:
<?php use AssertGD\GDAssertTrait; class ExampleTest extends PHPUnit\Framework\TestCase { // this trait adds the assert methods to your test case use GDAssertTrait; public function testSomething() { $this->assertSimilarGD('./tests/expected.png', './tests/actual.png'); } }
Plain comparisons
Use assertSimilarGD
if you expect 2 images to be exactly equal.
Use assertNotSimilarGD
if you expect there to be differences.
$this->assertSimilarGD('./tests/img.png', './tests/same.png'); $this->assertNotSimilarGD('./tests/img.png', './tests/other.png');
Threshold values
Provide a number between 0 and 1 to set the error threshold. For example, a value of 0.2 would allow for at most 20% difference.
$this->assertSimilarGD('./tests/img.png', './tests/similar.png', '', 0.2);
Parameter types
Instead of file paths, you can pass in GD image resources. This eliminates having to write something to disk prior to the comparison.
$img = imagecreatetruecolor(10, 10); $this->assertSimilarGD('./tests/empty-10x10.png', $img); imagedestroy($img);
Manual constraint
If you need to configure mock objects or do other, more complex matching calls,
use isSimilarGD
to obtain a constraint object (similar to what would be
returned by equalTo
, isTrue
, etc.).
$this->assertThat( './tests/actual.png', $this->isSimilarGD('./tests/expected.png') );
Difference calculation
By default, this library calculates the difference between two images by comparing the RGBA color channel information at each pixel coordinate of the source image and the test image, and averaging the difference between each pixel to calculate the difference score.
This will work for the majority of cases, but may give incorrect scoring in certain circumstances, such as images that contain a lot of transparency.
An alternative calculation method, which scales the RGB color channels
based on their alpha transparency - meaning more transparent pixels will
affect the difficulty score less to offset their less observable difference
on the image itself - can be enabled by adding a new ScaledRgbChannels
instance to the 5th parameter of the assertSimilarGD
or assertNotSimilarGD
methods.
use AssertGD\DiffCalculator\ScaledRgbChannels; public function testImage() { $this->assertSimilarGD( 'expected.png', 'actual.png', '', 0, new ScaledRgbChannels() ); }
Custom difference calculators
If you wish to completely customise how calculations are done in this
library, you may also create your own calculation algorithm by creating
a class that implements the AssertGd\DiffCalculator
interface.
A class implementing this interface must provide a calculate
method
that is provided two GdImage
instances, and the X and Y co-ordinate
(as ints
) of the pixel being compared in both images.
The method should return a float
between 0
and 1
, where 0 is
an exact match and 1 is the complete opposite.
You may then provide an instance of the class as the 5th parameter of
the assertSimilarGD
or assertNotSimilarGD
method to use this
calculation method for determining the image difference.