QGIS API Documentation 3.37.0-Master (fdefdf9c27f)
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | Friends | List of all members
QgsRenderChecker Class Reference

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 class  Flag : int { AvoidExportingRenderedImage = 1 << 0 }
 Render checker flags. More...
 
typedef QFlags< FlagFlags
 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< QgsDartMeasurementdartMeasurements () 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...
 
Q_DECL_DEPRECATED bool isKnownAnomaly (const QString &diffImageFile)
 Gets a list of all the anomalies. More...
 
QString markdownReport (bool ignoreSuccess=true) const
 Returns the markdown report describing the results of the test run. 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())
 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 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 QString sourcePath ()
 Returns the path to the QGIS source code. More...
 
static QDir testReportDir ()
 Returns the directory to use for generating a test report. More...
 

Protected Attributes

int mElapsedTime = 0
 
QString mExpectedImageFile
 
QString mMarkdownReport
 Markdown report. More...
 
unsigned int mMatchTarget = 0
 
QString mRenderedImageFile
 
QString mReport
 HTML format report. More...
 

Friends

class QgsMultiRenderChecker
 

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 Typedef Documentation

◆ Flags

typedef QFlags< Flag > QgsRenderChecker::Flags

Render checker flags.

Since
QGIS 3.28

Definition at line 210 of file qgsrenderchecker.h.

Member Enumeration Documentation

◆ Flag

enum class QgsRenderChecker::Flag : int
strong

Render checker flags.

Since
QGIS 3.28
Enumerator
AvoidExportingRenderedImage 

Avoids exporting rendered images to reports.

Definition at line 199 of file qgsrenderchecker.h.

Constructor & Destructor Documentation

◆ QgsRenderChecker()

QgsRenderChecker::QgsRenderChecker ( )

Constructor for QgsRenderChecker.

Definition at line 47 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 379 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.
renderedImageFileto optionally override the output filename
flagsrender checker flags
Note
: make sure to call setExpectedImage and setRenderedImage first.

Definition at line 357 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 67 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 287 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 119 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 129 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
enableEnable or disable buffering

Definition at line 279 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 270 of file qgsrenderchecker.h.

◆ imageToHash()

QString QgsRenderChecker::imageToHash ( const QString &  imageFile)

Gets an md5 hash that uniquely identifies an image.

Definition at line 101 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
Deprecated:
Use the test mask system instead.

Definition at line 141 of file qgsrenderchecker.cpp.

◆ markdownReport()

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

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

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

See also
report()
Since
QGIS 3.34

Definition at line 82 of file qgsrenderchecker.cpp.

◆ matchPercent()

float QgsRenderChecker::matchPercent ( ) const
inline

Returns the percent of pixels which matched the control image.

Definition at line 108 of file qgsrenderchecker.h.

◆ matchTarget()

unsigned int QgsRenderChecker::matchTarget ( ) const
inline

Returns the total number of pixels in the control image.

Definition at line 122 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 117 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 175 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.

See also
markdownReport()

Definition at line 77 of file qgsrenderchecker.cpp.

◆ runTest()

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

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.
flagsrender checker flags
Note
make sure to call setExpectedImage and setMapRenderer first

Definition at line 266 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
colorToleranceis maximum difference for each color component including alpha to be considered correct.

Definition at line 185 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 145 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 72 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 87 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 151 of file qgsrenderchecker.h.

◆ setControlPathSuffix()

void QgsRenderChecker::setControlPathSuffix ( const QString &  name)

Definition at line 93 of file qgsrenderchecker.cpp.

◆ setElapsedTimeTarget()

void QgsRenderChecker::setElapsedTimeTarget ( int  target)
inline

Definition at line 130 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 168 of file qgsrenderchecker.h.

◆ setMapSettings()

void QgsRenderChecker::setMapSettings ( const QgsMapSettings mapSettings)

Definition at line 114 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 161 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
xTolerancex tolerance in pixels
yTolerancey tolerance in pixels

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

◆ sourcePath()

QString QgsRenderChecker::sourcePath ( )
static

Returns the path to the QGIS source code.

Since
QGIS 3.36

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

Friends And Related Function Documentation

◆ QgsMultiRenderChecker

friend class QgsMultiRenderChecker
friend

Definition at line 336 of file qgsrenderchecker.h.

Member Data Documentation

◆ mElapsedTime

int QgsRenderChecker::mElapsedTime = 0
protected

Definition at line 302 of file qgsrenderchecker.h.

◆ mExpectedImageFile

QString QgsRenderChecker::mExpectedImageFile
protected

Definition at line 304 of file qgsrenderchecker.h.

◆ mMarkdownReport

QString QgsRenderChecker::mMarkdownReport
protected

Markdown report.

Definition at line 300 of file qgsrenderchecker.h.

◆ mMatchTarget

unsigned int QgsRenderChecker::mMatchTarget = 0
protected

Definition at line 301 of file qgsrenderchecker.h.

◆ mRenderedImageFile

QString QgsRenderChecker::mRenderedImageFile
protected

Definition at line 303 of file qgsrenderchecker.h.

◆ mReport

QString QgsRenderChecker::mReport
protected

HTML format report.

Definition at line 298 of file qgsrenderchecker.h.


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