inkex.tester package


Module contents

All Inkscape extensions should come with tests. This package provides you with the tools needed to create tests and thus ensure that your extension continues to work with future versions of Inkscape, the “inkex” python modules, and other python and non-python tools you may use.

Make sure your extension is a python extension and is using the inkex.generic base classes. These provide the greatest amount of functionality for testing.

You should start by creating a folder in your repository called tests with an empty file inside called to turn it into a module folder.

For each of your extensions, you should create a file called test_{extension_name}.py where the name reflects the name of your extension.

There are two types of tests:

  1. Full-process Comparison tests - These are tests which invoke your

    extension with various arguments and attempt to compare the output to a known good reference. These are useful for testing that your extension would work if it was used in Inkscape.

    Good example of writing comparison tests can be found in the Inkscape core repository, each test which inherits from the ComparisonMixin class is running comparison tests.

  2. Unit tests - These are individual test functions which call out to

    specific functions within your extension. These are typical python unit tests and many good python documents exist to describe how to write them well. For examples here you can find the tests that test the inkex modules themselves to be the most instructive.

When running a test, it will cause a certain fraction of the code within the extension to execute. This fraction called it’s coverage and a higher coverage score indicates that your test is better at exercising the various options, features, and branches within your code.

Generating comparison output can be done using the EXPORT_COMPARE environment variable when calling pytest and comes in 3 modes, the first of which is the CHECK comparisons mode:

EXPORT_COMPARE=1 pytest tests/

This will create files in tests/data/refs/*.{ext} and these files should be manually checked to make sure they are correct. Once you are happy with the output you can re-run the test with the WRITE comparisons mode:

EXPORT_COMPARE=2 pytest tests/

Which will create an output file of the right name and then run the test suite against it. But only if the file doesn’t already exist. The final mode is the OVERWRITE comparisons mode:

EXPORT_COMPARE=3 pytest tests/

This is like mode 2, but will over-write any existing files too. This allows you to update the test compare files.

class inkex.tester.ComparisonMixin[source]

Bases: object

Add comparison tests to any existing test suite.

_apply_compare_filters(data, is_saving=None)[source]
_base_compare(data_a, data_b, compare_mode)[source]
property _compare_file_extension

The default extension to use when outputting check files in COMPARE_CHECK mode.

_test_comparisons(compare_file, addout=None)[source]
assertCompare(infile, cmpfile, args, outfile=None)[source]

Compare the output of a previous run against this one.

  • infile: The filename of the pre-processed svg (or other type of file)

  • cmpfile: The filename of the data we expect to get, if not set

    the filename will be generated from the effect name and kwargs.

  • args: All the arguments to be passed to the effect run

  • outfile: Optional, instead of returning a regular output, this extension

    dumps it’s output to this filename instead.

compare_file: Union[List[str], Tuple[str], str] = 'svg/shapes.svg'
compare_file_extension = 'svg'
compare_filter_save = False
compare_filters: List[Compare] = []
comparisons = [(), ('--id=p1', '--id=r3')]
get_compare_cmpfile(args, addout=None)[source]

Generate an output file for the arguments given


Testing all comparisons

class inkex.tester.InkscapeExtensionTestMixin[source]

Bases: object

Automatically setup self.effect for each test and test with an empty svg


Check if there is an effect_class set and create self.effect if it is


Extension works with empty svg file

class inkex.tester.NoExtension(*args, **kwargs)[source]

Bases: inkex.base.InkscapeExtension

Test case must specify ‘self.effect_class’ to assertEffect.

document: Union[None, bytes, str, etree]
file_io: Optional[IO]
run(args=None, output=None)[source]

Fake run

class inkex.tester.TestCase(*args, **kw)[source]

Bases: inkex.tester.mock.MockCommandMixin,

Base class for all effects tests, provides access to data_files and test_without_parameters

classmethod _testdir()[source]

Get’s the folder where the test exists (so data can be found)

assertAlmostTuple(found, expected, precision=8)[source]

Floating point results may vary with computer architecture; use assertAlmostEqual to allow a tolerance in the result.

assertDeepAlmostEqual(first, second, places=None, msg=None, delta=None)[source]
assertEffect(*filename, **kwargs)[source]

Assert an effect, capturing the output to stdout.

filename should point to a starting svg document, default is empty_svg

assertEffectEmpty(effect, **kwargs)[source]

Assert calling effect without any arguments

assertTransformEqual(lhs, rhs, places=7)[source]

Assert that two transform expressions evaluate to the same transformation matrix.

classmethod data_file(filename, *parts, check_exists=True)[source]

Provide a data file from a filename, can accept directories as arguments.

classmethod datadir()[source]

Get the data directory (can be over-ridden if needed)

property effect

Generate an effect object


alias of inkex.tester.NoExtension

property effect_name
property empty_svg

Returns a common minimal svg file

classmethod rootdir()[source]

Return the full path to the extensions directory


Make sure every test is seeded the same way

stderr_output = False
stderr_protect = True
stdout_protect = True

For each returned stored, tear it down and restore mock instruction

temp_file(prefix='file-', template='{prefix}{name}{suffix}', suffix='.tmp')[source]

Generate the filename of a temporary file

property tempdir

Generate a temporary location to store files