Class: QgsRenderChecker¶

Helper class for unit tests that need to write an image and compare it to an expected result or render time.

Enums

Flag

Render checker flags.

Methods

`compareImages`	Test using two arbitrary images (map renderer will not be used)
`controlImagePath`	Returns the base path containing the reference images.
`dartMeasurements`	Gets access to buffered dash messages.
`elapsedTime`	Returns the total elapsed time for the rendering test.
`enableDashBuffering`	Call this to enable internal buffering of dash messages.
`expectedImageFile`	Returns the path to the expected image file
`imageToHash`	Gets an md5 hash that uniquely identifies an image
`isKnownAnomaly`	Gets a list of all the anomalies.
`markdownReport`	Returns the markdown report describing the results of the test run.
`matchPercent`	Returns the percent of pixels which matched the control image.
`matchTarget`	Returns the total number of pixels in the control image.
`mismatchCount`	Returns the number of pixels which did not match the control image.
`renderedImage`	Returns the path of the rendered image generated by the test.
`report`	Returns the HTML report describing the results of the test run.
`runTest`	Test using renderer to generate the image to be compared.
`setColorTolerance`	Set tolerance for color components used by `runTest()` and `compareImages()`.
`setControlExtension`	Sets file extension for the control image.
`setControlImagePath`	Sets the base path containing the reference images.
`setControlName`	Sets the base directory name for the control image (with control image path suffixed).
`setControlPathPrefix`	Sets the path prefix where the control images are kept.
`setControlPathSuffix`
`setElapsedTimeTarget`
`setExpectFail`	Sets whether the comparison is expected to fail.
`setMapSettings`
`setRenderedImage`	Sets the file name of the rendered image generated by the test.
`setSizeTolerance`	Sets the largest allowable difference in size between the rendered and the expected image.

Static Methods

`drawBackground`	Draws a checkboard pattern for image backgrounds, so that opacity is visible without requiring a transparent background for the image
`shouldGenerateReport`	Returns `True` if a test report should be generated given the current environment.
`sourcePath`	Returns the path to the QGIS source code.
`testReportDir`	Returns the directory to use for generating a test report.

class qgis.core.QgsRenderChecker[source]¶

Bases: object

__init__(): Constructor for QgsRenderChecker.

__init__(a0: QgsRenderChecker)

Parameters:: a0 (QgsRenderChecker)

class Flag(*values)¶

Bases: IntEnum

Render checker flags.

Added in version 3.28.

AvoidExportingRenderedImage: Avoids exporting rendered images to reports
Silent: Don’t output non-critical messages to console

Added in version 3.40.

AvoidExportingRenderedImage = 1¶

Silent = 2¶

class Flags¶
class Flags(f: QgsRenderChecker.Flags | QgsRenderChecker.Flag)
class Flags(a0: QgsRenderChecker.Flags): Bases: object

compareImages(self, testName: str | None, mismatchCount: int = 0, renderedImageFile: str | None = '', flags: QgsRenderChecker.Flags | QgsRenderChecker.Flag = QgsRenderChecker.Flags()) → bool[source]¶

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

Parameters:

testName (Optional[str]) – to be used as the basis for writing a file to e.g. /tmp/theTestName.png
mismatchCount (int = 0) – 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 (Optional[str] = '') – to optionally override the output filename
flags (Union[QgsRenderChecker.Flags, QgsRenderChecker.Flag] = QgsRenderChecker.Flags()) – render checker flags

Note

Make sure to call setExpectedImage and setRenderedImage first.

Return type:: bool

compareImages(self, testName: str | None, referenceImageFile: str | None, renderedImageFile: str | None, mismatchCount: int = 0, flags: QgsRenderChecker.Flags | QgsRenderChecker.Flag = QgsRenderChecker.Flags()) → bool[source]

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

Added in version 3.18.

Parameters:

testName (Optional[str])
referenceImageFile (Optional[str])
renderedImageFile (Optional[str])
mismatchCount (int = 0)
flags (Union[QgsRenderChecker.Flags, QgsRenderChecker.Flag] = QgsRenderChecker.Flags())

Return type:

bool

controlImagePath(self) → str[source]¶

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

Return type:: str

dartMeasurements(self) → List[QgsDartMeasurement]¶

