quilla package

Entrypoint code for the Quilla module. Deals with setting up the parser and the runtime context for the application, then executing the rest of the application

quilla.execute(ctx)

Runs all defined UI validations from the json, either from file or from raw json text, and prints all the resulting reports to the console

Parameters

json – The json string describing the validation

Return type

ReportSummary

Returns

A summary of all reports produced by Quilla

quilla.get_early_configs(parser, args)

Extracts known configs early on. This will disable help/usage printing and prevent exiting on failure, since it potentially needs to ignore errors to collect the early configs

Parameters

• parser (ArgumentParser) – A parser instance, such as the one returned by make parser

• args (List[str]) – A list of strings containing the arguments to be consumed

Return type

Namespace

Returns

A namespace object containing the early configurations for Quilla

quilla.main()

Creates the context and parses all arguments, then runs the default handler function

quilla.make_default_logger(early_configs)

Creates a default logger class for Quilla. All internal logger setup logic is done in this function

Parameters

early_configs (Namespace) – The extracted configurations from an early pass-through of the parse_known_intermixed_args function, before plugins run

Return type

Logger

Returns

A configured Logger

quilla.make_parser()

Creates the required parser to run Quilla from the command line

Return type

ArgumentParser

Returns

A pre-configured ArgParser instance

quilla.run(ctx)

Runs all reports and prints to stdout while providing the proper exit code

Parameters

ctx (Context) – The application context

quilla.setup_context(args, plugin_root='.', recreate_context=False)

Starts up the plugin manager, creates parser, parses args and sets up the application context

Parameters

• args (List[str]) – A list of cli options, such as sys.argv[1:]

• plugin_root (str) – The directory used by the plugin manager to search for uiconf.py files

• recreate_context (bool) – Whether the context should be recreated

Return type

Context

Returns

A runtime context configured by the hooks and the args

Submodules

quilla.ctx module

class quilla.ctx.Context(plugin_manager, debug=False, drivers_path='.', pretty=False, json_data='', is_file=False, no_sandbox=False, definitions=[], logger=None, run_id=None, indent=4, args=None, update_all_baselines=False, update_baseline=[], create_baseline_if_none=False)

Bases: quilla.common.utils.DriverHolder

Class defining configurations for the runtime context. This object should not be created directly but retrieved with “get_default_context”

Parameters

• plugin_manager (PluginManager) – A configured PluginManager instance

• debug (bool) – Whether the configurations should be run as debug mode.

• drivers_path (str) – The directory where the different browser drivers are stored

• pretty (bool) – If the output should be pretty-printed

• json_data (str) – The json describing the validations

• is_file (bool) – Whether a file was originally passed in or if the raw json was passed in

• no_sandbox (bool) – Whether to pass the ‘–no-sandbox’ arg to Chrome and Edge

• logger (Optional[Logger]) – An optional configured logger instance.

• run_id (Optional[str]) – A string that uniquely identifies the run of Quilla.

• args (Optional[Namespace]) – The Namespace object that parsed related arguments, if applicable

• update_all_baselines (bool) – Whether the VisualParity baselines should be updated or not

• update_baseline (List[str]) – A list of baseline IDs to update during this run

• create_baseline_if_none (bool) – If true, instructs the storage plugin to create a new baseline image if none can be found for the given baseline ID

pm

A PluginManager instance with all hooks already loaded

suppress_exceptions

Whether to suppress exceptions by generating reports or to crash the application on exception

run_headless

Whether the browsers should be instructed to run headless

close_browser

Whether the cleanup process should close browsers or leave the session open

pretty

If the output should be pretty-printed

json_data

The json describing the validations

is_file

Whether a file was originally passed in or if raw json was passed in

no_sandbox

Whether to pass the ‘–no-sandbox’ arg to Chrome and Edge

logger

A logger instance. If None was passed in for the ‘logger’ argument, will create one with the default logger.

Type

logging.Logger

run_id

A string that uniquely identifies the run of Quilla.

pretty_print_indent

How many spaces to use for indentation when pretty-printing the output

args

The Namespace object that parsed related arguments, if applicable

update_all_baselines

Whether the VisualParity baselines should be updated or not

update_baseline

A list of baseline IDs to update during this run

current_step

The current step

Type

Optional[BaseStep]

create_baseline_if_none

If true, instructs the storage plugin to create a new baseline image if none can be found for the given baseline ID

create_output(output_name, value)

Creates an output on the context object to be returned by the validation module if the browser is the supported output browser, and sets the value in the Validation context object. Setting the value in the Validation context happens regardless of the browser type, since further steps on the validation chain could need this specific value and the order in which browsers are executed is dependent on the order that the user gave in the validation json.

Parameters

• output_name (str) – The name (ID) of this specific output, to be referred to with ${{ Validation.<output_name> }}. This does support chaining of the namespace to create a more dictionary-like structure

• value (str) – The value that the name will be associated with

current_step: Optional[BaseStep] = None

default_context: Optional[Context] = None

property drivers_path: str

The path where the drivers will be stored. Setting this property will add it to the PATH variable, so if the drivers are already in the PATH this can be omitted.

Return type

str

property is_debug: bool

A set of debug configurations. Will return true if ‘debug’ is originally passed or this property is set, but one could edit the individual permissions to make a more fine-tuned debugging experience

Return type

bool

load_definitions(definitions_dict)

Loads the given dictionary into the context data, merging the dictionaries and preferring the newer configurations wherever there is a conflict

Parameters

