VAPI-XP tests

The VAPI-XP testing tool enables you to create new testing scripts using Microsoft VBScript, Microsoft JavaScript (JScript version), PerlScript, and PythonScript, and integrate these scripts into your application management process.

VAPI-XP overview

Using VAPI-XP test scripts, you can test COM/DCOM servers, SOAP-based Web services, Java APIs (such as Java classes and EJBs), and console applications. You can also use VAPI-XP to create a LoadRunner virtual user.

In addition, VAPI-XP is fully integrated with ALM, enabling you to design your VAPI-XP test script to call any ALM test or test set, and execute it as part of your own script. This allows you to build a more advanced test set execution flow, in which you can filter tests in a test set during execution, based on the status or type of each test.

VAPI-XP is also fully integrated with the ALM Open Test Architecture API. All open test architecture API classes and methods can be referenced from the VAPI-XP user interface so that you can easily include them in your test script.

Note: The VAPI-XP testing tool is installed on a testing host by performing ALM Client Registration. Instructions for performing client registration can be found in the Application Lifecycle Management Installation and Upgrade Guide.

Back to top

Create VAPI-XP test scripts

You create a VAPI-XP test script from the test plan tree in the Test Plan module.

Note: You can also convert a manual test to a VAPI-XP test. In the Design Steps tab, click the Generate Script button and select VAPI-XP-TEST. ALM creates a VAPI-XP test script that includes code for the steps that you defined. It also includes code for called tests that were part of the original manual test. For details on manual tests, see Design tests.

To create a VAPI-XP test script:

  1. See Create tests to create a test and make sure the Type field is set to VAPI-XP-TEST.

  2. In the VAPI-XP Wizard dialog box, specify the following, and click Next.

    Note: In each dialog box, you can click Finish to close the wizard and continue creating the test script in the Test Script tab.

    Field Description
    Script Language

    Select a script language.

    Note:

    • To create a VAPI-XP test script using ActiveState's ActivePython or ActivePerl scripts, you must install the script language on your machine. From the Help menu in the Test Script tab, select ActivePython Home Page or ActivePerl Home Page, and follow the appropriate installation instructions.

    • Microsoft's VBScript and JScript are usually installed with Internet Explorer. If they are not installed on your machine, select VBScript Home Page or JScript Home Page from the Help menu in the Test Script tab, and follow the appropriate installation instructions.

    Script Name Enter a name for the VAPI-XP test script.
    Create a LoadRunner Vuser

    Enabled when you select VBScript or JavaScript as your test scripting language.

    Creates a LoadRunner virtual user script that can be run in the LoadRunner Controller.

    To run this virtual user in the Controller, you must install the latest version of the ALM Connectivity Add-in on your LoadRunner client machine. For details, see Tools, add-ins and extensions.

  3. In the Select a test type step of the wizard, select the type of test you want to create, and click Next.

  4. If you select the COM/DCOM Server Test test type, select the Program IDs of the COM/DCOM objects in your machine's registry that you want to test, and click the + button. Each selected COM/DCOM object and its description is displayed.

  5. If you select the Java Class Test test type, specify the following:

    Field Description
    Java Class Name

    Enter the full name of the Java class that you want to test, and click the + button. The Java class name you typed appears in the text box.

    You can only use a Java class that has a public constructor that does not take arguments.

    If you use a Java virtual machine, specify the following:
    JVM Runtime The Java virtual machine runtime executable file (usually java.exe).
    Java Compiler

    The executable file that recompiles the bytecode at the execution platform (usually javac.exe).

    Classpath A list of additional (non-standard) Java libraries, separated by semi-colons (;), required to run the specified Java application. Note that if you do not specify the Java classpath, ALM uses the environment variable CLASSPATH.
    JVM Parameters The parameters for the Java virtual machine run-time executable file.

    Note: When working with Java virtual machines, add the location of the BSF DLLs to the system path, as follows:

    1. In the Control Panel, choose System > System Properties, and then click the Advanced tab.

    2. Click the Environment Variables button, and in the System Variables area, edit the Path parameter by adding the path of the following DLLs: msvcp60.dll, bsfactivescriptengine.dll, and bsfactivescriptengine_g.dll.

    3. Click OK.

  6. If you select the Web Service (SOAP) Test test type, specify the following:

    Field Description
    SOAP Client Library

    Select the SOAP client library.

    Two SOAP client libraries are supported: Microsoft SOAP SDK and PocketSOAP. Even if you choose to work with PocketSOAP, you must install Microsoft SOAP SDK to parse Web services. If Microsoft SOAP SDK is not already installed on your machine, run the SoapToolkit30.exe file located in the Redist directory on your ALM installation DVD.

    Web Service Definition Enter or select the URL you want to test, and click the + button.
  7. If you select the Console Application Test test type, specify the following and click the + button.

    Field Description
    Application Executable File Enter the name of the application file you want to test.
    Command Line Parameters Enter the parameters of the application file you want to test.
    Use VAPI-XP Output instead of Standard Output Whether or not you want to replace the standard output with the VAPI-XP output window.
    Application Timeout

    Enter the time, in milliseconds, for ALM to wait for the application to finish running. Note that if the timeout is set to -1, ALM waits an infinite amount of time for the application to finish running.

  8. In the Service list, select the functions you want to add to your test script. Double-click each function, or drag and drop it, to add it to your script code. The function is added to the box below the Service list.

  9. If required, enter additional parameters or add extra code to the script in the lower pane.

  10. Click Finish. The new test appears in the test plan tree under the subject folder you selected.

