# Plugins

Plugins allow you to use the @logigear/gondola internal API to extend its functionality. You can use the internal event dispatcher, container and output plugins as well as create your own.

@logigear/gondola's built-in plugins can be turned on and off in gondola.json. Use them as examples when developing your own plugins.

A plugin is a basic JS module that returns a function. Plugins can have individual configurations that are passed to this function. For example:

const defaultConfig = {
  someDefaultOption: true
}

module.exports = function(config) {
  config = Object.assign(defaultConfig, config);
  // do stuff
}

To enable your custom plugin in gondola.json add it to plugins section. Specify the path to the node module using require.

"plugins": {
  "myPlugin": {
    "require": "./path/to/my/module",
    "enabled": true
  }
}

require - specifies relative path to a plugin file. The Path is relative to the gondola.json file. enabled - to enable this plugin. If a plugin is disabled (enabled is not set or is set to false) this plugin can be enabled from command line:

./node_modules/.bin/gondola run --plugin myPlugin

Several plugins can be enabled at the same time:

./node_modules/.bin/gondola run --plugin myPlugin,allure

Example: Execute code for a specific group of tests If you need to execute a piece of code before a group of tests, you can mark these tests with a common tag. Then listen for tests where this tag is included (see Test Objects).

Let's say we need to populate database for a group of tests.

// populate database for slow tests
import {event} from "@logigear/gondola";
module.exports = function() {
  event.dispatcher.on(event.test.before, (test:any)=> {
    if (test.tags.indexOf('@populate') >= 0) {
      recorder.add('populate database', async () => {
        // populate database for this test
      })
    }
  });
}

# API

We use the local @logigear/gondola installation to get access to the @logigear/gondola module

@logigear/gondola provides an API which can be loaded via require('@logigear/gondola') when @logigear/gondola is installed locally. These internal objects are available:

gondola: test runner class. config: current gondola configuration. event: event listener. output: internal printer. container: dependency injection container for tests, includes the current helpers and support objects.

# Event Listeners

@logigear/gondola provides a module with an event dispatcher and a set of predefined events.

It can be loaded from the @logigear/gondola package if it is locally installed.

import {event} from "@logigear/gondola";
module.exports = function() {
  event.dispatcher.on(event.test.before, (test:any) => {
    console.log('--- I am before the test --');
  });
}

# Available Events

Event Description
event.test.before(test) async before hooks from helpers and a test case are executed
event.test.after(test) async after a test case
event.test.started(test) sync at the very beginning of a test case. Passes the current test object
event.test.passed(test) sync when a test case has passed
event.test.failed(test, error) sync when a test case has failed
event.test.finished(test) sync when a test case has finished
event.suite.before(suite) async before a test suite
event.suite.after(suite) async after a test suite
event.step.before(step) async when a step is scheduled for execution
event.step.after(step) async after a step
event.step.started(step) sync when a step starts
event.step.passed(step) sync when a step has passed
event.step.failed(step, err) sync when a step has failed
event.step.finished(step) sync when a step is finished
event.all.before before all tests will run
event.all.after after all tests have run
event.all.result when results are printed

# Test Objects

Test events provide a test object with following fields:

  • title title of the test
  • body test function as a string
  • opts additional test options like retries and others
  • pending true if test is scheduled for execution and false if a test has finished
  • tags array of tags for this test
  • file path to test file.
  • steps array of executed steps (available only in test.passed, test.failed, test.finished events)

and others

# Step Objects

Step events provide step objects with following fields:

  • name name of a step, like 'see', 'click', and others
  • helper current helper instance used to execute this step
  • helperMethod corresponding helper method, in most cases is the same as name
  • status status of a step (passed or failed)
  • prefix if a step is executed inside a within block contained within text, like: 'Within .js-signup-form'.
  • args passed arguments

# Output

The Output module provides 4 verbosity levels. Depending on the mode you can have different information printed using corresponding functions.

default: prints basic information using output.print steps: toggled by --steps option, prints test steps debug: toggled by --debug option, prints steps and debug information in the file output.debug verbose: toggled by --verbose prints debug information and internal logs in the file output.log It's recommended to avoid using the console.log() function and use following output.* methods for printing.

import {output} from "@logigear/gondola"; 

output.print("This is basic information");
output.debug("This is debug information");
output.log("This is verbose logging information");

# Containers

@logigear/gondola has a dependency injection container with Helpers or Plugins. They can be retrieved from the container:

import {container} from "@logigear/gondola"; 

// get an object containing all helpers
let helpers = container.helpers();

// get a helper using its name
let WebDriver = container.helpers("WebDriver");

// get all registered plugins
let plugins = container.plugins();

Containers also contain the current Mocha instance:

let mocha = container.mocha();

# Configuration

@logigear/gondola's configuration can be accessed from action config.get():

import {config} from "@logigear/gondola"; 

if (config.myKey == "value") {
  // run hook
}
Last Updated: 12/28/2020, 4:12:58 AM