Gets access to buffered dash messages. Only will return something if you call enableDashBuffering( True ); before.

Return type:: List[QgsDartMeasurement]
Returns:: buffered dash messages

static drawBackground(image: QImage | None)[source]¶

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

Parameters:: image (Optional[QImage])

elapsedTime(self) → int[source]¶

Returns the total elapsed time for the rendering test.

Note

This only records time for actual render part.

Return type:: int

enableDashBuffering(self, enable: bool)[source]¶

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 (bool) – Enable or disable buffering

expectedImageFile(self) → str[source]¶

Returns the path to the expected image file

Return type:: str
Returns:: Path to the expected image file

imageToHash(self, imageFile: str | None) → str[source]¶

Gets an md5 hash that uniquely identifies an image

Parameters:: imageFile (Optional[str])
Return type:: str

isKnownAnomaly(self, diffImageFile: str | None) → bool[source]¶

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.

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

Deprecated since version 3.40: Use the test mask system instead.

Parameters:: diffImageFile (Optional[str])

markdownReport(self, ignoreSuccess: bool = True) → str[source]¶

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

Added in version 3.34.

Parameters:: ignoreSuccess (bool = True)
Return type:: str

matchPercent(self) → float[source]¶

Returns the percent of pixels which matched the control image.

Return type:: float

matchTarget(self) → int¶

Returns the total number of pixels in the control image.

Return type:: int

mismatchCount(self) → int¶

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

Return type:: int

renderedImage(self) → str[source]¶

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

Return type:: str

report(self, ignoreSuccess: bool = True) → str[source]¶

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

Parameters:: ignoreSuccess (bool = True)
Return type:: str

runTest(self, testName: str | None, mismatchCount: int = 0, flags: QgsRenderChecker.Flags | QgsRenderChecker.Flag = QgsRenderChecker.Flags()) → bool[source]¶

Test using renderer to generate the image to be compared.

Parameters:

testName (Optional[str]) – to be used as the basis for writing a file to e.g. /tmp/theTestName.png
mismatchCount (int = 0) – 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 (Union[QgsRenderChecker.Flags, QgsRenderChecker.Flag] = QgsRenderChecker.Flags()) – render checker flags

Note

Make sure to call setExpectedImage and setMapRenderer first

Return type:: bool

setColorTolerance(self, colorTolerance: int)[source]¶

Set tolerance for color components used by runTest() and compareImages(). Default value is 0.

Parameters:: colorTolerance (int) – is maximum difference for each color component including alpha to be considered correct.

setControlExtension(self, extension: str | None)[source]¶

Sets file extension for the control image. By default it is “png”

Added in version 3.20.

Parameters:: extension (Optional[str])

setControlImagePath(self, path: str | None)[source]¶

Sets the base path containing the reference images.

See also

controlImagePath()

Added in version 3.18.

Parameters:: path (Optional[str])

setControlName(self, name: str | None)[source]¶

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)

Parameters:: name (Optional[str])

setControlPathPrefix(self, name: str | None)[source]¶

Sets the path prefix where the control images are kept. This will be appended to controlImagePath().

Parameters:: name (Optional[str])

setControlPathSuffix(self, name: str | None)[source]¶

Parameters:: name (Optional[str])

setElapsedTimeTarget(self, target: int)[source]¶

Parameters:: target (int)

setExpectFail(self, expectFail: bool)[source]¶

Sets whether the comparison is expected to fail.

Added in version 3.28.

Parameters:: expectFail (bool)

setMapSettings(self, mapSettings: QgsMapSettings)[source]¶

Parameters:: mapSettings (QgsMapSettings)

setRenderedImage(self, imageFileName: str | None)[source]¶

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

Parameters:: imageFileName (Optional[str])

setSizeTolerance(self, xTolerance: int, yTolerance: int)[source]¶

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

Parameters:

xTolerance (int) – x tolerance in pixels
yTolerance (int) – y tolerance in pixels

static shouldGenerateReport() → bool[source]¶

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

Added in version 3.28.

Return type:: bool

static sourcePath() → str[source]¶

Returns the path to the QGIS source code.

Added in version 3.36.

Return type:: str

static testReportDir() → QDir[source]¶

Returns the directory to use for generating a test report.

Added in version 3.28.

Return type:: QDir