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

#include <qgsrenderchecker.h>

Public Member Functions
	QgsRenderChecker ()
	Constructor for QgsRenderChecker. More...

bool	compareImages (const QString &testName, const QString &referenceImageFile, const QString &renderedImageFile, unsigned int mismatchCount=0)
	Test using two arbitrary images at the specified paths for equality. More...

bool	compareImages (const QString &testName, unsigned int mismatchCount=0, const QString &renderedImageFile=QString())
	Test using two arbitrary images (map renderer will not be used) More...

QString	controlImagePath () const
	Returns the base path containing the reference images. More...

QVector< QgsDartMeasurement >	dartMeasurements () const
	Gets access to buffered dash messages. More...

int	elapsedTime ()
	Returns the total elapsed time for the rendering test. More...

void	enableDashBuffering (bool enable)
	Call this to enable internal buffering of dash messages. More...

QString	expectedImageFile () const
	Returns the path to the expected image file. More...

QString	imageToHash (const QString &imageFile)
	Gets an md5 hash that uniquely identifies an image. More...

bool	isKnownAnomaly (const QString &diffImageFile)
	Gets a list of all the anomalies. More...

float	matchPercent () const
	Returns the percent of pixels which matched the control image. More...

unsigned int	matchTarget () const
	Returns the total number of pixels in the control image. More...

unsigned int	mismatchCount () const
	Returns the number of pixels which did not match the control image. More...

QString	renderedImage () const
	Returns the path of the rendered image generated by the test. More...

QString	report ()
	Returns the HTML report describing the results of the test run. More...

bool	runTest (const QString &testName, unsigned int mismatchCount=0)
	Test using renderer to generate the image to be compared. More...

void	setColorTolerance (unsigned int colorTolerance)
	Set tolerance for color components used by runTest() and compareImages(). More...

void	setControlExtension (const QString &extension)
	Sets file extension for the control image. More...

void	setControlImagePath (const QString &path)
	Sets the base path containing the reference images. More...

void	setControlName (const QString &name)
	Sets the base directory name for the control image (with control image path suffixed). More...

void	setControlPathPrefix (const QString &name)
	Sets the path prefix where the control images are kept. More...

void	setControlPathSuffix (const QString &name)

void	setElapsedTimeTarget (int target)

void	setMapSettings (const QgsMapSettings &mapSettings)

void	setRenderedImage (const QString &imageFileName)
	Sets the file name of the rendered image generated by the test. More...

void	setSizeTolerance (int xTolerance, int yTolerance)
	Sets the largest allowable difference in size between the rendered and the expected image. More...

Static Public Member 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. More...

Protected Attributes
int	mElapsedTime = 0

QString	mExpectedImageFile

unsigned int	mMatchTarget = 0

QString	mRenderedImageFile

QString	mReport

Detailed Description

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

Definition at line 38 of file qgsrenderchecker.h.

Constructor & Destructor Documentation

◆ QgsRenderChecker()

QgsRenderChecker::QgsRenderChecker ( )

Constructor for QgsRenderChecker.

Definition at line 31 of file qgsrenderchecker.cpp.

Member Function Documentation

◆ compareImages() [1/2]

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

Test using two arbitrary images at the specified paths for equality.

Since: QGIS 3.18

Definition at line 258 of file qgsrenderchecker.cpp.

◆ compareImages() [2/2]

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

Note: : make sure to call setExpectedImage and setRenderedImage first.

Definition at line 241 of file qgsrenderchecker.cpp.

◆ controlImagePath()

QString QgsRenderChecker::controlImagePath ( ) const

Returns the base path containing the reference images.

This defaults to an internal QGIS test data path, but can be changed via setControlImagePath().

See also: setControlImagePath()

Definition at line 36 of file qgsrenderchecker.cpp.

◆ dartMeasurements()

QVector<QgsDartMeasurement> QgsRenderChecker::dartMeasurements ( ) const

inline

Gets access to buffered dash messages.

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

Returns: buffered dash messages

Definition at line 224 of file qgsrenderchecker.h.

◆ drawBackground()

void QgsRenderChecker::drawBackground ( QImage * image )

static

Draws a checkboard pattern for image backgrounds, so that opacity is visible without requiring a transparent background for the image.

Definition at line 78 of file qgsrenderchecker.cpp.

◆ elapsedTime()

int QgsRenderChecker::elapsedTime ( )

inline

Returns the total elapsed time for the rendering test.

Note: this only records time for actual render part.

Definition at line 93 of file qgsrenderchecker.h.

◆ enableDashBuffering()

void QgsRenderChecker::enableDashBuffering ( bool enable )

inline

Call this to enable internal buffering of dash messages.

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

Parameters

enable Enable or disable buffering

Definition at line 216 of file qgsrenderchecker.h.

◆ expectedImageFile()

QString QgsRenderChecker::expectedImageFile ( ) const

inline

Returns the path to the expected image file.

Returns: Path to the expected image file

Definition at line 207 of file qgsrenderchecker.h.

◆ imageToHash()

QString QgsRenderChecker::imageToHash ( const QString & imageFile )

Gets an md5 hash that uniquely identifies an image.

Definition at line 60 of file qgsrenderchecker.cpp.

◆ isKnownAnomaly()

bool QgsRenderChecker::isKnownAnomaly ( const QString & diffImageFile )

Gets a list of all the anomalies.

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.

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

