19. Develop custom Script Generator Plugin

Introduction to Script Generator Plugin

In qTest Sessions, to generate automated script from a recorded session, you must select a script generator, also known as a plugin.

At the time of this writing, there are three built-in plugins provided by qTest, namely:

  • Java Selenium: plugin to generate automated script in Java language that can be executed against Selenium framework
  • C# Selenium: plugin to generate automated script in C# language that can be executed against Selenium framework
  • Protractor: plugin to generate automated script in JavaScript language that can be executed against Protractor framework

In qTest Sessions, you can manage script generator plugins from Settings page. You can also develop your custom plugins and submit them through Script Generator Plugin section of Settings page.

Develop your custom Script Generator Plugin

In case the built-in plugins does not meet your need and you want to develop your own plugin, e.g. one to generate automation script in a programming language other than C# or Java or Javascript, this instruction is for you.

Plugin development must expose an instance of script generator to session editor. Script generator is a JavaScript object that implements a function named generateScripts. The plugin must also expose a mechanism for session editor to load and obtain the script generator instance by adding a function, namely getAutomationScriptGenerator, to browser's window object which, when being called by session editor, will return the script generator instance.

We think it would be better to describe how the script generator plugin work with a simple workflow:

  1. User selects a plugin, via its name from script generator dialog in session editor
  2. Script generator loads the plugin, which is a JavaScript file associated with the selected plugin, from qTest system
  3. Script generator invokes the function window.getAutomationScriptGenerator() to obtain the instance of script generator
  4. Script generator obtains the supportedProperties field of the plugin. The values of this field are used to filter out the captured attributes of the UI element. In the resulting generated script, these attributes are used to build the element locators.
  5. Script generator calls the function generateScripts() on script generator instance to generate automated script
  6. Script generator populates the resulting script to the script generator dialog

In addition, session editor also allows the user to download the generated script and save it as a text file, we find it would be more convenient for the user to specify the default file extension in the script generator plugin so that when user chooses to download the script, the file extension will be selected by default. 

Below is a screenshot showing the concept of plugin development.

One thing to note is that the implementation concept does not return an instance of SampleScriptGeneratorPlugin but a JavaScript literal object that contains a function named generateScripts, a field name generatedFileExtension whose value is "java" (or probably "cs", "py", "js" depends on the practical implementation) and a supportedProperties field. There is another way to return the script generator instance, as shown in below screenshot:

Bottom line is, choosing the way to return the script generator instance is just a matter of preference.

The generateScripts function

The signature of generateScripts function is described as below:

Below are descriptions of generateScripts function parameters.

session parameter

Description: this parameter represents the JavaScript object containing the session data used to generate automated script

Field Name Type Description
appInfo AppInfo Instance of AppInfo object
sysInfo SysInfo Instance of SysInfo object
actions Action[] Array of action objects

AppInfo

Description: this object contains the information of the recorded application

Field Name Type Description
name string Name of the recorded (browser) application, e.g. “chrome”, “firefox”, safari”
version string  Version of the recorded (browser) application

SysInfo

Description: this JavaScript object contains the system information

Field Name Type Description
os string Name of the Operating System where the session was recorded, e.g. Mac, Windows

Action

Description: this JavaScript object represents for an action taken by the user

Field Name Type Description
description string

Action description.

Examples:

  • Type 'q' in edit box 'Selenium'
  • Click on 'btnG' button
type string

Type of action. Possible values:

  • click: user clicked on an element
  • key: user typed in an input element
  • alert: user took action on alert dialog
  • confirm: user took action on confirm dialog
  • prompt: iuser took action on prompt dialog
selectedPropertyName string

Name of the selected property used to generate selector script. Possible value is either: “ID”, “Name”, “xPath”, etc.

selectedPropertyValue string

Value of the selected property of a selected action on Script generator dialog. For the example of automating Google search, the value is either:

  • ”q” if the selected property is Name
  • “lst-ib” if the selected property is ID
  • “id(lst-ib)” if the selected property is xPath
timestamp string

Timestamp of the action

actionMetadata ActionMetadata

Instance of ActionMetadata object

ActionMetadata

Description: this object carries additional metadata of the action, e.g. the metadata of UI elements that user took action on, or the data representing for the action taken on popup dialogs (alert, confirm, prompt)

Field Name Type Description
id string

Value of id property of web element, empty if not specified

name string

Value of name property of web element, empty if not specified

className string

Value of class property of web element, empty of not specified

tagName string

Tag name of the web element

timestamp string

Timestamp of the action

xpath string

xPath of the web element

controlType string

Type of control, e.g. “button”, “textbox”, “checkbox”, “radio”, etc.

value string 

Value of web element at the time the action was taken.

frames Array of anonymous (literal) javascript objects

List of (nested) frames where the web element is located in the web page

This field is used to determine whether the automated script should switch to correct frame before taking action on the web element.

value

Identity of frame or index of frame.

The meaning of this value depends on "type" property

type
  • "index": the value is index of frame, should cast to integer before using. The value is used to switch frame by index
  • "id" or "name": the value is name or value of frame. The value is use to switch frame by name or id

Example value: [ { value: "0", type: "index"}] 

popupData Anonymous JavaScript object

This field is a literal object containing data for action taken on alert, confirm or prompt dialog. Below is the object definition:

{

    message: "",

    response: {

        action: "",

        value: "",

    }

}

Examples:

1. User click "OK" on an alert box. This field contains value as below:

{

    message: “Are you sure you want to delete this?”,

    response: { 

     action: “ok”, 

     value: “”

    }

}

2. User entered some value on a prompt dialog, then clicked “OK”, this field will contain values as below:

{

   message: “Enter your name?”,

   response: { 

     action: “ok”, 

     value: “Harry Potter”

  }

}

3. User click ‘OK’ on a confirm dialog, this field will contain value as below:

{

   message: “Are you sure?”,

   response: { 

     action: “ok”, 

     value: “”

  }

}

 details Anonymous JavaScript object 

This object represent for the detail information of the action. It might contain:

  • The control key information, e.g. whether user pressed CTRL or ALT or SHIFT when clicking on an element?
  • The control key information when user typed to an element, e.g. whether they held CTRL or ALT or SHIFT when typing?

options parameter

Description: this parameter represents a JavaScript literal object containing the additional data the user entered in Script generator dialog, e.g. web driver path as below example:

{

    webDriverPath: "D:\webdriver\chromedriver.exe"

}

doneCallback parameter

Description: a callback function which should be called when the generatedScripts function completes its execution. When invoking this function, plugin developer must pass a literal JavaScript object which contains fields and values as below:

Field Name Type Description
success boolean Possible values: true or false to indicate whether the generateScripts function has executed successfully
script string The resulting generated script
error string Optional field containing the detailed error

Script generator dialog, when calling the generateScripts function from the plugin, it will inspect the object returned from the doneCallback function. If the value of success field is true, Script generator will obtain the generated script in script field. In case the value of success field is false, it will try to get the value from error field, if specified. The value of script or error field will be displayed in the UI where user expect to see the resulting generated script.

Sample plugin implementation and customization

At any time, you can view the source code of the built-in plugins developed by QASymphony by accessing to Script Generator Plugin in Settings page.

From View Plugin dialog, you can view the implementation of each plugin, or customize a plugin by downloading it to local machine, adding changes, then uploading it via Script Generator Plugin section as a new plugin.