definitions_dict (dict) – A dictionary containing all the definitions. Definitions are strings saved either in an external file or in the ‘definitions’ object of the validation json that works effectively as a macro, allowing test writers to use declarative names for XPaths

logger: logging.Logger

property outputs: dict

A dictionary of all outputs created by the steps for the current Quilla test

Return type

dict

perform_replacements(text)

Extracts any relevant context expressions from the text and attempts to making suitable replacements for the context objects

Parameters

text (str) – Any string that supports context expressions

Return type

str

Returns

The resulting string after executing the context expression

Examples

>>> from quilla.ctx import Context
>>> ctx = Context(context_data={'name': 'examplesvc'})
>>> ctx.perform_replacements('/api/${{ Validation.name }}/get')
'/api/examplesvc/get'

run()

Runs Quilla, assuming a proper Namespace object with a handler has been passed in.

This function is not guaranteed to do anything, and is just a passthrough to allow the proper parser handlers to execute, as described in the documentation for ArgParse https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers

quilla.ctx.get_default_context(plugin_manager, debug=False, drivers_path='.', pretty=False, json='', is_file=False, no_sandbox=False, definitions=[], recreate_context=False, logger=None, run_id=None, indent=4, args=None, update_all_baselines=False, update_baseline=[], create_baseline_if_none=False)

Gets the default context, creating a new one if necessary.

If a context object already exists, all of the arguments passed into this function are ignored.

Parameters

• plugin_manager (PluginManager) – An instance of the plugin manager class to attach to the context

• debug (bool) – Whether debug configurations should be enabled

• drivers_path (str) – The directory holding all the required drivers

• pretty (bool) – Whether the output json should be pretty-printed

• json (str) – The json data describing the validations

• is_file (bool) – Whether the json data was passed in originally raw or as a string

• no_sandbox (bool) – Specifies that Chrome and Edge should start with the –no-sandbox flag

• definitions (List[str]) – A list file names that contain definitions for Quilla

• recreate_context (bool) – Whether a new context object should be created or not

• logger (Optional[Logger]) – An optional logger instance. If None, one will be created with the NullHandler.

• run_id (Optional[str]) – A string that uniquely identifies the run of Quilla.

• update_all_baselines (bool) – Whether the VisualParity baselines should be updated or not

• create_baseline_if_none (bool) – If true, instructs the storage plugin to create a new baseline image if none can be found for the given baseline ID

Returns

Application context shared for the entire application

Return type

Context

quilla.ui_validation module

class quilla.ui_validation.QuillaTest(ctx, browsers, root, setup_steps)

Bases: quilla.common.utils.EnumResolver

A class to convert data into a valid QuillaTest instance, which is able to resolve raw text data into the appropriate enums to be used by the internal classes.

Creates shallow copies of all the steps to ensure independence

Parameters

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

• browsers (List[BrowserTargets]) – A list of browsers to run the validations against

• root (str) – The starting path of the validations

• setup_steps (list) – a list of steps used to create the validation report

browsers

A list of instantiated browser validations, each containing an independent steps aggregator

ctx

The runtime context for the application

classmethod from_dict(ctx, validation_parameters)

Converts a dictionary that represents a single UIValidation test case into the appropriate validation object.

Note

The browsers are effectively a cartesian product with the steps & validations

Return type

QuillaTest

classmethod from_file(ctx, fp)

Converts an fp (a .read() supporting file-like object) containing a json document into a UIValidation object

Return type

QuillaTest

classmethod from_filename(ctx, path)

Reads a file at the specified path and attempts to convert it into a UIValidation object

Return type

QuillaTest

classmethod from_json(ctx, validation_json)

Converts a json string into a UIValidation object

Return type

QuillaTest

validate_all()

Performs all the setup test steps required for each test case and executes the validations, producing a set of validation reports.

Return type

ReportSummary

validation_type_selector: Dict[quilla.common.enums.ValidationTypes, Type[quilla.common.enums.ValidationStates]] = {<ValidationTypes.XPATH: 'XPath'>: <enum 'XPathValidationStates'>, <ValidationTypes.URL: 'URL'>: <enum 'URLValidationStates'>}

quilla.plugins module

quilla.plugins.get_plugin_manager(path, logger)

Creates and configures a plugin manager by loading all the plugins defined through entrypoints or through a uiconf.py file found at the path location

Parameters

path (str) – the directory in which the uiconf.py will be found

Return type

PluginManager

Returns

a configured PluginManager instance with all plugins already loaded

Subpackages

• quilla.browser package
  • Submodules
  • quilla.browser.browser_validations module
  • quilla.browser.drivers module
• quilla.common package
  • Submodules
  • quilla.common.enums module
  • quilla.common.exceptions module
  • quilla.common.utils module
• quilla.reports package
  • Submodules
  • quilla.reports.base_report module
  • quilla.reports.report_summary module
  • quilla.reports.step_failure_report module
  • quilla.reports.validation_report module
  • quilla.reports.visual_parity_report module
• quilla.steps package
  • Submodules
  • quilla.steps.base_steps module
  • quilla.steps.steps module
    • Adding new actions
  • Subpackages
    • quilla.steps.validations package
      • Submodules
      • quilla.steps.validations.url module
      • quilla.steps.validations.validation_factory module
      • quilla.steps.validations.xpath module
      • Module contents
• quilla.hookspecs package
  • Submodules
  • quilla.hookspecs.configuration module
  • quilla.hookspecs.steps module
  • quilla.hookspecs.reports module