tl.testing.cairo

Doc-testing the graphical content of cairo surfaces.

Functions

tl.testing.cairo.DocFileSuite(*paths, **options)

Return a TestSuite that runs doc-test files with graphical tests.

Parameters are the same as for tl.testing.doctest.DocFileSuite.

tl.testing.cairo.copy_to_ARGB32(surface)

tl.testing.cairo.normalise_exclude(result, expected, options)

Classes

class tl.testing.cairo.Manuel(Test, Result)

Bases: manuel.Manuel

Manuel test runner that exercises Test and Result implementations.

parse(document)

Create Test instances for matching regions of a document.

evaluate(region, document, globs)

Evaluate the region’s Test, if any, in the context of globs.

format(document)

Format Results obtained for matching regions of a document.

class tl.testing.cairo.Result(test, error)

Bases: object

The result of a test for a cairo Surface’s graphical content.

A test result is characterised by the failure message, which is an empty string if the test passed.

format()

Return a formatted failure message if the test failed.

class tl.testing.cairo.Test(document, region)

Bases: object

A graphical test that compares a cairo surface with an expected image.

A test instance represents a test run on one region of a doc-test file. The region is identified as being a ReST figure with a caption that is a literal expression. The test is characterised by that expression and the path to the referenced image.

The example’s Python expression is evaluated in the context of the test case’s global variables. It is expected to be a cairo Surface. The expected graphical content is loaded from the referenced file, which must be a PNG image.

Failures:

‘Exception raised: <traceback>’

The expression raised an exception when evaluated.

‘Expected a cairo surface, Got: <expression value>’

The expression’s value is not a cairo Surface instance.

‘Image differs from expectation: <path to image>’

The graphical content of the cairo Surface could be computed but does not meet the test’s expectation.

Errors:

‘Could not load expectation: <path to image>’

The referenced image is not a readable PNG file.

If the expression could be evaluated to a cairo Surface and the test failed or raised an error later, the CAIRO_TEST_RESULTS environment variable is consulted. If set, is taken to be the path to an existing directory and the surface’s content is written to a file in that directory. The file name is computed from the path to the expected image.

start = <_sre.SRE_Pattern object at 0x27d03d0>

end = <_sre.SRE_Pattern object at 0x26c7430>

classmethod match(region)

Decide whether a region matching by regex really represents a test.

In order for a region to represent a test, its figure caption must contain exactly one literal expression marked up by double back-ticks.

evaluate(globs)

Compute the cairo surface under test and compare it with the image.

Returns the failure message or None if the test passed.

store_result(result)

Write the surface’s content to a file on failure or error.

Returns a line of output pointing to the file, or ‘’ if no target directory is specified by the environment.