Building a User Extension in ACCELQ

User extensions in ACCELQ enable end-users to create customized commands to suit their specific testing needs, including utilizing third-party libraries, implementing custom logic, and much more. While ACCELQ's out-of-the-box functionality covers most enterprise requirements, user extensions prove invaluable for addressing highly specific requirements. This detailed guide explores how to create and integrate user-defined extensions, leveraging ACCELQ's environment for more tailored and powerful testing solutions.

Understanding the Basics

A User extension in ACCELQ is primarily a Java file with ACCELQ annotations. Key annotations like @UserLibrary, @Command, and @Parameter are instrumental in this integration.

ACCELQ Annotations

Here are 3 important annotations used to build any user library command:

• @UserLibrary
• @Command
• @Parameter

Note:
Import the following packages in the Java class:

com.accelq.common.library.annotations.UserLibrary
com.accelq.common.library.annotations.Command
com.accelq.common.library.annotations.Parameter

Command Annotation

The @Command annotation marks a Java method as a command in ACCELQ, making it visible in the logic editor and shaping its presentation to users. This enables the addition of unique commands to the automation framework.

The @Command annotation includes several important attributes that provide detailed information about the command:

• displayName: A short, meaningful name that appears in the ACCELQ Action Logic Editor as part of the command listing.
• templateStr: A template string that represents the statement text that is displayed in the logic editor, including placeholders for parameters. This is what the user would read in the logic once this command is inserted.
• description: A detailed description of what the command does, helping users understand its purpose and how to use it.
• tags: Multiple tags or keywords separated by semicolons, which help in categorizing and searching for the command within ACCELQ.

Command Annotation Structure

@Command(displayName = "<Display Name>",
templateStr = "<Template String>",
description = "<Command Description>",
tags = "<Multiple tags/keywords separated by semi colon>")

Valid Return Types for Public Methods with @Command Annotation

Public methods annotated with @Command are limited to returning only specific types of values. The valid return types that such a method can return in Java are:

1. String: The method can return a string value. This is useful for commands that need to return text data, such as a message, a value retrieved from a web element, or any other string. You can return other primitive data types (e.g., int, float, double) after converting as Strings.

2. Boolean: The method can return a boolean value (true or false). This is typically used for commands that perform checks in conditional statements, indicating whether a certain condition is met or not. Usually used with /if, /while, /do-while statements.

3. ACCELQ List (as String): The method can return a list of items formatted as a string. This is useful for commands that need to return multiple values, such as a list of options available in a dropdown menu or any collection of items. Here is how you convert a Java List to String format accepted as ACCELQ List in the logic editor.

4. ACCELQ Map (as String): The method can return a map (key-value pairs) formatted as a string. This is suitable for commands that need to return a collection of key-value pairs, such as a set of attributes for a web element or any other associative array. Similar to lists, maps are also formatted as strings in ACCELQ. Here is how you convert a Java Map to an ACCELQ Map in string format.
   
   Learn more about ACCELQ Collections

Parameter Annotation

The @Parameter annotation in ACCELQ is used to define and describe the parameters of a method annotated with @Command. It provides essential details about each parameter, such as its name and a short description, which helps in understanding the purpose and expected value of the parameter.

There are different variations of @parameter annotations to choose from based on your requirements.

Basic Structure

Here is the basic structure of @Parameter annotation

@Parameter (name = "<Parameter Name> ", 
description = "<Short Description For about Parameter>")

@Parameter with a default value:

Here, in addition to the name and description, a defaultValue can be specified. This value is automatically populated in the parameter field in the Action Logic Editor when creating the statement, simplifying the command's use by pre-defining a common or suggested value.

@Parameter (name = "<Parameter Name>", 
description = "<Short Description For about Parameter>" , 
defaultValue = "<text to prepopulate in the parameter value>")

Restricting values to a Predefined List of Options

This variant restricts the user to select a value for a parameter from a predefined list of options (enumValues), ensuring users select only from acceptable values.

@Parameter (name = "<Parameter Name>", 
description = "<Short Description For about Parameter>" , 
enumValues = {"<option1>", "<option2>", "<option3>"})

Auto-selection from a List of Options:

Similar to the previous example, but with an added defaultValue, automatically selecting one of the options from the list. This combines the benefits of guided selection with the convenience of default values, streamlining the command configuration process for the users.

@Parameter (name = "<Parameter Name>", 
description = "<Short Description For about Parameter>" , 
enumValues = {"<option1>", "<option2>", "<option3>"}, 
defaultValue = "<one of the option from the enumValues to prepopulate in the field>")

Accepted Data Types for Parameters

