Creating an Addon

This article covers getting started with creating addons using the Java SDK.
Getting Started
To get started, you need to complete the following prerequisites checklist:
Login to your account at https://app.testproject.io/ or register a new one.
​Download and install an Agent for your operating system or pull a container from Docker Hub.
Run the Agent and register it with your Account.
Download Java SDK for Addons​
Installation
The open source version (v2) of the SDK does not yet support addon creation, so you will need to add the downloaded SDK as a dependency in your pom.xml file. This article will show you how to do that in Eclipse, but you can of course follow similar steps in whichever IDE you are using. 
In an Eclipe project, make sure that you have a lib folder and if not add one to your project. Copy the Java SDK file that you downloaded from TestProject, into that folder. You should see something like this in  Eclipse:
TestProject SDK
Once you have done that, you can right click on the SDK file and choose the properties option. This will show you the Location of the SDK. Copy that location and then edit your pom.xml file  and add the following dependecy into it:
1
<dependency>
2
    <groupId>io.testproject</groupId>
3
    <artifactId>java-sdk</artifactId>
4
    <version>1.0</version>
5
    <systemPath>/path/to/sdk/TestProject_SDK_0.65.0.jar</systemPath>
6
    <scope>system</scope>
7
</dependency>
Copied!
You will of course, need to set the systemPath entry to the location that you copied the SDK into.
If you hare working with a Gradle project, you can add the dependency by adding the following to your build.gradle file:
1
 compile files("/path/to/sdk/TestProject_SDK_0.65.0.jar")
Copied!
Where once again the path is the location that you copied earlier. 
If you want to see more details, you can look at the pom.xml and build.gradlefiles in the examples of the addons github repository.
Addon development
In order to get started with developing and Addon, you will need a manifest file. This file contains a descriptor of your addon, which includes a unique GUID for the addon and a list of the permissions that the addon will need. TestProject will automatically generate this file for you.
Generating an Addon Manifest
In order to generate a manifest file, you will need to login to the TestProject App and then go the addons tab. Click on the Create Addon button:
Create Addon Button
On the resulting dialogue, give your addon a name. For this article we will implement a simple addon that gives us the ability to clear the fields on a form, so you can name it something like ClearFieldsExampleAddon. Click next and you can optionally give some additional details like the source code and documentation links if you have them. Click Next again and you can choose what permission your addon needs. In this example, you should not need any special permission, so you can leave them unselected and just click on the Generate and Download Manifest button to create the manifest.
Generate and Download Manifest
We will return to this dialog in a few minutes, keep it open for now
Once the manifest has downloaded, you will need to add it to the resources folder in your project. If you do not yet have that folder, add it under src/main. If you are using Eclipse, it should look something like this:
Manifest File in Eclipse
Now that you have the manifest file and the proper dependencies, you are ready to start implementing an addon.
Implement the Addon
Lets look at implementing the code for a simple Addon with a ClearFields action that clears a form. In order to do this, you will need to create a package in Eclipse. On the src/main/java folder, right-click and under new, choose Package. Name the package something like io.testproject.myaddon and click Finish. You can then add a class to that package by right-clicking on it and going to new>Class. Name the class something like ClearFieldsAction and click on Finish. You can then fill in the following code to create the addon.
1
package io.testproject.myaddon;
2
​
3
import io.testproject.java.annotations.v2.Action;
4
import io.testproject.java.sdk.v2.addons.WebAction;
5
import io.testproject.java.sdk.v2.addons.helpers.WebAddonHelper;
6
import io.testproject.java.sdk.v2.drivers.WebDriver;
7
import io.testproject.java.sdk.v2.enums.ExecutionResult;
8
import io.testproject.java.sdk.v2.exceptions.FailureException;
9
import org.openqa.selenium.By;
10
import org.openqa.selenium.WebElement;
11
​
12
@Action(name = "Clear Fields")
13
public class ClearFieldsAction implements WebAction {
14
​
15
    public ExecutionResult execute(WebAddonHelper helper) throws FailureException {
16
​
17
        // Get Driver
18
        WebDriver driver = helper.getDriver();
19
​
20
        // Search for Form elements
21
        for (WebElement form : driver.findElements(By.tagName("form"))) {
22
​
23
            // Ignore invisible forms
24
            if (!form.isDisplayed()) {
25
                continue;
26
            }
27
​
28
            // Clear all inputs
29
            for (WebElement element : form.findElements(By.tagName("input"))) {
30
                element.clear();
31
            }
32
        }
33
​
34
        return ExecutionResult.PASSED;
35
    }
36
}
Copied!
This addon will find all element on a page that have the form tag (unless the form is not being displayed) and clear any data that is in those form fields.
Packaging
It really is that easy to create your own addon, but you in order to use it in the test recorder you will need to upload it to the TestProject app. In order to do that, you have to first package it as JAR file. When you package up your code, do so as an uber-jar file with dependencies, excluding the TestProject SDK. If you are working with a Maven package, you can do this by adding the following to the pom.xml file.
1
<build>
2
    <plugins>
3
        <!-- Assembly Plugin - Create a JAR with dependencies for uploading to 
4
        TestProject -->
5
        <plugin>
6
            <artifactId>maven-assembly-plugin</artifactId>
7
            <configuration>
8
                <descriptors>
9
                    <descriptor>src/main/descriptor.xml</descriptor>
10
                </descriptors>
11
            </configuration>
12
            <executions>
13
                <execution>
14
                    <id>make-assembly</id>
15
                    <phase>package</phase>
16
                    <goals>
17
                        <goal>single</goal>
18
                    </goals>
19
                </execution>
20
            </executions>
