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 Types
enum	Flag : int { Flag::AvoidExportingRenderedImage = 1 << 0 }
	Render checker flags. More...

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

bool	compareImages (const QString &testName, const QString &referenceImageFile, const QString &renderedImageFile, unsigned int mismatchCount=0, QgsRenderChecker::Flags flags=QgsRenderChecker::Flags())
	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(), QgsRenderChecker::Flags flags=QgsRenderChecker::Flags())
	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 () const
	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 (bool ignoreSuccess=true) const
	Returns the HTML report describing the results of the test run. More...

bool	runTest (const QString &testName, unsigned int mismatchCount=0, QgsRenderChecker::Flags flags=QgsRenderChecker::Flags())
	Render checker flags. 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	setExpectFail (bool expectFail)
	Sets whether the comparison is expected to fail. More...

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

static bool	shouldGenerateReport ()
	Returns `true` if a test report should be generated given the current environment. More...

static QDir	testReportDir ()
	Returns the directory to use for generating a test report. 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 41 of file qgsrenderchecker.h.

Member Enumeration Documentation

◆ Flag

enum QgsRenderChecker::Flag : int

strong

Render checker flags.

Since: QGIS 3.28

Enumerator
AvoidExportingRenderedImage	Avoids exporting rendered images to reports.

Definition at line 189 of file qgsrenderchecker.h.

Constructor & Destructor Documentation

◆ QgsRenderChecker()

QgsRenderChecker::QgsRenderChecker ( )

Constructor for QgsRenderChecker.

Definition at line 30 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`,
		QgsRenderChecker::Flags	flags = `QgsRenderChecker::Flags()`
	)

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

Since: QGIS 3.18

Definition at line 346 of file qgsrenderchecker.cpp.

◆ compareImages() [2/2]

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

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
flags	render checker flags

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

Definition at line 326 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 50 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 275 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 97 of file qgsrenderchecker.cpp.

◆ elapsedTime()

int QgsRenderChecker::elapsedTime ( ) const

inline

Returns the total elapsed time for the rendering test.

Note: this only records time for actual render part.

Definition at line 116 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 267 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 258 of file qgsrenderchecker.h.

◆ imageToHash()

QString QgsRenderChecker::imageToHash ( const QString & imageFile )

Gets an md5 hash that uniquely identifies an image.

Definition at line 79 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 118 of file qgsrenderchecker.cpp.

◆ matchPercent()

float QgsRenderChecker::matchPercent ( ) const

inline

Returns the percent of pixels which matched the control image.

Definition at line 95 of file qgsrenderchecker.h.

◆ matchTarget()

unsigned int QgsRenderChecker::matchTarget ( ) const

inline

Returns the total number of pixels in the control image.

Definition at line 109 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 104 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 162 of file qgsrenderchecker.h.

◆ report()

QString QgsRenderChecker::report ( bool ignoreSuccess = true ) const

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

If ignoreSuccess is true then the report will always be empty if the test was successful.

Definition at line 60 of file qgsrenderchecker.cpp.

◆ runTest()

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

Render checker flags.

Since: QGIS 3.28 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.
flags	render checker flags

Note: make sure to call setExpectedImage and setMapRenderer first

Definition at line 239 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 174 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 132 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 55 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 65 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 138 of file qgsrenderchecker.h.

◆ setControlPathSuffix()

void QgsRenderChecker::setControlPathSuffix ( const QString & name )

Definition at line 71 of file qgsrenderchecker.cpp.

◆ setElapsedTimeTarget()

void QgsRenderChecker::setElapsedTimeTarget ( int target )

inline

Definition at line 117 of file qgsrenderchecker.h.

◆ setExpectFail()

void QgsRenderChecker::setExpectFail ( bool expectFail )

inline

Sets whether the comparison is expected to fail.

Since: QGIS 3.28

Definition at line 155 of file qgsrenderchecker.h.

◆ setMapSettings()

void QgsRenderChecker::setMapSettings ( const QgsMapSettings & mapSettings )

Since: QGIS 2.4

Definition at line 92 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 148 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 182 of file qgsrenderchecker.h.

◆ shouldGenerateReport()

bool QgsRenderChecker::shouldGenerateReport ( )

static

Returns true if a test report should be generated given the current environment.

Since: QGIS 3.28

Definition at line 45 of file qgsrenderchecker.cpp.

◆ testReportDir()

QDir QgsRenderChecker::testReportDir ( )

static

Returns the directory to use for generating a test report.

Since: QGIS 3.28

Definition at line 37 of file qgsrenderchecker.cpp.

Member Data Documentation

◆ mElapsedTime

int QgsRenderChecker::mElapsedTime = 0

protected

Definition at line 280 of file qgsrenderchecker.h.

◆ mExpectedImageFile

QString QgsRenderChecker::mExpectedImageFile

protected

Definition at line 282 of file qgsrenderchecker.h.

◆ mMatchTarget

unsigned int QgsRenderChecker::mMatchTarget = 0

protected

Definition at line 279 of file qgsrenderchecker.h.

◆ mRenderedImageFile

QString QgsRenderChecker::mRenderedImageFile

protected

Definition at line 281 of file qgsrenderchecker.h.

◆ mReport

QString QgsRenderChecker::mReport

protected

Definition at line 278 of file qgsrenderchecker.h.

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

/build/qgis-3.26.3+32focal/src/core/qgsrenderchecker.h
/build/qgis-3.26.3+32focal/src/core/qgsrenderchecker.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Flag

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()

◆ setExpectFail()

◆ setMapSettings()

◆ setRenderedImage()

◆ setSizeTolerance()

◆ shouldGenerateReport()

◆ testReportDir()

Member Data Documentation

◆ mElapsedTime

◆ mExpectedImageFile

◆ mMatchTarget

◆ mRenderedImageFile

◆ mReport