Creating custom APIs
Custom test steps are a way to extend the standard features of Provar by writing your own logic in the form of an API and invoke it easily across all test cases. As an example, you can create a Custom API to trigger an External ANT Task from a test case.
Creating a custom API
To create a Custom API:
Step 1: Click the New Test button and select New Test API:
Step 2: Enter a Name, Title and Summary. (Name is the name of the Java class whereas Title is the display name of the API.) Then click the Finish button:
Step 3: Open the newly created .java file by navigating to the folder src/customapis in the Navigator view, then double-clicking on the file:
Step 4: Locate the following section in the file and add your own logic in Java:
Step 5: Click Save. To use the new Test API, locate it in the Test Palette and click and drag it into the Test Case.
Example 1: Trigger External ANT Tasks
This example shows how to create a Custom API for triggering an external ANT Task. A common use case for this is to trigger an ANT task to deploy a package in a Salesforce environment, followed by test data setup steps.
Step 1: Download Apache ANT jar and ANT Launcher jar and import them to the Project using the steps described in importing and executing JAR files.
Step 2: Download the following custom API text and add it into your Test Project under the folder src/customapis:
package customapis;
import java.io.Console;
import java.io.File;
import java.util.logging.Logger;
import org.apache.tools.ant.BuildEvent;
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.BuildListener;
import org.apache.tools.ant.DefaultLogger;
import org.apache.tools.ant.Project;
import org.apache.tools.ant.ProjectHelper;
import com.provar.core.model.base.api.ValueScope;
import com.provar.core.testapi.ITestExecutionContext;
import com.provar.core.testapi.annotations.TestApi;
import com.provar.core.testapi.annotations.TestApiExecutor;
import com.provar.core.testapi.annotations.TestApiParameter;
import com.provar.core.testapi.annotations.TestApiParameterGroup;
import com.provar.core.testapi.annotations.TestApiParameterGroups;
import com.provar.core.testapi.annotations.TestExecutionContext;
import com.provar.core.testapi.annotations.TestLogger;
@TestApi( title="RunANTTask"
, summary=""
, remarks=""
, iconBase=""
, defaultApiGroups={"My Test APIs"}
)
@TestApiParameterGroups(parameterGroups={
@TestApiParameterGroup(groupName="inputs", title="Inputs"),
@TestApiParameterGroup(groupName="result", title="Result"),
})
public class RunANTTask {
@TestApiParameter(seq=1,
summary="Path to ANT build file",
remarks="",
mandatory=true,
parameterGroup="inputs")
public String path;
@TestApiParameter(seq=2,
summary="Name of the ANT build file",
remarks="",
mandatory=true,
parameterGroup="inputs")
public String buildFileName;
@TestApiParameter(seq=3,
summary="Provide the name of the Target. Leave blank if you want default target to be picked",
remarks="",
mandatory=false,
parameterGroup="inputs")
public String targetName;
@TestApiParameter(seq=10,
summary="The name that the result will be stored under.",
remarks="",
mandatory=true,
parameterGroup="result")
public String isTaskSuccessful;
@TestApiParameter(seq=11,
summary="The lifespan of the result.",
remarks="",
mandatory=true,
parameterGroup="result",
defaultValue="Test")
public ValueScope resultScope;
/**
* Used to write to the test execution log.
*/
@TestLogger
public Logger testLogger;
/**
* Provides access to facilities, mainly to set and get variable values.
*/
@TestExecutionContext
public ITestExecutionContext testExecutionContext;
// Store the result (if appropriate).
final String[] dummyResult = new String[1];
@TestApiExecutor
public void execute() {
File buildFile = new File(path, buildFileName);
// Prepare Ant project
Project project = new Project();
project.setUserProperty("ant.file", buildFile.getAbsolutePath());
DefaultLogger consoleLogger = new DefaultLogger();
consoleLogger.setErrorPrintStream(System.err);
consoleLogger.setOutputPrintStream(System.out);
consoleLogger.setMessageOutputLevel(Project.MSG_INFO);
project.addBuildListener(consoleLogger);
project.addBuildListener(new BuildListener() {
@Override
public void taskStarted(BuildEvent arg0) {
// TODO Auto-generated method stub
testLogger.info("=====Task Started=====");
}
@Override
public void taskFinished(BuildEvent arg0) {
// TODO Auto-generated method stub
testLogger.info("=====Task Finished : " + arg0.getMessage() + "=====");
}
@Override
public void buildStarted(BuildEvent arg0) {
// TODO Auto-generated method stub
testLogger.info("======Build started : " + arg0.getMessage() + "=====");
}
@Override
public void buildFinished(BuildEvent arg0) {
// TODO Auto-generated method stub
if(arg0.getException() == null ) {
testLogger.info("=====Build Successful=====");
dummyResult[0] = "true";
} else {
testLogger.info("=====Build Failed=====");
dummyResult[0] = "false";
}
}
@Override
public void messageLogged(BuildEvent arg0) {
// TODO Auto-generated method stub
testLogger.info(arg0.getMessage());
}
@Override
public void targetFinished(BuildEvent arg0) {
// TODO Auto-generated method stub
testLogger.info("=====Target finished : " + arg0.getMessage() + "=====");
}
@Override
public void targetStarted(BuildEvent arg0) {
// TODO Auto-generated method stub
testLogger.info("=====Target started : " + arg0.getMessage() + "=====");
}
});
// Capture event for Ant script build start / stop / failure
try {
project.fireBuildStarted();
project.init();
ProjectHelper projectHelper = ProjectHelper.getProjectHelper();
project.addReference("ant.projectHelper", projectHelper);
projectHelper.parse(project, buildFile);
// If no target specified then default target will be executed.
if(targetName != null) {
project.executeTarget(targetName);
}
else {
project.executeTarget(project.getDefaultTarget());
}
project.fireBuildFinished(null);
// testLogger.info(dummyResult[0]);
} catch (BuildException buildException) {
project.fireBuildFinished(buildException);
throw new RuntimeException("!!! Unable to restart !!!", buildException);
} finally {
testExecutionContext.setValue(isTaskSuccessful, dummyResult[0], resultScope);
}
}
}
Step 3: Create a new Test Case, then locate the new Custom API in the Test Palette and click and drag it into the Test Case:
Step 4: Populate the following parameters:
- Path: The absolute path to the ANT build file
- Build File Name: Name of the ANT build file to be executed
- Target Name: Name of the Target that you need to execute. Provar will pick up the default Target if this is left blank
After the ANT task is executed, it will give the result in a variable defined under Is Task Successful. This Custom API will respond with an output of TRUE if executed successfully, or FALSE if any error was encountered. The full ANT logs can be viewed in the Test Runner.
Types of parameters for custom APIs
If you create a new custom API, Provar will provide several different parameter types including string, Boolean, number, float, date and list. You can use the default parameters provided or edit them as per your needs. Parameters can be found in the custom API Java file and are annotated with @TestApiParameter. The following includes a brief summary of each parameter type and how they should be used.
seq= This defines a sequence of parameters in the custom API. Make sure you select a different seq for each parameter defined in the custom API.
Note: Your API will produce an error if the same seq number is selected for different parameters belonging to the same group.
summary= A summary to describe the purpose of the parameter.
remarks= Additional remarks if any.
mandatory= Entries in this field should be true or false. This defines if the input field is mandatory or not.
parameterGroup= Describes which parameter group the parameter is associated with.
Type 1 – String
The following example shows a String parameter type.
@TestApiParameter(seq=1, summary="The first parameter's summary.", remarks="", mandatory=true, parameterGroup="inputs") public String param1;
Note: Because it is marked as mandatory = true, The Param 1 is required message is displayed.
Type 2 – Boolean
The following highlights how Boolean syntax appears in Provar.
@TestApiParameter(seq=1, summary="The first parameter's summary.", remarks="", mandatory=true, parameterGroup="inputs") public boolean param1;
Type 3 – Numbers (Integer)
The following example shows a number (integer) parameter type.
@TestApiParameter(seq=1, summary="The first parameter's summary.", remarks="", mandatory=true, parameterGroup="inputs") public int param1;
Type 4 – Numbers (Float)
The following example shows a number (float) parameter type.
@TestApiParameter(seq=1, summary="The first parameter's summary.", remarks="", mandatory=true, parameterGroup="inputs") public float param1;
Type 5 – Date
The following example shows a date parameter type.
@TestApiParameter(seq=1, summary="The first parameter's summary.", remarks="", mandatory=true, parameterGroup="inputs") public Date param1;
Type 6 – List
The following example shows a list parameter type.
@TestApiParameter(seq=1, summary="The first parameter's summary.", remarks="", mandatory=true, parameterGroup="inputs") public List param1;
Note: If you are using a list type parameter, make sure to import the following – import java.util.List;