Back to top

Edit VAPI-XP test scripts

After you create a VAPI-XP test script using the VAPI-XP Wizard, you can edit it in the Test Script tab.

Tip: You can display the Test Script tab in a separate window by selecting View > Window Screen, or clicking the Window Screen button .

To edit a VAPI-XP test script:

  1. In the test plan tree, select a VAPI-XP test, and click the Test Script tab. The test script is displayed.

  2. Note: To view or edit the properties of the test script you created, choose Test > Properties.

  3. To view a list of object definitions, methods, and properties that you can add to your script, select one of the following options:

    • Test > References > COM Library References. Opens the References dialog box in which you can choose the COM object definitions, methods, and properties you want to view.

    • Test > References > SOAP Web Service References. Opens the Add Web Service Reference dialog box in which you can type the Web service object definition or method you want to view.

    • Test > References > Java Class References. Opens the Add Java Class Reference dialog box in which you can type the Java class object definition or method you want to view.

  4. Select View > Browsers, or click the Show/Hide Browsers button . The following tabs are displayed.

    Tab Description
    Library

    Displays a list of VAPI-XP (SRunner), ALM (TDAPIOLELib), and COM/DCOM object definitions, methods, and properties that you can add to your script.

    For an explanation of VAPI-XP object definitions, methods, and properties, see Use VAPI-XP API.

    For an explanation of ALM object definitions, methods, and properties, see Open Test Architecture API Reference.

    Soap

    Displays a list of Web service object definitions and methods that you can add to your script.

    Java

    Displays a list of Java class object definitions and methods that you can add to your script.

    Function Displays a list of functions contained in your script.
    Object

    Displays a list of objects with defined names that you can add to your script.

    Note: For a description of each object definition, method, or property, select View > Output, and click the Help tab.

  5. To add an object definition, method, or property to the current function in your script, place the cursor in the appropriate place in your code, and double-click the object definition, method, or property in the Library, Soap, or Java tabs.

  6. To add an object with a defined name, select the object definition, method, or property in the Library, Soap, or Java tabs, and select Test > Add Object. In the Add Object dialog box, enter the name you want to assign to the object and click OK.

  7. To add the object to your script, double-click the object, or right-click it and select Insert into Script.

  8. To check the syntax of your code, select Test > Check Syntax, or click the Syntax Check button . Select View > Output to view the verification results in the Output tab.

  9. Perform additional editing functions in the Test Script tab:

    • To undo a previous action, click the Undo button . To restore an action that was undone, click the Redo button .

    • To remove a section of code from one part of your script, and place it in another part of the script, select the section and click the Cut and Paste buttons.

    • To copy a section of code from one part of your script, and place it in another part of the script, select the section and click the Copy and Paste buttons.

    • To delete a section of code, select it and click the Delete button .

    • To locate specific text within your script, click the Find in Script button . In the Find Text dialog box, type the text for which you want to search. Select the options, direction, scope, and origin for your search, and click OK.

      To find another occurrence of the text within the script, choose Search > Find Next.

    • To locate specific text within your script and replace it with different text, click the Replace button . In the Find Text dialog box, enter the text you want to search for in the Text to find box. Enter the text with which you want to replace this text in the Replace with box. Select the options, direction, scope, and origin for your search, and click OK. To replace all instances of the text in the script, click the Replace All button.

    • To locate a specific line number within your script, choose Search > Go to Line Number. In the Go to Line Number dialog box, type the line number you want to find, and click OK.

    • To change the editor options, such as the margins, fonts, and screen/text colors, click the Editor button . Set the properties you want in the Editor, Display, and Colors tabs, and click OK.

  10. After you have finished editing your script, click the Save button to save the changes you made.

