This topic explains how to extend SOAtest and Virtualize with custom tools. Sections include: SOAtest and Virtualize include a framework for adding your custom tools. Custom tools can be configured to perform custom executions on input. For example, a custom tool might modify a variable, or remove browser cookies. After setting up your environment for a custom extension, implement the following interfaces (described in the Extensibility API documentation): This is a required class that will be used to implement the tool execution logic. There are three methods to implement in this interface: You will implement your tool’s execution logic using the execute() method, which provides you with an IToolInput and IToolContext. The IToolInput contains the input message being sent to your tool, such as XML or traffic from a request or response. The context provides access to the UI configuration and output manager. Returning true indicates a successful tool execution, while false indicates a tool failure. The output manager can be used to send an IToolInput to tools that are chained to instances of your custom tool. You can either construct your own implementation of an IToolInput, or use a default implementation provided by Parasoft. For example, assume that you defined two outputs in your parasoft-extension.xml: In SOAtest or Virtualize, you could select your custom tool, click the Add test or output (SOAtest) or Add responder or output (Virtualize) button, and add tools to the selected output. The following is an example of constructing inputs and passing them to the chained output tools: If errors are encountered during tool execution, one or more errors should be reported using IToolContext.report(String). If a fatal error is encountered that prevents the tool execution from completing, a CustomToolException should be thrown; this will abort the execution of the tool and cause it to fail, in addition to aborting scenario execution (if the scenario is set to abort on fatal errors). Errors reported in either manner will get reported to the Quality Tasks view. Additional methods to implement: When working with IToolInputs, you will need to check the specific type of IToolInput that gets passed to the tool. In the majority of cases, SOAtest or Virtualize will pass an instance of a subinterface of IToolInput. However, there may be some cases where the input cannot be converted to a more specific subinterface of IToolInput. In those cases, a simple IToolInput will get passed to the tool. IToolInput has no method, but there is a way to get access to the internal object being used. All IToolInputs will be instances of an internal interface called com.parasoft.tool.IToolInputWrapper. You can cast to that interface and then call the getToolUsable() method to get access to the internal object being used. A similar case might occur when passing inputs to the outputs of a custom tool. You may need to pass an object from the internal API, rather than an instance of a more specific subinterface of IToolInput. In that case, you would return an instance of the internal interface com.parasoft.tool.IToolInputWrapper, which returns a com.parasoft.tool.ToolUsable. After you have implemented the necessary classes, define parasoft-extension.xml as follows: This element is unique to this extension type and must be valid and correct for your custom tool to be imported. Attributes: icon - Optional attribute that allows you to provide the name of a custom icon to be displayed next to the tool name in menus and next to the assets using the tool in the Test Case Explorer (SOAtest) or Virtual Asset Explorer (Virtualize). If not provided, a default icon will be used. This element is unique to this extension type and must be valid and correct for your custom tool to be imported. It defines input fields for your custom tool. Attributes: If you want a GUI field to serve as a password field (with inputs masked and the specified password saved securely), give that field element a If you want a GUI field to be implemented as an XPath chooser, give that field a Data Sources, Data Bank values, environment variables and test or responder suite variables can be referenced in the extension GUI fields using the Verify that your new tool was created and listed among other Parasoft defined tools.About Custom Tools
Interfaces to Implement for Custom Tools
ICustomTool Implementation
<output key="output_1" name="traffic header"/>
<output key="output_2" name="traffic body"/>
public boolean execute(IToolInput input, IToolContext context) throws CustomToolException
{
String charset ="UTF-8";
String mimeType ="text/plain";
String header ="";
String message ="";
. . .
DefaultTextInput headerOutput = new DefaultTextInput(header, charset, mimeType);
context.getOutputManager().runOutput("output_1", headerOutput, context);
. . .
DefaultTextInput msgOutput = new DefaultTextInput(message, charaset, mimeType);
context.getOutputManager().runOutput("output_2", msgOutput, context);
. . .
return true;
}
Defining parasoft-extension.xml for a Custom Tool
<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="urn:ocm/parasoft/extensibility-framework/v1/extension"
type="tool"
name='the name of your tool, appears in menus'
description='A more detailed description'>
<class>com.myCompany.MyTool</class> <!-- implements ICustomTool -->
<version id='your version ID' updaterClass="com.myCompany.myUpdater"/>
<tool xmlns="http://schemas.parasoft.com/extensibility-framework/v1/tool"
icon="myIcon.gif"
useInputTab="true"
successIndicator="true"
category="myCategory"
supportXmlConversion="true"
showInToolList="common"
showInOutputList="common">
<outputs>
<output key="key" name="output name"/>
...
</outputs>
</tool>
<form xmlns="urn:com/parasoft/extensibility-framework/gui">
<section label="field group 1">
<field id="key 1" label="field 1"/>
<field id="key 2" label="field 2"/>
<field id="element" label="Select an element" type="xpath"/>
</section>
<section label="field group 2">
<field id="key 3" label="field 1"/>
<field id="usr" label="Username"/>
<field id="pwd" label="Password" type="password"/>
. . .
</section>
. . .
</form>
</extension>
<tool> Element
<form> Element
string (a normal field), xpath (provides XPath Chooser functionality) or password (hides the value as you type and encrypts the value when saved).Tips
type attribute. This can be set to:string: A normal field.xpath: Provides XPath Chooser functionality.password: Hides the value as you type and encrypts the value when saved.type attribute which is set to password. For example, the following sets the pwd field to password mode:<form xmlns="urn:com/parasoft/extensibility-framework/gui">
<section label="Main Settings">
<field id="usr" label="Username"/>
<field id="pwd" label="Password" type="password"/>
</section>
</form>
type element which is set to xpath. For example, the following sets the element field to an XPath chooser:<form xmlns="urn:com/parasoft/extensibility-framework/gui">
<section label="Main Settings">
<field id="element" label="Select an element" type="xpath"/>
</section>
</form>
supportXmlConversion option in parasoft-extension.xml. Tool users will be able to select the desired message format in the tool’s configuration panel. Additionally, if an XPath selector is implemented (see above), its tree view will display messages in the format appropriate for the selected message type. (Note that the the message format is set in the Message Format section of the tool’s configuration panel).
${var_name} syntax. The standard "Parameterized" and "Scripted" GUI controls can also be used to parameterize fields.Verifying the New Tool
Overview
Content Tools
Need assistance? Visit our support page