Introduction to the Test Input Adapter API

prevnext

About Test Input Adapters


A Test Input Adapter (TIA) is a C or C++ dynamic-link library (DLL) that integrates with TestManager to enable additional test input types to be available for planning test cases. Test cases define what a tester will test, based on this newly defined test input.

Each test input source is associated with a particular TIA. Without a TIA, the user would be unable access a test input through the user interface.


TIA Functionality

A TIA must, at a minimum:

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


Built-In and Custom TIAs

Test inputs consist of any data that the test designer identifies as needing validation. (For more information about built-in test input types, see the Rational TestManager User's Guide.)

TestManager comes with three built-in test input types. Built-in TIAs support these test input types, enabling TestManager to access these test inputs. The built-in test input types are:

If you want TestManager to support a new test input type, you must implement a custom TIA. That is, you can extend the TestManager functionality to support test inputs generated by non-Rational tools. You can define and manage as a test input type any kind of intermediary object needed for testing. Examples are:

Because a TIA must provide connection with the test input source, the following functions are required for building a basic TIA:

In addition, the TIA must provide access to the test inputs in the source by implementing some of the following functions:

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

Some functions work in pairs. For example, because TIConnectEx() is called to make the connection to the test input source, TIDisconnect() must subsequently be called to disconnect from the test input source.

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

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


The TIA Function Calls

The TIA applications programming interface (API) consists of 34 functions that are organized into eight functional groupings.


Functional Groupings of TIA Functions

The Test Input Adapter (TIA) functions are summarized in the following table, which shows:

Notes:

  1. TestManager does not currently call the functions preceded by an asterisk (*).

  2. The following extended function calls supersede the corresponding nonextended calls:

Function Group and Purpose Functions in Group
Connection Supports connection and disconnection from the test input source.
TIConnect()
TIConnectEx()
TIDisconnect()
Data Access Provides access to the source's test inputs:
  • Hierarchical data

  • Nonhierarchical data

  • Sources with different test input types

  • Functions providing icons for source and test inputs

TIGetRoots()
TIGetChildren()
TIGetIsNode()
*TIGetParent()
*TIGetName()
*TIGetType()
*TIGetTypes()
TIGetTypeIcon()
TIGetSourceIcon()

TIGetNeedsValidation()
State Access Provides information about test input states. *TIGetIsParent()
*TIGetIsChild()
*TIGetIsNode()
*TIGetIsModified()
*TIGetIsModifiedSince()
*TIGetModified()
TIGetModifiedSince()
Filtering Provides support to filter out test inputs that do not meet user-defined criteria TISetFilter()
TISetFilterEx()
TIGetFilterEx()
*TISetValidationFilter()
UI Support Provides the ability to create custom user interface components that display the properties of a test input. TIShowProperties()
*TIShowSelectDialog()
Source Configuration Support Provides the ability to produce a custom user interface to aid in configuring the test input source TISetConfiguration()
TIGetConfiguration()
Custom Action Execution Provides the ability to expose custom operations from the TestManager Test Input view TIExecuteSourceAction()
TIExecuteNodeAction()
TIExecuteSourceAction()
TIGetNodeActions()
Miscellaneous Infrastructure Provide infrastructure support *TIGetIsValidSource()
TIGetIsFunctionSupported()


Mapping of User Actions to TIA Function Calls

A TestManager end user may want to carry out various actions on the test input source. Following is a list of common test input operations that the user might perform in the Test Input view. 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 input source.

  2. Opening the Test Input view.

  3. Setting a filter for a test input source.

  4. Selecting a test input from a test input source.

  5. Displaying properties of a test input.

  6. Performing custom actions (if any) on the test input source

Note: Based on the current state of TestManager (including which test-input-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 Input Source

When the user defines or modifies the configuration of a test input source, TestManager calls the following two functions from the Source Configuration group in the order listed below.

Typical Sequence of Function Calls Operation
  1. TIGetConfiguration()

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

When a connection is made to the test input source, TestManager passes the configuration data obtained from the TIGetConfiguration() function into this function.

Note: Test inputs from different sources demonstrate great variability in:

For example, test inputs from a RequisitePro project are relatively stable. TestManager treats all requirements in a RequisitePro test input source as potential test inputs. Therefore, you do not need to write a custom TIA to collect any additional user input.

On the other hand, test inputs from an Excel-based input source tend to be highly variable regarding the test input location (column or row) and the data format, making it undesirable to build a specialized adapter for each possible condition.


Opening the Test Input View

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

Note: TIConnectEx() supersedes TIConnect().

Typical Sequence of Function Calls Operation
  1. TIConnectEx()

Establishes a connection to the test input source.
  1. TIGetSourceIcon()

Returns the path to the bitmap containing the icon that represents the test input source in Test Input view. Note that implementation of this function is optional.


Setting a Filter for a Test Input Source

When the user sets a filter on the test input source, TestManager calls the following functions from the Filtering group in the order listed below.

Typical Sequence of Function Calls Operation
  1. TIGetFilterEx()

Exposes user interface elements that collect filtering specifications from the user. The TIA passes those filtering specifications back to TestManager to be persisted with the Test Input view or test coverage reports.
  1. TISetFilterEx()

When a connection is made to the test input source, TestManager passes into the TIA the filtering specifications obtained from TIGetFilterEx().


Selecting a Test Input from a Test Input Source

Many operations, including associating a test case to a test input, require that the user select a test input from a test input source. To display the contents of a test input source, TestManager calls these functions from the Data Access group, typically in the following sequence:

Typical Sequence of Function Calls Operation
  1. TIGetSourceIcon()

Returns the path to the bitmap that represents the test input source.
  1. TIGetRoots()

Returns the array of nodes comprising the roots of the test input source.
  1. TIGetChildren()

Returns an array of nodes that are the children of the specified node. TestManager calls this function once for each test input returned by the function TIGetRoots().
  1. TIGetTypeIcon()

Returns the path to the bitmap that represents the test input type for each test input added to the view.


Displaying Properties of a Test Input

When the user makes a UI selection to view the properties of a test input, TestManager calls the following function, which comes from the UI Support group.

Function Call Operation
TIShowProperties() Displays the properties of a selected test input.


Performing Custom Actions on the Test Input Source

You can implement the TIA to support custom actions on the test input source. If the TIA supports these custom actions, TestManager displays them in a custom menu so that the user can select them. To enable display and execution of custom actions on the test input source, TestManager calls these functions from the Custom Action Execution group, typically in the following sequence:

Typical Sequence of Function Calls Operation
  1. TIGetSourceActions()

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

Executes the specified action on the test input source.


Performing Custom Actions on a Test Input Node

You can implement the TIA to support custom actions on a test input node. If the TIA supports these custom actions, TestManager displays them in a custom menu so that the user can select them. To enable display and execution of custom actions on the test input node, TestManager calls these functions from the Custom Action Execution group, typically in the following sequence:

Typical Sequence of Function Calls Operation
  1. TIGetNodeActions()

Returns a pointer to an array of actions that can be applied to a node of a particular type.
  1. TIExecuteNodeAction()

Executes the specified action on the specified node.

prevnext


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