Back to top

Use AUT Environments with VAPI-XP

ALM Editions:  AUT Environments and Functional test sets are available only for ALM Edition. For information about ALM editions and their functionality, see ALM editions. To find out which edition of ALM you are using, ask your ALM site administrator.

VAPI-XP tests can be run using server-side execution when they are part of a Functional test set. When using server-side execution, you can take advantage of AUT Environments. AUT Environments allows users to make test execution more dynamic by parameterizing the environment data used for testing. Instead of defining and running several different VAPI-XP tests that use the same logic but need different environment parameters, you can simply program your VAPI-XP test to use an already defined AUT environment configuration that ALM inserts into your test at run-time.

For information about setting up AUT environment configurations and environment parameters, see Lab Resources.

To use your AUT environment configuration in a VAPI-XP script, you use the following functions:

Post

Invoke this function before calling functions that access AUT parameters.

currentRun.post()

getRunTimeParameterByName

Returns the environment parameter value based on parameter name.

currentRun.getRunTimeParameterByName(Name)

Name. Environment parameter name.

getRunTimeParameterByGuid

Returns the environment parameter value based on parameter Guid.

currentRun.getRunTimeParameterByGuid(Guid)

Guid. Environment parameter Guid.

isSSE

Returns TRUE if the test is being run as a server-side execution test in a Functional test set.

currentRun.isSSE

ReservationId

Returns the timeslot ID of the test if the test is being run as a server-side execution test in a Functional test set.Otherwise, returns NULL.

currentRun.ReservationID

Back to top

Use VAPI-XP API

The VAPI-XP tool contains a built-in library of VAPI-XP object definitions that you can reference as you are creating your test script.

TDHelper object

The TDHelper object supplies the following functions that you can use to perform ALM-related tasks.

Function Description
RunTestSet

Executes the selected test set and returns the accumulated test set execution status.

RunTestSet([Name = "default"], [Filter = ""], [Locally = FALSE], [Host = ""], [HostGroup = ""])

Name. Test set name. Optional. Default = "default"

Filter. Test filter. Defines tests to run. If empty, instructs ALM to run all the tests in a specified test set. Optional. Default = ""

Locally. If set to TRUE, instructs ALM to run test set locally. Optional. Default = FALSE

Host. Host on which test set will be run. Optional. Default = ""

HostGroup. Host group in which test set will be run. Optional. Default = ""

RunTest

Executes the selected test and returns the test execution status.

RunTest(Name, Instance, TestSet, [Locally = FALSE], [Host = ""], [HostGroup = ""])

Name. Test name.

Instance. Test instance.

TestSet. Test set name.

Locally. If set to TRUE, instructs ALM to run test set locally. Optional. Default = FALSE

