Test Script Console Adapter API

prevnext

About the Test Script Console Adapter


A Test Script Console Adapter (TSCA) is a C or C++ dynamic-link library (DLL) that integrates with TestManager. By so doing, it enables additional test script types to be available for operations.

Each test script type is associated with a particular TSCA. A TSCA is required to allow the user to access a test script through the user interface.

Note: The TSCA does not support test script execution; this function is carried out by the TSEA and TSEE, as described in Chapter 2.


TSCA Functionality

A TSCA must, at a minimum:

In addition to these basic functions, many TSCAs are designed to support more sophisticated functions. A more robust TSCA might support such operations as:


Built-In and Custom Test Script Types

As described in Chapter 1, you can implement a test case with a test script that is either a built-in test script type or a custom test script type.

If you create a custom test script type, you must extend TestManager to support this new type. To extend TestManager, do one of the following:


The TSCA Function Calls

The TSCA applications programming interface (API) consists of 31 functions that are organized into nine functional groupings.


Functional Groupings of TSCA Functions

The Test Script Console Adapter (TSCA) functions are summarized in the following table, which shows:

Function Group and Purpose Functions in Group
Connection Supports connection and disconnection from the test script source. TTConnect()
TTDisconnect()
Data Access Provides access to the test scripts within the source:
  • Hierarchical data

  • Nonhierarchical data

  • Sources with different test script types

  • Functions providing icons for source and test scripts

TTGetRoots()
TTGetChildren()
TTGetNode()
TTGetName()
TTGetTypeIcon()
TTGetSourceIcon()
TTGetIcon()
Editor Integration Provides integration between TestManager and the editor or IDE used to create and edit test scripts. TTNew()
TTEdit()
Filtering Provides support to filter out test scripts that do not meet user-defined criteria. TTSetFilterEx()
TTGetFilterEx()
TTClearFilter()
UI Support Provides the ability to expose components that display test script properties. This facilitates the use of preexisting user interfaces. TTShowProperties()
TTSelect()
Source Configuration Support Supports the ability to provide custom user interfaces to aid in the configuration of the test script source. TTGetConfiguration()
TTSetConfiguration()
Custom Action Execution Provides the ability to perform custom operations on the test script source. TTGetSourceActions()
TTGetNodeActions()
TTExecuteSourceAction()
TTExecuteNodeAction()
Source Control Provides the ability to support source control operations in the test script view on the test scripts within a source. TTAddToSourceControl()
TTCheckIn()
TTCheckOut()
TTUndoCheckout()
TTGetSourceControlStatus()
Execution Supports execution of the test script. TTGetTestToolOptions()
Miscellaneous Infrastructure Provides infrastructure support TTGetIsFunctionSupported()


Required and Optional Functionality

A TSCA must, at a minimum, provide the ability to:

To enable these actions, you must implement the following functions when building a basic TSCA:

In addition, to enable users to view test scripts in Test Script View, you must include the following functions:

Other functions are optional; they enable the user to work with the user interface to perform additional operations on the test script. The advantages of using these additional functions are described in Building a TSCA: Workflow and Implementation Issues.

Some functions work in pairs. For example, because TestManager calls TTConnect() to make the connection to the test script source, it must subsequently call TTDisconnect() to disconnect from the test script source.

For information about specific declarations, see the following required header file:

...\Rational Test\rtsdk\c\include\testypeapi.h


Mapping of User Actions to TSCA Function Calls

A TestManager end user may want to carry out various actions on the test script source. Following is a list of common test script operations that the user might perform. The order in which these operations are listed represents a plausible sequence in which the user might execute them.

  1. Defining or modifying the configuration of a test script source.

  2. Opening the Test Script view.

  3. Setting a filter for test scripts.

  4. Creating a new test script.

  5. Selecting a test script for operations.

  6. Editing test script properties.

  7. Editing test script text.

  8. Performing custom actions on the test script or test script source.

  9. Integrating with source control.

To aid the user in carrying out these actions, you should build the TSCA to support the test script view that enables the user to perform these operations.

When the user makes a selection in the GUI to carry out an operation on the test script source, TestManager typically calls the TSCA function or functions that support the user's action.

To help you understand which functions you need to implement in order to provide support for specific actions, the following sections explain the mapping between the user's actions and the TSCA functions called by TestManager to implement those actions.

Note: Based on the current state of TestManager (including which test-script-related operations it has already performed), TestManager may not call some of the functions listed in the following sequences.