While defining parameters for your commands, it's essential to know the accepted data types to ensure compatibility with ACCELQ's framework:

ACCELQ supports only two data types for parameters for methods with the @Command annotation:

• String:

  • A universal data type accepted by command parameters, useful for text inputs, numerical values represented as text, and more.

• WebElement:

  • com.accelq.core.ui.types.WebElement To work with ACCELQ smart locator element, allowing direct interaction with elements on a web page.

• Type Conversion:

  If you need to work with a data type other than String you can initially accept the parameter as a String and then convert it to the desired type using ACCELQ's built-in utility methods, such as converting a String to an Integer or String to double or ACCELQ web element to Selenium web element as explained in the next sections.

Built-in Methods to use in User Extensions:

Data Type Conversion for Parameters

ACCELQ provides built-in methods to assist with type conversions, particularly useful when you need to convert parameter types within custom commands. These methods are essential for handling data types like integers, web elements, maps, and lists, which are commonly required in automation scripts but need to be manipulated or converted to work within the framework. Here are examples of such methods:

Getting Web Driver Object of Current Web Automation Session:

SingletonInstancesRepo.getCurrentWebDriver(): Returns the WebDriver object (of type org.openqa.selenium.WebDriver) of the current web automation session.

Import Statement:
import com.accelq.core.SingletonInstancesRepo;

Converting String to Number:

• SingletonInstancesRepo.getAqNumericUtils().parseInteger(String number): Converts a string representation of a number into an integer.
• SingletonInstancesRepo.getAqNumericUtils().parseIntegerWithDefaultValue(String number, int defaultValue): Converts a string to an integer with a default value if conversion fails.
• SingletonInstancesRepo.getAqNumericUtils().parseDouble(String number): Converts a string to a double.

Import Statement:
import com.accelq.core.SingletonInstancesRepo;

Converting ACCELQ WebElement to Selenium WebElement:

• aqWebElement.toWebElement(): Converts an ACCELQ WebElement into a Selenium WebElement. This is useful when you need to apply Selenium-specific methods or interactions.
  

  Where aqWebElement is com.accelq.core.ui.types.WebElement type

Import Statement:
import com.accelq.core.ui.types.WebElement;

Conversions with ACCELQ Map

• Convert String to Map:
  • SingletonInstancesRepo.getAqMap().toMap(ACCELQ Map as String) returns java.util.HashMap<String, String>.
• Convert Map to String:
  • SingletonInstancesRepo.getAqMap().toJSONString(java.util.HashMap<String, String>) converts a map to a String in ACCELQ Map format.
    Learn more about ACCELQ Collections

Conversions with ACCELQ List

• Convert String to List:
  • SingletonInstancesRepo.getAqList().toList(ACCELQ List as String) returns java.util.List<String>.
• Convert List to String:
  • SingletonInstancesRepo.getAqList().toJSONString(java.util.List<String>) converts a list to a String in ACCELQ List format.
    Learn more about ACCELQ Collections
    
    

Note: Make sure to add the below import statement:
import com.accelq.core.SingletonInstancesRepo;

Working with file paths

If your command involves working with files located on the agent machine, then effective management of file paths is crucial for accessing and manipulating files during automated testing. The SingletonInstancesRepo.getAqFileUtils().getAbsolutePath(String filename) method plays a key role in this process. Here's how it works:

• For Absolute Paths: When an absolute file path is provided to this method, it recognizes the path as complete and returns it without modifications. An absolute path specifies a file or directory location in relation to the file system's root directory.

• For Relative Paths: If you provide a relative path (such as data\config.json), ACCELQ assumes it resides in the user_data folder of the ACCELQ Agent and then prepends the necessary portion to complete the path. 

For example, "data\config.json" gets internally translated to C:\Users\<user name>\ACCELQAgent\AgentInstances\agent\user_data\data\config.json

Logging in User Extension Commands

In ACCELQ user extensions, logging is essential for monitoring, debugging, and delivering runtime insights throughout the testing process. ACCELQ offers logging capabilities via built-in methods, enabling the inclusion of detailed log messages directly within the test execution report.

ACCELQ provides a set of methods for printing log messages of different severities, such as informational messages, warnings, errors, and verbose messages. These methods are accessible through the SingletonInstancesRepo.getAqLogUtils() utility.
Here are the primary methods used for logging within user extensions:

Information Logs

• SingletonInstancesRepo.getAqLogUtils().info_(String message): Prints an informational message to the log. This is a commonly used log printing method.

Error Logs

• SingletonInstancesRepo.getAqLogUtils().error_(String message): Prints an error message to the log. Use this for logging exceptions or errors encountered during the execution of your command.