Host. Host on which test set will be run. Optional. Default = ""

HostGroup. Host group in which test set will be run. Optional. Default = ""

AddDefect

Adds a new defect to the current test, if the test is being run in debug mode. If the test is being run in test mode, a new defect is added to the current run of the test instance in the current test set. Returns a created defect object.

AddDefect([Fields], [stepKey])

Fields. Two-dimensional array—the first dimension is for the field name, and the second for the field value. Optional.

stepKey. step ID for step related to new defect. Optional.

AddDefectUI

Adds a new defect to the current test (in debug mode) or the current run (in test mode), using the ALM New Defect dialog box.

AddDefectUI([stepKey])

stepKey. step ID for step related to new defect. Optional.

AddStepToRun

Adds a new step to the current run. Returns a created step object.

AddStepToRun(Name, [Desc], [Expected], [Actual], [Status])

Name. Step name.

Desc. Step description. Optional.

Expected. Expected step result. Optional.

Actual. Actual step result. Optional.

Status. Step status. Optional.

DownLoadAttachment

Downloads the attachment associated with a test object. Returns the local path to which the download was performed.

DownLoadAttachment(Name, item)

Name. The attachment name.

item. Reference to the object with the attachment.

UpLoadAttachment

Uploads an attachment and associates it with a test object.

UpLoadAttachment(path, item)

path. The local path (fully specified file name) of the item to upload.

item. Reference to the object to which to associate the attachment.

TDInput object

The TDInput object supplies the following function that you can use to obtain an input value from an end user.

Function Description
GetInput

Displays the Input dialog box, enabling you to obtain an input value from an end user.

GetInput([Caption],[Name])

Caption. Dialog box caption. Optional.

Name. Name of the input value. Optional.

TDOutput object

The TDOutput object supplies the following functions that you can use to control the VAPI-XP Output tab.

Function Description
Clear Method

Clears the Output tab.

Clear

Print Method

Prints the text message to a new line in the Output tab.

Print(Msg)

HookDebug Property

Sets or removes the hook for the OutputDebugString tab API function.

HookDebug

Text Property

Gets or sets the Output tab text.

String Text

XTools object

The XTools object supplies the following functions that you can use to perform general tasks.

Function Description
run

Runs command line with passed attributes.

run(Command, [Args = ""], [Timeout = -1], [UseOutput = TRUE])

Command. Application executable file.

Args. Application arguments. Optional. Default = ""

Timeout. Timeout in milliseconds. If this is -1, ALM waits an infinite amount of time for the application to finish running.

UseOutput. If TRUE, ALM replaces the standard output with the VAPI-XP output window.

WrapArray

Creates an array of variants from an array of objects. For example, if a called object returns as a method result an array of strings, none of the supported script engines is able to read the array. Calling the WrapArray function and passing the returned array as a function parameter creates an array of variants that can be understood by the scripting engine.

WrapArray (array)

array. Array to wrap.

Sleep

Suspends script execution for a specified amount of time.

Sleep(interval)

interval. Time (in milliseconds) for script execution suspension

Back to top

Run VAPI-XP tests

After you create and edit your VAPI-XP test script, you can run it in debug mode or test mode.

Overview

Consider the following before running a VAPI-XP test:

Run a VAPI-XP test in debug mode

Enables you to execute the test without including it in a test set and without creating test run data in the ALM project.

It is generally recommended that you use the debug mode while you are developing your test, and switch the test mode once you have completed creating your test.

Run a VAPI-XP test in test mode

You can run your VAPI-XP test in test mode once you have added the test to a test set in the Test Lab module.

When you run a VAPI-XP test in test mode, test run data is created in the ALM project. You can run your VAPI-XP test in test mode from either the Test Plan or Test Lab module.

Note: To run VAPI-XP tests remotely, you must install the ALM Client Registration Add-in and the ALM Connectivity Add-in on the host machine on which the tests are executed. For details on add-ins, see Tools, add-ins and extensions.