Defining or Modifying the Configuration of a Test Script Source

When the user defines or modifies a configuration for a test script source (for example, specifying the operating system), TestManager calls the following functions from the Source Configuration group in the order listed.

Typical Sequence of Function Calls Operation
  1. TTGetConfiguration()

Exposes user interface elements that collect data access and data format information from the user when registering the test script source. The TSCA passes that information back to TestManager to be persisted as a property of the test script source.
  1. TTSetConfiguration()

When a connection is made to the test script source, TestManager passes the configuration information obtained from the TTGetConfiguration() function into this function.


Opening the Test Script View

When the user opens up the Test Script view, TestManager calls the following functions from the Connection group in the order listed below.

,
Typical Sequence of Function Calls Operation
  1. TTConnect()

Establishes a connection to the test script source.
  1. TTGetSourceIcon()

Returns the path to the bitmap containing the icon that represents the test script source. Note that implementation of this function is optional.


Setting a Filter for Test Scripts

When the user sets a filter on the test script source, TestManager calls the following functions, in the order shown below.

Typical Sequence of Function Calls Operation
  1. TTGetFilterEx()

Exposes user interface elements that collect filtering specifications from the user registering the test script source.
  1. TTSetFilterEx()

When a connection is made to the test script source, TestManager passes the filtering specifications obtained from TTGetFilterEx() into the TSCA.
  1. TTGetRoots()

Returns the array of nodes comprising the root elements of the test script source.


Creating a New Test Script

When the user creates a new test script, TestManager calls the following function from the Editor Integration group.

Function Call Operation
TTNew() Enables the tester to create a new test script for this type of test using the hosted tool.


Selecting a Test Script for Operations

Before carrying out any operations on a test script, the user selects the test script from a list of available test scripts in the Test Script view. To display these test scripts, TestManager calls the following functions from the Data Access group, typically in the sequence that follows.

Typical Sequence of Function Calls Operation
  1. TTGetSourceIcon()

Returns the path of the bitmap that represents the test script source.
  1. TTGetRoots()

Returns the array of nodes comprising the roots of the test script source.
  1. TTGetChildren()

Returns an array of nodes that are the children of the specified node. TestManager calls this function for each node returned by TTGetRoots().
  1. TTGetTypeIcon()

Returns the path of the bitmap that represents the test script node.


Editing Test Script Properties

When users want to edit the properties of a test script, they must:

  1. Select the test script from the Test Script view.

  2. Bring up the Test Script Properties dialog box to view and modify the test script properties.

To enable these actions, TestManager calls the following function, which comes from the UI Support group.

Function Call Operation
TTShowProperties() Displays the properties of a selected test script.


Editing Test Script Text

When the user selects operations to edit a test script, TestManager calls TTEdit(), which comes from the Editor Integration group.

Function Call Operation
TTEdit() Displays a test script in the appropriate editor for modification by the user.


Performing Custom Actions on the Test Script or the Test Script Source

You can implement the TSCA to support custom actions on the test script or on the test script source. If the TSCA supports these custom actions, TestManager displays them in a custom menu so that the user can select these actions.

To enable display and execution of custom actions on the test script source, TestManager calls these functions from the Custom Action Execution group, typically in the following sequence.

Typical Sequence of Function Calls Operation
  1. TTGetSourceActions()

Returns a pointer to an array of actions that can be applied to the test script source.
  1. TTExecuteSourceAction()

Executes the specified action against the test script source.

To enable display and execution of custom actions on a test script, TestManager calls these functions from the Custom Action Execution group, typically in the following sequence.

Typical Sequence of Function Calls Operation
  1. TTGetNodeActions()

Returns a pointer to an array of actions that can be applied to the test script.
  1. TTExecuteNodeAction()

Executes the specified action against the test script.


Integrating with Source Control

When the user makes selections in the UI to integrate a test script with source control, TestManager calls the following functions from the TSCA. These functions come from the Source Control group. TestManager typically calls TTGetSourceControlStatus() first and then calls the other functions in an order that corresponds to the order of the user's selections in the UI.

Typical Sequence of Function Calls Operation
  1. TTGetSourceControlStatus()

Returns the current source-control status of the test script.
  1. One of the following:

  2. TTAddToSourceControl()


Adds the appropriate files for the specified test script to source control.
Checks out the appropriate files for the specified test script from source control.
Checks in the appropriate files for the specified test script to source control.
Undoes the checkout of the appropriate files for the specified test script.

prevnext


Rational TestManager Extensibility Reference Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com