21
        </plugin>
22
        <!-- Compile Plugin -->
23
        <plugin>
24
            <artifactId>maven-compiler-plugin</artifactId>
25
            <version>3.5.1</version>
26
            <configuration>
27
                <source>1.8</source>
28
                <target>1.8</target>
29
            </configuration>
30
        </plugin>
31
    </plugins>
32
</build>
Copied!
As you can see in the code above, the maven-assembly-plugin is going to look at the file src/main/descriptor.xml to find out what assemblies to generate. If you don't have that file yet, you can go ahead and create it from the right-click menu on the src/main folder. Choose new>File and naming the file descriptor.xml. Add the following xml into the file and save it:
1
​
2
<?xml version="1.0" encoding="UTF-8"?>
3
<assembly>
4
        xmlns="https://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"
5
        xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
6
        xsi:schemaLocation="https://maven.apache.org/plugins/maven-assembly-plugin/assembly/
7
        1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">
8
    <id>jar-with-dependencies</id>
9
    <formats>
10
        <format>jar</format>
11
    </formats>
12
    <includeBaseDirectory>false</includeBaseDirectory>
13
    <dependencySets>
14
        <!--Assemble all runtime dependencies-->
15
        <dependencySet>
16
            <outputDirectory>/</outputDirectory>
17
            <useProjectArtifact>true</useProjectArtifact>
18
            <unpack>true</unpack>
19
            <scope>runtime</scope>
20
        </dependencySet>
21
        <!--Extract TestProject SDK Properties-->
22
        <dependencySet>
23
            <outputDirectory>/</outputDirectory>
24
            <useProjectArtifact>true</useProjectArtifact>
25
            <scope>system</scope>
26
            <unpack>true</unpack>
27
            <includes>
28
                <include>io.testproject:java-sdk</include>
29
            </includes>
30
            <unpackOptions>
31
                <includes>
32
                    <include>testproject-sdk.properties</include>
33
                </includes>
34
            </unpackOptions>
35
        </dependencySet>
36
        <!--Exclude TestProject SDK from the resulting JAR-->
37
        <dependencySet>
38
            <outputDirectory>/</outputDirectory>
39
            <unpack>true</unpack>
40
            <scope>system</scope>
41
            <excludes>
42
                <exclude>io.testproject:java-sdk</exclude>
43
            </excludes>
44
        </dependencySet>
45
    </dependencySets>
46
</assembly>
Copied!
This file provides the information maven needs in order to assemble all the dependencies for the jar file along with the SDK properties, while excluding the SDK itself from the jar file.
Once you have these files created and saved, you can run the commands to package it up. First make sure everything in maven is up to date, by going to Maven on the right click menu and choosing the Update Project option. You can then make sure everything is ready by going to  Run As on the right click menu and choosing Maven Clean. Once you run that choose the Maven build option ensuring that the Goal is set to package.  This should create the jar files that you need and if you refresh the package, you should see jar files in the target folder of your package.
Generated Addon Files
You will need to upload the jar-with-dependencies.jar file to TestProject which you can see how to do in the next section.
If you prefer to build with gradle, you can use the following build.gradle file to package your addons, just update the TP_SDK variable to the correct location of the TestProject SDK on your system.
1
group 'io.testproject'
2
version '1.0.1'
3
​
4
apply plugin: 'java'
5
​
6
// Update the location of TestProject SDK JAR file
7
def TP_SDK = "__PATH_TO_LOCAL_JAR__/io.testproject.sdk.java.jar"
8
​
9
compileJava.options.encoding = 'UTF-8'
10
​
11
sourceCompatibility = 1.8
12
​
13
repositories {
14
    mavenCentral()
15
}
16
​
17
// Configurations
18
configurations {
19
    tpsdk
20
    compile.extendsFrom tpsdk
21
}
22
​
23
// JAR Task
24
jar {
25
    assert file("${TP_SDK}").exists() : "TestProject SDK JAR file was not found, please update the TP_SDK variable"
26
    archiveName "${rootProject.name}-${version}.jar"
27
    dependsOn configurations.runtime
28
    from {
29
        // Removes TestProject SDK from the final jar file
30
        (configurations.runtime - configurations.tpsdk).collect {
31
            it.isDirectory() ? it : zipTree(it)
32
        }
33
    }
34
​
35
    // Extract SDK version
36
    from {
37
        (configurations.tpsdk).collect {
38
            zipTree(it).matching {
39
                include 'testproject-sdk.properties'
40
            }
41
        }
42
    }
43
}
44
​
45
dependencies {
46
    tpsdk files("${TP_SDK}")
47
}
Copied!
Uploading the Addon to TestProject
Once you have packaged up the addon, you can add it into the TestProject application. Go back to the TestProject application and click Next on the dialog. You can then upload the file.
Upload Addon File
Once the file has uploaded, click Next and then review your actions to make sure everything looks good.
Review Addon Actions
Click Finish and the addon will be created in your TestProject account. You can go to the Addon page and then click on My Addons to see the addon you just uploaded.
New Addon
And that is all it takes!  You can now start using the actions in this addon while making recorded tests. If you create a recorded test that loads the https://example.testproject.io/web page and enters some text into the form, you can then add a step to the test and search for the addon. In this case, since you are using the same addon that is used in other examples, you might see multiple instances of it. If you mouse-over the addons, you will be able to see which one is yours and choose it. 
Add a step using your addon
If you are not yet familiar with the test recorder, you can checkout the section in the docs on getting started with creating a web test.  This simple example shows you how to get started, but there are many different options available when creating your own Addons. Check out the next section of the documentation to see the details of the kinds of things you can do when creating addons.