Warning Logs

• SingletonInstancesRepo.getAqLogUtils().warn_(String message): Prints a warning message. This can be used for non-critical issues that do not halt the test execution.

Verbose Logs

• SingletonInstancesRepo.getAqLogUtils().verbose_(String message): Prints a detailed verbose message, useful for in-depth debugging and analysis. These messages are displayed in the Console log when running the logic in Playback mode.
  
  

Now lets create a sample user extension that clicks on an element on a web page and then enters text into the active element. Here's a step-by-step guide on how to do it.

Creating a simple User Extension

Start Simple:

First, work on your Java code without worrying about ACCELQ stuff. Make sure your code works well on its own by testing it thoroughly. This is your chance to make sure everything is perfect before adding ACCELQ into the mix.

Design Your Commands:

After your Java code is good to go, think about how you want your commands to work and look in ACCELQ. This is important because it affects how easy they are for others to use.

For this demo, we'll make a User Library command that clicks on an element and then allows you to enter text into an input field that appears after the click.

Lets set the display name of this command as "Click and Enter Text".

Lets have this command to accept 2 parameters:

• ACCELQ Web Element(com.accelq.core.ui.types.WebElement type from Smart-locator)
• Text to Enter(As String)

Now that we have a high level understanding of what we want to achieve. Lets proceed with the next steps.

Create a new Java project:

Add Dependencies:

Create a libs Directory: Inside your project folder, create a directory named libs.

Add JARs to Your IntelliJ Java Project: Locate the JAR files required by ACCELQ in the ACCELQAgent installation directory on your computer. You'll need to copy JARs from two locations:

• Third-party JARs from ~\ACCELQAgent\AgentInstances\agent\libs\3_p\
  

  
  
  

• ACCELQ internal JARs from ~\ACCELQAgent\AgentInstances\agent\software\accelq\base\libs\aq_fwk\default\
  
  
  

Copy these JAR files into the libs directory you created in your IntelliJ project.

Configure the IDE to Mark the libs Folder to Resolve Project Dependencies:

1. Right-click on the project name and select "Open Module Settings"

2. Click "Libraries" on the left-hand side, then click the + icon and select "Java".

3. Select the "libs" folder with all the dependency jars under the project folder > click "OK" button

4. Click the "OK" button

5. Click "Apply" and then click "OK"

Crafting Your User Extension

The following Java class demonstrates how to create a custom command in ACCELQ for clicking on a web element and entering text into the active element. 

  package com.<tenant_code>; // Replace '<tenant_code>' with your actual tenant code

import com.accelq.common.library.annotations.Command;
import com.accelq.common.library.annotations.Parameter;
import com.accelq.common.library.annotations.UserLibrary;
import com.accelq.core.ui.types.WebElement;
import com.accelq.core.SingletonInstancesRepo;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.By;

@UserLibrary
public class ClickAndEnterTextDemo {

    @Command(displayName = "Click and Enter Text",
             templateStr = "Click on <param1> and enter text <param2> in active element",
             description = "Clicks on the specified ACCELQ web element and enters the provided text into it",
             tags = "click;enter text;")
    public void clickAndEnterText(
            @Parameter(name = "Web Element", description = "The ACCELQ web element to interact with") WebElement aqElement,
            @Parameter(name = "Text To Enter", description = "Text to enter into the web element") String textToEnter) {
        try {
            // Convert ACCELQ WebElement to Selenium WebElement for more advanced operations
            org.openqa.selenium.WebElement webElement = aqElement.toWebElement();

            // Click on the converted Selenium WebElement to trigger any associated events
            webElement.click();

            // Retrieve the WebDriver instance from ACCELQ's current run for further actions
            WebDriver driver = SingletonInstancesRepo.getCurrentWebDriver();

            // Switch to the active element, likely the one just clicked or a related input field.
            org.openqa.selenium.WebElement activeElement = driver.switchTo().activeElement();

            // Enter the specified text into the active element, which is now focused
            activeElement.sendKeys(textToEnter);

            // Log a success message indicating the text was successfully entered
            SingletonInstancesRepo.getAqLogUtils().info_("Successfully clicked on the element and entered text: " + textToEnter);
        } catch (Exception e) {
            // Log an error message if any exception occurs during the click or text entry process
            SingletonInstancesRepo.getAqLogUtils().error_("Error interacting with the web element: " + e.getMessage());
        }
    }
}

Important: 
Before uploading to ACCELQ make sure the package name of the User library Class file has the below pattern:

package com.<tenant_code>;

You can get the tenant code from your profile icon in ACCELQ > Auth Properties


Also the user extension file name(.java file) and class name must be same.