Quilla Plugin Hooks

Configuration hooks

Hooks that are related to configuration, such as logger configs, parser additions, etc.

quilla.hookspecs.configuration.quilla_addopts(parser)

A hook to allow plugins to add additional arguments to the argument parser. This can be used if a plugin requires additional parameters or data in some way.

This is called after the initial argument parser setup

Parameters

parser (ArgumentParser) – The argparse Argument Parser instance used by the application

quilla.hookspecs.configuration.quilla_configure(ctx, args)

A hook to allow plugins to modify the context object, either changing its data or adding data to it.

This is called after the initial setup of the context object

Parameters

• ctx (Context) – The runtime context for the application

• args (Namespace) – Parsed CLI args, in case they are needed

quilla.hookspecs.configuration.quilla_configure_logger(logger)

A hook called immediately after the plugin manager is created. This is the very first hook called, and allows plugins to register additional handlers, formatters, or otherwise modify the logger used throughout Quilla. Note, the Context is not yet created

To help in debugging, it is recommended that plugins register their own StreamHandler to the logger with a filter that shows only the messages relevant to the plugin.

Parameters

logger (Logger) – The configured logger instance for Quilla

quilla.hookspecs.configuration.quilla_prevalidate(validation)

A hook called immediately before the validations attempt to be resolved (i.e. before validations.validate_all() is called)

Parameters

validation (QuillaTest) – The collected validations from the json passed to the application

quilla.hookspecs.configuration.quilla_resolve_enum_from_name(name, enum)

A hook called when a value specified by the quilla test should be resolved to an enum, but no enum has been found. This is to allow plugins to register custom enum values for quilla, such as new step actions, validation types, validation states, output sources, etc.

Parameters

• name (str) – the string value specified in the quilla test

• enum (Type[~T]) – The enum subclass type that is being attempted to be resolved. This should give an indication as to what is being resolved. For example, UITestActions is the enum type being resolved for the ‘actions’ field.

Return type

Optional[~T]

Returns

The resolved enum, if it can be resolved. None if the plugin can’t resolve the value.

Steps hooks

Hooks that allow extension of the behaviour of steps, including output and validation related steps. This also includes any hooks related to context expressions

quilla.hookspecs.steps.quilla_context_obj(ctx, root, path)

A hook to allow pluggins to resolve a context object given its root and a path. All plugins that implement this hook must return None if they cannot resolve the context object.

It is not possible to override the default context object handlers

Parameters

• ctx (Context) – The runtime context for the application

• root (str) – The name of the context object, which is expressed as the root of a dot-separated path in the validation files

• path (Tuple[str]) – The remainder of the context object path, where data is being retrieved from

Returns

the data stored at the context object if existing, None otherwise

Return type

Optional[str]

quilla.hookspecs.steps.quilla_get_baseline_uri(ctx, run_id, baseline_id)

A hook to allow plugins to retrieve some URI for the image associated with the baseline ID.

Parameters

• ctx (Context) – The runtime context of the application

• run_id (str) – The run ID for the current run, in case the plugin tracks baselines for each run

• baseline_id (str) – The unique ID for the baseline image

Return type

Optional[str]

Returns

An identifier that can locate the baseline image

quilla.hookspecs.steps.quilla_get_visualparity_baseline(ctx, baseline_id)

A hook to allow pluggins to find baseline images for the VisualParity validation, called while the VisualParity validation step is being executed.

Plugins should first check if they are able to authenticate or configure with whatever storage mechanism is being used to keep the baseline images, and return None if they cannot both read and write files. It is assumed that only one storage mechanism will be used for baseline/treatment images.

If a plugin can read the files from its storage mechanism, it should search for the image by its baseline ID and return the data in bytes.

Parameters

• ctx (Context) – The runtime context for the application

• baseline_id (str) – The baseline ID to search for

Return type

Optional[bytes]

Returns

The image data in bytes

quilla.hookspecs.steps.quilla_step_factory_selector(selector)

A hook called immediately before resolving the step factory for a given step definition. This is used to register new step factories for custom step objects.

Most custom steps should just add themselves to one of the non-factory selector hooks, but if a custom step requires complex logic it might be beneficial to register a factory to have more fine-grained control over the logic

Parameters

selector (Dict[UITestActions, Type[BaseStepFactory]]) – The factory selector dictionary.

quilla.hookspecs.steps.quilla_store_image(ctx, baseline_id, image_bytes, image_type)

A hook to allow pluggins to store images for the VisualParity validation.

Plugins should first check if they are able to authenticate or configure with whatever storage mechanism is being used to keep the baseline images, and return None if they cannot both read and write files. It is assumed that only one storage mechanism will be used for baseline/treatment images.

If a plugin can write files to its storage mechanism, it should return the URI (i.e. the link, path, etc. that can be used to find the new image) so that it can be included in the report.

Plugins to add storage mechanisms to VisualParity validations should implement this hook as well as the quilla_get_visualparity_baseline hook and some configuration method (i.e. adding CLI options with quilla_addopts or pulling data from the environment)

Parameters

• ctx (Context) – The runtime context for the application

• baseline_id (str) – The image baseline ID associated with the image

• image_bytes (bytes) – The data for the image PNG in bytes form

• image_type (VisualParityImageType) – The kind of image that it is, since different image types might be desired to be stored differently

Returns

An identifier that can locate the new image

Return type

Optional[str]

Report hooks

Hooks related to outputs and reports

quilla.hookspecs.reports.quilla_postvalidate(ctx, reports)

A hook called immediately after all validations are executed and the full ReportSummary is generated

Parameters

• ctx (Context) – The runtime context for the application

• reports (ReportSummary) – An object capturing all generated reports and giving summary data