To run a VAPI-XP test in debug mode:

  1. In the Test Plan module, select a VAPI-XP test from the test plan tree, and click the Test Script tab.

  2. Select Test > Execute (Debug Mode), or click the Execute Script button . ALM begins executing the test script you selected.

  3. Select View > Output to view the output generated by the test script.

    • To clear the Output tab, click the Clear Output button .

    • To copy the output text to the clipboard, select it and click the Copy Selected Text to Clipboard button .

    • To view the test script output in a Web browser, click the Open Output Text in Web Browser button .

    • To print the test script output, click the Print Output button .

  4. To stop executing the VAPI-XP test before it finishes running, select Test > Stop, or click the Stop button .

To run a VAPI-XP test in test mode from the Test Plan module:

  1. Select a VAPI-XP test from the test plan tree, and click the Test Script tab.

  2. Select Test > Execute (Test Mode). The Select Test Set dialog box opens.

  3. In the Test Set box, select the test set containing the current VAPI-XP test.

  4. In the Instance box, select the test instance that you want to run.

  5. In the Run Name box, type the name you want to assign to the test run.

  6. Click OK. ALM begins executing the test you selected.

  7. To view the output generated by the test script, select View > Output.

  8. To stop executing the VAPI-XP test before it finishes running, select Test > Stop, or click the Stop button .

To run a VAPI-XP test in test mode from the Test Lab module:

  1. From the Test Sets tab, select the test set containing the VAPI-XP test you want to run.

  2. In the Execution Grid, select the test you want to run, and click the Run button. The Automatic Runner dialog box opens, displaying the selected test.

  3. In the Run on Host column, select a host machine on which to run the VAPI-XP test, or choose Run All Tests Locally to run the test on your local machine.

  4. Click the Run button. The VAPI-XP Test Script window opens as ALM begins executing the selected VAPI-XP test. When ALM finishes executing the test, the Automatic Runner dialog box displays the status of the test run.

Back to top

Debug VAPI-XP test scripts

If your test run was not successfully completed, you can use VAPI-XP's Integrated Debugger to assist you in debugging your VAPI-XP test script.

Note: You cannot use the Integrated Debugger to debug PerlScript or PythonScript test scripts.

To debug a VAPI-XP test script:

  1. Select a VAPI-XP test from the test plan tree, and click the Test Script tab.

  2. Select Debug > Integrated Debugger. Additional buttons controlling the debugging process are displayed on the toolbar.

  3. To set a breakpoint in a script, select the line in the script where you want to set the breakpoint, and select Debug > Toggle Breakpoint or click the Toggle Breakpoint button .

    Alternatively, click the gray margin next to the line in the script. The line you selected is highlighted in red.

  4. Click the Execute Script button . ALM begins executing the script, stopping at the defined breakpoint. The Output tab displays the following message.

  5. To instruct ALM to enter the script after the breakpoint, select Debug > step Into or click the step Into button . The line in the script that follows the breakpoint is highlighted in blue.

  6. To instruct ALM to step over a line in the script, click the step Over button or select Debug > step Over.

  7. To instruct ALM to execute the script, select Debug > step Out or click the step Out button . The output is displayed in the Output tab.

  8. To view or edit the value of each variable in the script, select Debug > Variables or click the Show Variables button .

    The Variables dialog box opens, displaying the variables available in the current script. Select a variable to view its properties.

    To change a variable's value, in the Value box, enter the new value you want to assign to it and click Update. Click OK to save your changes and close the Variables dialog box.

  9. To view information about a specific variable while debugging, select Debug > Watch or click the Show Watch Window button to display the Watch tab.

    To add a variable to the Watch tab, click +, in the Prompt box, enter a variable name , and click OK. The variable and its values are displayed in the Watch tab.

  10. To instruct ALM to resume executing the script, select Debug > Resume Execution or click the Resume Execution button .

  11. Select Debug > Stop Debugging, or click the Stop Debugging button to stop the Integrated Debugger from debugging your script.

Back to top