We're here to help

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 1Download 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.