Definition at line 99 of file qgsrenderchecker.cpp.

◆ matchPercent()

float QgsRenderChecker::matchPercent ( ) const

inline

Returns the percent of pixels which matched the control image.

Definition at line 72 of file qgsrenderchecker.h.

◆ matchTarget()

unsigned int QgsRenderChecker::matchTarget ( ) const

inline

Returns the total number of pixels in the control image.

Definition at line 86 of file qgsrenderchecker.h.

◆ mismatchCount()

unsigned int QgsRenderChecker::mismatchCount ( ) const

inline

Returns the number of pixels which did not match the control image.

Definition at line 81 of file qgsrenderchecker.h.

◆ renderedImage()

QString QgsRenderChecker::renderedImage ( ) const

inline

Returns the path of the rendered image generated by the test.

This method will return either the path set with setRenderedImage() or generated in runTest().

Definition at line 132 of file qgsrenderchecker.h.

◆ report()

QString QgsRenderChecker::report ( )

inline

Returns the HTML report describing the results of the test run.

Definition at line 67 of file qgsrenderchecker.h.

◆ 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.

Note: make sure to call setExpectedImage and setMapRenderer first

Definition at line 159 of file qgsrenderchecker.cpp.

◆ setColorTolerance()

void QgsRenderChecker::setColorTolerance ( unsigned int colorTolerance )

inline

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

Default value is 0.

Parameters

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

Since: QGIS 2.1

Definition at line 144 of file qgsrenderchecker.h.

◆ setControlExtension()

void QgsRenderChecker::setControlExtension ( const QString & extension )

inline

Sets file extension for the control image.

By default it is "png"

Since: QGIS 3.20

Definition at line 109 of file qgsrenderchecker.h.

◆ setControlImagePath()

void QgsRenderChecker::setControlImagePath ( const QString & path )

Sets the base path containing the reference images.

See also: controlImagePath()

Since: QGIS 3.18

Definition at line 41 of file qgsrenderchecker.cpp.

◆ setControlName()

void QgsRenderChecker::setControlName ( const QString & name )

Sets the base directory name for the control image (with control image path suffixed).

The path to the image will be constructed like this: controlImagePath() + '/' + control name + '/' + control name + '.' + extension ('png' by default)

Definition at line 46 of file qgsrenderchecker.cpp.

◆ setControlPathPrefix()

void QgsRenderChecker::setControlPathPrefix ( const QString & name )

inline

Sets the path prefix where the control images are kept.

This will be appended to controlImagePath().

Definition at line 115 of file qgsrenderchecker.h.

◆ setControlPathSuffix()

void QgsRenderChecker::setControlPathSuffix ( const QString & name )

Definition at line 52 of file qgsrenderchecker.cpp.

◆ setElapsedTimeTarget()

void QgsRenderChecker::setElapsedTimeTarget ( int target )

inline

Definition at line 94 of file qgsrenderchecker.h.

◆ setMapSettings()

void QgsRenderChecker::setMapSettings ( const QgsMapSettings & mapSettings )

Since: QGIS 2.4

Definition at line 73 of file qgsrenderchecker.cpp.

◆ setRenderedImage()

void QgsRenderChecker::setRenderedImage ( const QString & imageFileName )

inline

Sets the file name of the rendered image generated by the test.

Definition at line 125 of file qgsrenderchecker.h.

◆ setSizeTolerance()

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

inline

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

Since: QGIS 2.12

Definition at line 152 of file qgsrenderchecker.h.

Member Data Documentation

◆ mElapsedTime

int QgsRenderChecker::mElapsedTime = 0

protected

Definition at line 229 of file qgsrenderchecker.h.

◆ mExpectedImageFile

QString QgsRenderChecker::mExpectedImageFile

protected

Definition at line 231 of file qgsrenderchecker.h.

◆ mMatchTarget

unsigned int QgsRenderChecker::mMatchTarget = 0

protected

Definition at line 228 of file qgsrenderchecker.h.

◆ mRenderedImageFile

QString QgsRenderChecker::mRenderedImageFile

protected

Definition at line 230 of file qgsrenderchecker.h.

◆ mReport

QString QgsRenderChecker::mReport

protected

Definition at line 227 of file qgsrenderchecker.h.

The documentation for this class was generated from the following files:

/build/qgis-3.20.0+99unstable/src/core/qgsrenderchecker.h
/build/qgis-3.20.0+99unstable/src/core/qgsrenderchecker.cpp

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QgsRenderChecker()

Member Function Documentation

◆ compareImages() [1/2]

◆ compareImages() [2/2]

◆ controlImagePath()

◆ dartMeasurements()

◆ drawBackground()

◆ elapsedTime()

◆ enableDashBuffering()

◆ expectedImageFile()

◆ imageToHash()

◆ isKnownAnomaly()

◆ matchPercent()

◆ matchTarget()

◆ mismatchCount()

◆ renderedImage()

◆ report()

◆ runTest()

◆ setColorTolerance()

◆ setControlExtension()

◆ setControlImagePath()

◆ setControlName()

◆ setControlPathPrefix()

◆ setControlPathSuffix()

◆ setElapsedTimeTarget()

◆ setMapSettings()

◆ setRenderedImage()

◆ setSizeTolerance()

Member Data Documentation

◆ mElapsedTime

◆ mExpectedImageFile

◆ mMatchTarget

◆ mRenderedImageFile

◆ mReport