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. For 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. An everyday 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 to 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 per your needs. Parameters can be found in the custom API Java file and are annotated with @TestApiParameter. The following includes a summary of each parameter type and how they should be used.
seq= This defines a sequence of parameters in the custom API. 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;
For more information, check out this course on University of Provar.
- Provar Automation
- System Requirements
- Browser and Driver Recommendations
- Installing Provar Automation
- Updating Provar Automation
- Licensing Provar
- Granting Org Permissions to Provar Automation
- Optimizing Org and Connection Metadata Processing in Provar
- Using Provar Automation
- Understanding Provar’s Use of AI Service for Test Automation
- Provar Automation
- Creating a New Test Project
- Import Test Project from a File
- Import Test Project from a Remote Repository
- Import Test Project from Local Repository
- Commit a Local Test Project to Source Control
- API Testing
- Behavior-Driven Development
- Consolidating Multiple Test Execution Reports
- Creating Test Cases
- Custom Table Mapping
- Functions
- Debugging Tests
- Defining a Namespace Prefix on a Connection
- Defining Proxy Settings
- Environment Management
- Exporting Test Cases into a PDF
- Exporting Test Projects
- Japanese Language Support
- Override Auto-Retry for Test Step
- Customize Browser Driver Location
- Mapping and Executing the Lightning Article Editor in Provar
- Managing Test Steps
- Namespace Org Testing
- NitroX
- Provar Test Builder
- ProvarDX
- Refresh and Recompile
- Reintroduction of CLI License Check
- Reload Org Cache
- Reporting
- Running Tests
- Searching Provar with Find Usages
- Secrets Management and Encryption
- Setup and Teardown Test Cases
- Tags and Service Level Agreements (SLAs)
- Test Cycles
- Test Data Generation
- Test Plans
- Testing Browser – Chrome Headless
- Testing Browser Options
- Tooltip Testing
- Using the Test Palette
- Using Custom APIs
- Callable Tests
- Data-Driven Testing
- Page Objects
- Block Locator Strategies
- Introduction to XPaths
- Creating an XPath
- JavaScript Locator Support
- Label Locator Strategies
- Maintaining Page Objects
- Mapping Non-Salesforce fields
- Page Object Operations
- ProvarX™
- Refresh and Reselect Field Locators in Test Builder
- Using Java Method Annotations for Custom Objects
- Applications Testing
- Database Testing
- Document Testing
- Email Testing
- Email Testing in Automation
- Email Testing Examples
- Gmail Connection in Automation with App Password
- App Configuration for Microsoft Connection in MS Portal for OAuth 2.0
- OAuth 2.0 Microsoft Exchange Email Connection
- Support for Existing MS OAuth Email Connection
- OAuth 2.0 MS Graph Email Connection
- Create a Connection for Office 365 GCC High
- Mobile Testing
- OrchestraCMS Testing
- Salesforce CPQ Testing
- ServiceMax Testing
- Skuid Testing
- Vlocity API Testing
- Webservices Testing
- Provar Manager
- How to Use Provar Manager
- Provar Manager Setup
- Provar Manager Integrations
- Release Management
- Test Management
- Test Operations
- Provar Manager and Provar Automation
- Setting Up a Connection to Provar Manager
- Object Mapping Between Automation and Manager
- How to Upload Test Plans, Test Plan Folders, Test Plan Instances, and Test Cases
- Provar Manager Filters
- Uploading Callable Test Cases in Provar Manager
- Uploading Test Steps in Provar Manager
- How to Know if a File in Automation is Linked in Test Manager
- Test Execution Reporting
- Metadata Coverage with Manager
- Provar Grid
- DevOps
- Introduction to Provar DevOps
- Introduction to Test Scheduling
- Apache Ant
- Configuration for Sending Emails via the Automation Command Line Interface
- Continuous Integration
- AutoRABIT Salesforce DevOps in Provar Test
- Azure DevOps
- Running a Provar CI Task in Azure DevOps Pipelines
- Configuring the Automation secrets password in Microsoft Azure Pipelines
- Parallel Execution in Microsoft Azure Pipelines using Multiple build.xml Files
- Parallel Execution in Microsoft Azure Pipelines using Targets
- Parallel execution in Microsoft Azure Pipelines using Test Plans
- Bitbucket Pipelines
- CircleCI
- Copado
- Docker
- Flosum
- Gearset
- GitHub Actions
- Integrating GitHub Actions CI to Run Automation CI Task
- Remote Trigger in GitHub Actions
- Parameterization using Environment Variables in GitHub Actions
- Parallel Execution in GitHub Actions using Multiple build.xml Files
- Parallel Execution in GitHub Actions using Targets
- Parallel Execution in GitHub Actions using Test Plan
- Parallel Execution in GitHub Actions using Job Matrix
- GitLab Continuous Integration
- Travis CI
- Jenkins
- Execution Environment Security Configuration
- Provar Jenkins Plugin
- Parallel Execution
- Running Provar on Linux
- Reporting
- Salesforce DX
- Git
- Version Control
- Salesforce Testing
- Recommended Practices
- Salesforce Connection Best Practices
- Improve Your Metadata Performance
- Java 21 Upgrade
- Testing Best Practices
- Automation Planning
- Supported Testing Phases
- Provar Naming Standards
- Test Case Design
- Create records via API
- Avoid using static values
- Abort Unused Test Sessions/Runs
- Avoid Metadata performance issues
- Increase auto-retry waits for steps using a global variable
- Create different page objects for different pages
- The Best Ways to Change Callable Test Case Locations
- Working with the .testProject file and .secrets file
- Best practices for the .provarCaches folder
- Best practices for .pageObject files
- Troubleshooting
- How to Use Keytool Command for Importing Certificates
- Installing Provar After Upgrading to macOS Catalina
- Browsers
- Configurations and Permissions
- Connections
- DevOps
- Error Messages
- Provar Manager 3.0 Install Error Resolution
- Provar Manager Test Case Upload Resolution
- Administrator has Blocked Access to Client
- JavascriptException: Javascript Error
- macOS Big Sur Upgrade
- Resolving Failed to Create ChromeDriver Error
- Resolving Jenkins License Missing Error
- Resolving Metadata Timeout Errors
- Test Execution Fails – Firefox Not Installed
- Selenium 4 Upgrade
- Licensing, Installation and Firewalls
- Memory
- Test Builder and Test Cases
- Release Notes