QgsRenderChecker class

This is a helper class for unit tests that need to write an image and compare it to an expected result or render time.

Reference

Public static functions

static void drawBackground(QImage* image): Draws a checkboard pattern for image backgrounds, so that opacity is visible without requiring a transparent background for the image.

Constructors, destructors, conversion operators

QgsRenderChecker() defaulted: Constructor for QgsRenderChecker.

Public functions

auto compareImages(const QString& testName, unsigned int mismatchCount = 0, const QString& renderedImageFile = QString()) -> bool: Test using two arbitrary images (map renderer will not be used)
auto dartMeasurements() const -> QVector<QgsDartMeasurement>: Gets access to buffered dash messages.
void enableDashBuffering(bool enable): Call this to enable internal buffering of dash messages.
auto expectedImageFile() const -> QString: Returns the path to the expected image file.
auto imageToHash(const QString& imageFile) -> QString: Gets an md5 hash that uniquely identifies an image.
auto isKnownAnomaly(const QString& diffImageFile) -> bool: Gets a list of all the anomalies.
auto renderedImage() -> QString: The path of the rendered image can be retrieved through that method.
auto runTest(const QString& testName, unsigned int mismatchCount = 0) -> bool: Test using renderer to generate the image to be compared.
void setColorTolerance(unsigned int colorTolerance): Set tolerance for color components used by runTest() and compareImages().
void setControlName(const QString& name): Base directory name for the control image (with control image path suffixed) the path to the image will be constructed like this: controlImagePath + '/' + mControlName + '/' + mControlName + '.png'.
void setControlPathPrefix(const QString& name): Prefix where the control images are kept.
void setMapSettings(const QgsMapSettings& mapSettings)
void setSizeTolerance(int xTolerance, int yTolerance): Sets the largest allowable difference in size between the rendered and the expected image.

Function documentation

bool QgsRenderChecker::compareImages(const QString& testName, unsigned int mismatchCount = 0, const QString& renderedImageFile = QString())

Test using two arbitrary images (map renderer will not be used)

Parameters
testName	- to be used as the basis for writing a file to e.g. /tmp/theTestName.png
mismatchCount	- defaults to 0 - the number of pixels that are allowed to be different from the control image. In some cases rendering may be non-deterministic. This parameter allows you to account for that by providing a tolerance.
renderedImageFile	to optionally override the output filename

QVector<QgsDartMeasurement> QgsRenderChecker::dartMeasurements() const

Gets access to buffered dash messages.

Returns	buffered dash messages

Only will return something if you call enableDashBuffering( true ); before.

void QgsRenderChecker::enableDashBuffering(bool enable)

Call this to enable internal buffering of dash messages.

Parameters
enable	Enable or disable buffering

You may later call dashMessages() to get access to the buffered messages. If disabled (default) dash messages will be sent immediately.

QString QgsRenderChecker::expectedImageFile() const

Returns the path to the expected image file.

Returns	Path to the expected image file

bool QgsRenderChecker::isKnownAnomaly(const QString& diffImageFile)

Gets a list of all the anomalies.

Returns	a bool indicating if the diff matched one of the anomaly files

An anomaly is a rendered difference file where there is some red pixel content (indicating a render check mismatch), but where the output was still acceptable. If the render diff matches one of these anomalies we will still consider it to be acceptable.

QString QgsRenderChecker::renderedImage()

The path of the rendered image can be retrieved through that method.

Returns	The path to the rendered image

Will return the path set with setRenderedImage() or generated in runTest()

bool QgsRenderChecker::runTest(const QString& testName, unsigned int mismatchCount = 0)

Test using renderer to generate the image to be compared.

Parameters
testName	- to be used as the basis for writing a file to e.g. /tmp/theTestName.png
mismatchCount	- defaults to 0 - the number of pixels that are allowed to be different from the control image. In some cases rendering may be non-deterministic. This parameter allows you to account for that by providing a tolerance.

void QgsRenderChecker::setColorTolerance(unsigned int colorTolerance)

Set tolerance for color components used by runTest() and compareImages().

Parameters
colorTolerance	is maximum difference for each color component including alpha to be considered correct.

Default value is 0.

void QgsRenderChecker::setControlPathPrefix(const QString& name)

Prefix where the control images are kept.

This will be appended to controlImagePath

void QgsRenderChecker::setMapSettings(const QgsMapSettings& mapSettings)

void QgsRenderChecker::setSizeTolerance(int xTolerance, int yTolerance)

Sets the largest allowable difference in size between the rendered and the expected image.

Parameters
xTolerance	x tolerance in pixels
yTolerance	y tolerance in pixels