Professional Documents
Culture Documents
TestDirector Open Test Architecture Guide, Version 8.0 This manual, and the accompanying software and other documentation, is protected by U.S. and international copyright laws, and may be used only in accordance with the accompanying license agreement. Features of the software, and of other products and services of Mercury Interactive Corporation, may be covered by one or more of the following patents: U.S. Patent Nos. 5,701,139; 5,657,438; 5,511,185; 5,870,559; 5,958,008; 5,974,572; 6,138,157; 6,144,962; 6,205,122; 6,237,006; 6,341,310; 6,360,332, 6,449,739; 6,470,383; 6,477,483; 6,549,944; 6,560,564; and 6,564,342.6,564,342; 6,587,969; 6,631,408; 6,631,411; 6,633,912 and 6,694,288. Other patents pending. All rights reserved. Mercury, Mercury Interactive, the Mercury Interactive logo, LoadRunner, LoadRunner TestCenter, QuickTest Professional, SiteScope, SiteSeer, TestDirector, Topaz and WinRunner are trademarks or registered trademarks of Mercury Interactive Corporation or its subsidiaries, in the United States and/or other countries. The absence of a trademark from this list does not constitute a waiver of Mercury Interactive's intellectual property rights concerning that trademark. All other company, brand and product names are registered trademarks or trademarks of their respective holders. Mercury Interactive Corporation disclaims any responsibility for specifying which marks are owned by which companies or which organizations. Mercury Interactive Corporation 379 North Whisman Road Mountain View, CA 94043 Tel: (650) 603-5200 Toll Free: (800) TEST-911 Customer Support: (877) TEST-HLP Fax: (650) 603-5300 2004 Mercury Interactive Corporation, All rights reserved
If you have any comments or suggestions regarding this document, please send them via e-mail to documentation@mercury.com.
TDOTAG8.0/03
Table of Contents
Welcome to TestDirector Open Test Architecture ...............................v Using This Guide ..................................................................................vi TestDirector Documentation Set..........................................................vi Online Resources .................................................................................vii Documentation Updates ................................................................... viii Typographical Conventions.................................................................ix P A RT I : R E M O T E T E S T E X E C U TI O N Chapter 1: Integrating Custom Testing Tools ......................................3 About Integrating Custom Testing Tools..............................................3 The TestDirector Open Test Architecture .............................................5 The TestType Mechanism .....................................................................8 Chapter 2: Implementing the Testing Tool Integration ....................11 About Implementing Testing Tool Integration ..................................12 Creating Custom Test Types ...............................................................13 TestType COM Class............................................................................13 RemoteAgent DCOM Server ................................................................20 ScriptViewer ActiveX Control .............................................................28 ResultViewer ActiveX Control.............................................................31 ExecConfiguration ActiveX Control ...................................................33 Registering Custom Test Types with TestDirector ..............................35 PA RT II: T E S TD I RE C TO R A PI Chapter 3: Using the TestDirector API ...............................................45 About the TestDirector API .................................................................45 Integrating Your Applications with TestDirector................................46 Accessing TestDirector API Functions .................................................47 Downloading the OTAClient80.dll .....................................................48 How the OTAClient80.dll Communicates with TestDirector.............48 TestDirector API Terminology.............................................................50
iii
Chapter 4: TestDirector Projects Data Structure ...............................51 TestDirector Projects............................................................................51 Table Relationships .............................................................................52 Data Tables ..........................................................................................54 System Tables and Security Tables ......................................................82 Chapter 5: TestDirector API Object Model .........................................97 Object Model Description ...................................................................97 Objects by Category ..........................................................................100 Performance Issues and Pre-fetching ................................................107 Chapter 6: TestDirector API Object Reference .................................109 Object Name......................................................................................110 Object Properties ...............................................................................110 Object Methods .................................................................................111 Object Example .................................................................................112 Special Notation Issues......................................................................113 Alphabetical Reference Table ............................................................114 Base Interfaces ...................................................................................120 Utility Classes ....................................................................................135 Data Objects ......................................................................................195 System and Security Objects .............................................................353 Customization Objects ......................................................................407 Chapter 7: Error Handling.................................................................453 List of Error Codes .............................................................................453 Examples of Error Handling ..............................................................464 Index..................................................................................................465
iv
Note: New API examples are continuously being added to the Knowledge Base on the Mercury Customer Support Web site. To search the TestDirector Knowledge Base for new information, select Using the Open Test Architecture - API from the Topic list.
Part I
Part II
vi
TestDirector Site Administrator Client API Guide explains how to use the Site Administrator Client API to enable your application to organize, manage, and maintain all users, projects, domains, connections, and site configuration parameters. It includes a complete reference of all the Site Administrator Client functions.
Online Resources
TestDirector includes the following online resources: Readme provides last-minute news and information about TestDirector. Books Online displays the complete documentation set in .PDF format. Online books can be read and printed using Adobe Acrobat Reader 5.0 which can be downloaded from the Adobe Web site (http://www.adobe.com/products/acrobat/readstep2.html). TestDirector Online Help provides immediate answers to questions that arise as you work with TestDirector. It describes menu commands and dialog boxes, and shows you how to perform TestDirector tasks. Check Mercury Interactives Customer Support Web site (http://support.mercury.com) for updates to TestDirector help files. Customer Support Online uses your default Web browser to open Mercury Interactives Customer Support Web site. This site enables you to browse the Mercury Support Knowledge Base and add your own articles, post to and search user discussion forums, submit support requests, download patches and updated documentation, and more. The URL for this Web site is http://support.mercury.com. Mercury Interactive on the Web uses your default Web browser to open Mercury Interactives home page. This site provides the most up-to-date information on Mercury Interactive and its products. This includes new application releases, seminars and trade shows, customer support, educational services, and more. The URL for this Web site is http://www.mercury.com.
vii
Documentation Updates
Mercury Interactive is continuously updating its product documentation with new information. You can download the latest version of this document from the Customer Support Web site (http://support.mercury.com). To download updated documentation: 1 In the Customer Support Web site, click the Documentation link. 2 Under Select Product Name, select TestDirector. Note that if TestDirector does not appear in the list, you must add it to your customer profile. Click My Account to update your profile. 3 Click Retrieve. The Documentation page opens and lists the documentation available for the current release and for previous releases. If a document was recently updated, Updated appears next to the document name. 4 Click a document link to download the documentation.
viii
Typographical Conventions
This book uses the following typographical conventions: 1, 2, 3 > Stone Sans Bold numbers indicate steps in a procedure. Bullets indicate options and features. The greater than sign separates menu levels (for example, File > Open). The Stone Sans font indicates names of interface elements in a procedure that you perform actions upon (for example, Click the Run button.). Bold text indicates function and object names. Italic text indicates property and parameter names. The Arial font is used for examples and statements that are to be typed in literally. The Courier New font is used for syntax examples in the object reference. The Courier New italic font is used for comments within examples.
ix
Part I
Remote Test Execution
1
Integrating Custom Testing Tools
You can integrate your custom and third-party testing tools with TestDirector to create tests using these tools. You can then use TestDirector to configure the testing tool(s) you are using, view test scripts created, execute the tests across multiple remote hosts, and view test results. This chapter describes the architecture that enables TestDirector to integrate with custom and third-party testing tools. For information on implementing this integration, see Chapter 2, Implementing the Testing Tool Integration. This chapter describes: The TestDirector Open Test Architecture The Test Types Mechanism
Additionally, you define the conditions that cause each test in the test set to be run. These can be a date and time (time condition), or a condition based on the result of another test (run condition). A typical run condition configures a test to run after another test in the test set has run and passed. By using this condition for all the tests in a test set, the tester can create a batch test in which the tests run in sequence until one of the tests fails, at which point the sequence is terminated. After you design your tests and test sets, you can use TestDirector to remotely execute tests created with third-party testing tools on multiple hosts across a network. After test execution is complete, you can use TestDirectors reports and graphs to analyze test results. You can use customized controls to view the test script and results in a format compatible with the testing tool you are using. You can also add defects discovered during test execution to TestDirectors defect database, and track these defects until they are repaired. For a complete discussion of TestDirectors features and user interface, refer to the TestDirector Users Guide.
The TestDirector physical environment consists of three types of entities: The TestDirector server The TestDirector client The testing application host Note that two, or even all, of these entities can reside on one machine. The server houses the server modules and the TestDirector database. (The physical location of the database may vary, but it is included on the server for simplicity.) The testing tool host houses the testing application and a remote agent module, which enables the client modules on the client machine to control the testing application and obtain the testing status from it. The testing application then uses the TestDirector API (Application Program Interface) to update the TestDirector server database with information regarding the test that is being run and the results of this test. The TestDirector API is COM (Component Object Model)-based, and can be implemented directly through the testing application as an extension to the remote agent module, or through any other custom component. The client houses optional controls that enable the client user to view and set the testing application properties in its own custom format. The client machine and the server can be located anywhere on the Internet. The TestDirector client uses custom controls to access testing detailssuch as the test script and test parametersfrom the TestDirector server. The custom controls are needed to view the testing details in the custom format used by the specific testing application. These components are optional and are downloaded to the client from the server through the mechanism described in Chapter 2, Registering Custom Test Types with TestDirector.
TestDirector uses the testing host remote agent to communicate with testing tools. By using Microsofts DCOM (Distributed Component Object Model) protocol, the remote agent is accessible directly over a network, enabling the testing tool to receive commands from the TestDirector client. For your testing application to receive commands from TestDirector, you must install a remote agent on each host you want to use for running tests. Note that the TestDirector client and testing host machines must be on the same LAN (Local Area Network). When the TestDirector client requests to run a test, it first checks with the appropriate remote agent module that the testing application is ready. The client then sets the test parameters for the requested test through the remote agent and commands the agent to run the test. Once the test is run, the client can query the remote agent for the execution progress and results (for example, success or failure). The testing application can then communicate with the TestDirector server through the TestDirector API interfaces to update the servers database with the test details and results. The ability to run a test through the client on a remote testing host (running a custom or third-party testing application) and obtain the tests results from the server enables you to use the custom or third-party testing tool as you would integrated testing applications.
10
2
Implementing the Testing Tool Integration
To integrate custom and third-party testing tools with TestDirector, you must create a DCOM server and test type add-in for each testing tool, and register the add-in with TestDirector. The DCOM server enables TestDirector to interface with the testing tool on a remote testing host. The test type add-in consists of one or several OCX files that contain information enabling TestDirector to interface with the third-party testing tool information in the TestDirector database. This chapter describes: Creating Custom Test Types TestType COM Class RemoteAgent DCOM server ScriptViewer ActiveX Control ResultViewer ActiveX Control ExecConfiguration ActiveX Control Registering Custom Test Types with TestDirector
11
12
Remote Agent DCOM Server ScriptViewer ActiveX Control ResultViewer ActiveX Control
ExecConfiguration ActiveX Control Configures the testing tool. This component is optional. To use a custom test type, TestDirector creates an object of the TestType COM class, and uses its methods to obtain the user interface properties of the test type, to create the test script template, and to obtain the class ID of the ScriptViewer, ResultViewer, ExecConfiguration ActiveX controls, and RemoteAgent DCOM server.
13
TestType Properties
Simple Data Type Properties
Property Name CanCreateScriptTemplate R/W R Type Long Description Indicates whether the test type supports creating script templates. Returns 0 if the test can not be created; 1 if the test can be created; 2 if the test supports creating script templates. ExecConfigCLSID R String Returns the class ID of the ExecConfiguration class associated with this test type, in the following format: {XXXXXXXX-XXXX-XXXXXXXX-XXXXXXXXXXXX}, where X is a hexadecimal character. If ExecConfiguration is not supported, this property returns an empty string. Returns the most recent error message. Returns the class ID of the RemoteAgent class associated with this test type, in the following format: {XXXXXXXXXXXX-XXXX-XXXXXXXXXXXXXXXX}, where X is a hexadecimal character. If RemoteAgent is not supported, this property returns an empty string.
LastErrorMessage RemoteAgentCLSID
R R
String String
14
R/W R
Type String
Description Returns the class ID of the ResultViewer class associated with this test type, in the following format: {XXXXXXXXXXXX-XXXX-XXXXXXXXXXXXXXXX}, where X is a hexadecimal character. If ResultViewer is not supported, this property returns an empty string. Returns the class ID of the ScriptViewer class associated with this test type, in the following format: {XXXXXXXX-XXXXXXXX-XXXXXXXXXXXXXXXX}, where X is a hexadecimal character. If ScriptViewer is not supported, this property returns an empty string. Returns the name of the testing tool.
ScriptViewerCLSID
String
TestingToolName
String
15
R/W R
Type String
Description If the TestType add-in was compiled with the OTAClient.dll library, the returned value is the TestDirector version with which it was compiledfor example, 8.0. If the add-in is independent of the TestDirector version (that is, using only Variant/IDispatch types for interfacing), the returned value is the string All.
VcsData
String
Returns VCS information. This information will enable TestDirector to save tests of this type in the VCS database. Currently not in use.
TestType Methods
Init Method
Initializes the TestType object. Specifies (through the ITDConnect interface) the server/project to which this object relates. Syntax HRESULT Init(VARIANT TDConnection) Parameters
Parameter Name TDConnection Description Required. A variant containing the IDispatch interface to the TDConnection object. For a description of the TDConnection object, see the TDConnection object description on page 135. Default None
16
CreateScriptTemplate Method
Creates a script template for the specified test. The test type creates a script on the local client machine, and uploads it to the server side test repository. Syntax HRESULT CreateScriptTemplate(long TestKey, BSTR LocalPath, long Value) Parameters
Parameter Name TestKey LocalPath Description Required. The tests key for which the template is created. Input - the path on the local host in which the client wishes to place the script (the path does not have to exist). Output - one of the following two options: Default None None
17
TestType Example
The following example is of the main TestType class. The example is developed step by step with the other remote execution component examples, so that executing all the steps included in this section results in a (simple) working remote test execution mechanism. The example uses Microsoft Visual Basic 6.0. Using Microsoft Visual Basic, create a new Active-X DLL project. Declare the following class members in the code window (global declaration area): Public RemoteAgentCLSID As String Public ScriptViewerCLSID As String Public TestingToolName As String Public ExecConfigCLSID As String Public CanCreateScriptTemplate As Long Public LastErrorMessage As String Public ResultViewerCLSID As String 'RemoteAgent class ID 'ScriptViewer control class ID 'The testing tools name 'ExecConfiguration class ID 'The script template Flag 'The last error message 'ResultViewer control class ID
These members represent the main TestType object properties. Add the following sub-routine to the code: Private Sub Class_Initialize() ExecConfigCLSID = "' RemoteAgentCLSID = "" ScriptViewerCLSID = "" TestingToolName = "Custom DOS Batch file script agent" CanCreateScriptTemplate = False ' no create new test feature LastErrorMessage = "DOS session problems" ResultViewerCLSID = "" End Sub
18
This sub-routine is run when the TestType is loaded. Note that at this time, none of the optional controls is supported, as their class ID strings are empty. Also note that the remote agent class ID is empty, as no such agent yet exists. This example does not support script templates, and has only one error type. In the class properties, change the Instancing property to 6 - GlobalMultiUse. Choose Project > Properties. Click the General tab, and make sure Unattended Execution and Upgrade ActiveX Controls are selected. In the same tab, in the Threading Model section, select the Thread Per Object option and change the projects name to MyTestType. Save the project under this name. Choose File > Make MyTestType.exe to instruct Visual Basic to compile the class and register it. Note that this example is also incorporated in the other examples in this chapter.
19
is_host_ready Method
Before test execution can begin, the TestDirector client asks the remote agent to ensure that the designated testing host is available and ready to run the test using this method. Syntax HRESULT is_host_ready(BSTR descr) Parameters
Parameter Name descr Description Required. Returns a description of the reason the host is not ready. Default None
Return Value Returns S_OK if the testing tool and host are ready to run tests, and S_FALSE otherwise.
20
set_value Method
Before the testing tool can run a test, it must receive information from TestDirector, including the name of the test, the database to which the test belongs, and other test-related information. This information enables the testing tool to retrieve data from the TestDirector database, run tests, and return the test results to TestDirector. This method accepts two parametersthe parameter name to be set and its designated valueand integrates them into the testing tool, so that the testing tool is able to exercise the above operations. Syntax HRESULT set_value (BSTR prm_name, BSTR prm_value) Parameters
Parameter Name Description Required. The name of the parameter to be set. Case insensitive. This method supports the parameter names described in the table below. Required. The value to be set. Case insensitive. Default None
prm_name
prm_value
None
Supported Parameter Names Parameter Name domain_name project_name user_name password TDAPI_host_name Description The name of the TestDirector domain in which test and result information is stored. The name of the TestDirector project in which test and result information is stored. The name of the user running the test. The users password. The name of the host on which the TestDirector server is running.
21
host_name scheduler_version sys_user_name sys_computer_name test_set_id test_path test_id test_name tstest_name test_type test_instance testcycle_id runner_result_dir tester_name responsible plann_status subject test_set_user1...99 test_user1...99
The name of the host on which the remote agent test type is run. The software version number of the scheduler. The login user name for the user logged in on the TestDirector client PC. The name of the PC on which the TestDirector client is running. The ID of the test set to which the test belongs. The full path of the test to be run. The ID of the test to be run. The name of the test to be run. The name of the test to be run with a [1] instance prefix. The custom test type. The ID of the test instance inside a test set. The ID of the test. The name of the test run. The name of the tester assigned to run the test. The name of the user responsible for the project. The planning mode status of the test. The subject folder to which the test belongs in the test plan tree. The value of a user field in the Test Set table. The value of a user field in the Tests table.
22
Return Value Returns S_OK if the call succeeds, and S_FALSE otherwise.
run Method
The run method instructs the testing tool to load and run the test. This function also launches the testing tool if it is not already running. Syntax HRESULT run() Return Value Returns S_OK if the call succeeds, and S_FALSE otherwise.
tdstop Method
The tdstop method instructs the testing tool to terminate the test that is currently running. This method replaces the previously used Stop method. Syntax HRESULT tdstop() Return Value Returns S_OK if the call succeeds, and S_FALSE otherwise.
get_status Method
During test execution, TestDirector checks the status of the testing tool and displays this information. This enables the tester to monitor the tests progress at each stage of the run. This function returns the current status of the testing tool. Syntax HRESULT get_status (BSTR descr, BSTR status)
23
Parameters
Parameter Name descr status Description Required. Returns a verbal description of the testing tools current status. Returns one of the following values as a generic description of the current testing tool status. Default None None
Message The testing tool is currently running another test. The testing tool has reached the end of the current test. The testing tool has failed. The testing tool is in its initialization stage. The testing tool is running the test. The testing tool has paused execution of the current test. The testing tool is ready to run the test. The testing tool has stopped execution of the current test. The test has been successfully completed. Execution of the test failed. You cannot execute the test on the current host. Try to execute the test on another host from the attached host group.
READY STOPPED
24
Return Value Returns S_OK if the testing tool and host are ready to run tests, and S_FALSE otherwise.
RemoteAgent Example
The following is an example of the remote agent class that runs the test. Using Microsoft Visual Basic, create a new Active-X EXE project. Declare the following class members in the code window (global declaration area): Private Status As String Private Descr As String Private ServerName As String Private ProjectName As String Private DomainName As String Private UserName As String Private Password As String Private TestPath As String Private TestName As String Private TestSet As String Private TestID As Integer Private S_OK As Long Private S_FALSE As Long Private END_OF_TEST As Long ' The current testing status ' The current testing description ' The server URL ' The current projects name ' The current domain name ' The current user name ' The current users password ' The current tests path ' The current tests name ' The current test sets name ' The current tests ID ' Return value if the run is OK ' Return value if the run failed ' Return value for end of test
Add the class initialization sub-routine: Private Sub Class_Initialize() S_OK = 0 S_FALSE = 1 END_OF_TEST = 4 End Sub This sub-routine initializes the return value variables. Add the following RemoteAgent interface methods: Public Function is_host_ready(Descr As String) As Long Descr = "Ready"
25
is_host_ready = S_OK End Function The is_host_ready method will always report that the host is ready, and will change the testing description to Running. Public Function set_value(ByVal name As String, ByVal Value As String) As Long Select Case name Case "TDAPI_host_name" ServerName = Value Case "project_name" ProjectName = Value Case "domain_name" DomainName = Value Case "user_name" UserName = Value Case "sys_user_name" SysUserName = Value Case "password" Password = Value Case "test_name" TestName = Value Case "test_path" TestPath = Value Case "test_set" TestSet = Value Case "test_id" TestID = Val(Value) End Select set_value = S_OK End Function The set_value function sets the appropriate variable only. Public Function get_status(descr1 As String, status1 As String) As Long descr1 = Descr status1 = Status get_status = S_OK End Function
26
The get_status function sets the output according to the tests status and description variables. Public Function run() As Long Dim txt As String Status = "RUNNING" Descr = "Running..." Dim rc rc = Shell(TestPath & "\batch.bat") Status = "END_OF_TEST" Descr = "Completed" run = S_OK End Function
' Update testing status ' Update testing description ' Run the application ' Update testing status ' Update testing description
The run function runs the testing application (in this example the Batch.bat DOS script) while updating the test status and description. In the class properties, change the Instancing property to 6 - GlobalMultiUse. Choose Project > Properties. Click the General tab, and make sure Unattended Execution and Upgrade ActiveX Controls are selected. In the same tab, in the Threading Model section, select the Thread Per Object option and change the projects name to MyRunAgent. Save the project under this name. Choose Project > Properties. Click the Component tab and select Remote Server Files. Choose File > Make MyRunAgent.exe to instruct Visual Basic to compile the class and register it. The remote agent is now ready to run. For information on registering and running the remote agent with TestDirector, see Registering Custom Test Types Example on page 38.
27
Init Method
Initializes the ScriptViewer object. Specifies (through the ITDConnect interface) the server/project to which this object relates. Syntax HRESULT Init(VARIANT TDConnection) Parameters
Parameter Name TDConnection Description Required. A variant containing the IDispatch interface to the TDConnection object. For a description of the TDConnection object, see the TDConnection object description on page 135. Default None
ShowTest Method
Displays the specified test script in the Script Viewer control. Syntax HRESULT ShowTest(long TestKey)
28
Parameters
Parameter Name TestKey Description Required. The requested tests ID. Default None
ScriptViewer Example
The following is an example of the script viewer control that allows you to view the test. Using Microsoft Visual Basic, create a new Active-X Control project. Choose Project > References, and select the OTA COM 8.0 Type Library reference. From the standard toolbar, add a list box to the user control. The script contents are displayed inside the list box. Declare the following class members in the code window (global declaration area): Dim td As Variant Dim tfact As TestFactory Dim myt As Test ' The OTA connection class ' The OTA test factory class ' The OTA test class
These objects contain the main TD classes needed by the script viewer. Add the interface methods: Public Sub Init(mytd As Variant) Set td = mytd List1.Clear End Sub ' Initilization method. called by TD ' Clears the list box control
29
The Init method sets the td object to the ITDConnection object passed by the TestDirector client, and clears the list box. Public Sub ShowTest(TestKey As Long) Dim myf As String Dim mydata As String Set tfact = td.TestFactory ' Getting the tests full path Set myt = tfact.Item(TestKey) myf = myt.FullPath & "\batch.bat" ' The script file full path Open myf For Input As #1 ' Opening the batch.bat script file List1.Clear While Not EOF(1) Input #1, mydata ' Reading the script file List1.AddItem (mydata) ' Add each script line to the list control Wend Close #1 ' Closing the file List1.Refresh End Sub The ShowTest method gets the path for the specified test using its key, reads the script file (Batch.bat) from this location, and displays it in the list box. Choose Project > Properties. Click the General tab, and rename the project MyScriptViewer. Save the project under this name. Choose File > Make MyScriptViewer.ocx to instruct Visual Basic to compile the ActiveX control class and register it with Windows. Note that the ScriptViewer control accesses the script path directly from the TestDirector server through the network (which requires a mapped drive from the client to the TestDirector server), and does not download the script to the client through HTTP. You can, however, add the proper TestDirector API code to accomplish this. For information, see TestDirector API Object Reference on page 109 To see the ScriptViewer control at work, you need to register it with TestDirector. For more information, see Registering Custom Test Types Example on page 38.
30
Init Method
Initializes the ResultViewer object. Specifies (through the ITDConnect interface) the server/project to which this object relates. Syntax HRESULT Init([in] VARIANT TDConnection) Parameters
Parameter Name TDConnection Description Required. A variant containing the IDispatch interface to the TDConnection object. For a description of the TDConnection object, see the TDConnection object description on page 135. Default None
ShowResultEx Method
This method displays the result of the specified test instance in a test set in the Result Viewer. This method is an update to the ShowResult method (see below), and supports multiple instances of a test in a test set. Syntax HRESULT ShowResultEx( VARIANT TestSetKey, VARIANT TSTestKey, VARIANT ResultKey)
31
Parameters
Parameter Name TestSetKey TSTestKey ResultKey Description Required. The test sets key. Required. The tests key in the test set. Required. The specific run result key. Default None None None
ShowResult Method
This is an outdated method that is only supported for backward compatibility. The method displays the result of the specified test in the Result Viewer. This methods calling format does not support multiple instances of a specific test in one test set. Syntax HRESULT ShowResult(long TestKey, long TestSetKey, long ResultKey) Parameters
Parameter Name TestKey TestSetKey ResultKey Description Required. The tests key. Required. The test sets key. Required. The test runs result key. Default None None None
32
TestTypeConfiguration
R/W
String
33
ShowExecConfigurationEX Method
This method displays the configuration of the specified test in the specified test set. This method is an update to the ExecConfiguration method (see below), and supports multiple instances of a test in a test set. Syntax HRESULT ShowExecConfigurationEx(VARIANT TestSetKey, VARIANT TSTestKey) Parameters
Parameter Name TestSetKey TSTestKey Description Required. The test sets key. Required. The tests key in the test set. Default None None
34
ShowExecConfiguration Method
This is an outdated method that is supported for backward compatibility. The method displays the configuration of the specified test in the specified test set. This methods calling format does not support multiple instances of a specific test in one test set. Syntax HRESULT ShowExecConfiguration(long TestKey, long TestSetKey) Parameters
Parameter Name TestKey TestSetKey Description Required. The tests key. Required. The test sets key. Default None None
For example: [VAPI-TEST] CLSID={6D3B8D58-B5F5-11D2-9399-0080C837F11F} This file will be downloaded to each client machine, and enables TestDirector to recognize this test type and its controls. Note that on existing clients, you must delete this file from the client so that the client downloads the revised version of this file. In the Common Data section of the file setup_a.ini, specify a default root directory for the file download in the Destination item line. 4 In the setup_a.ini file, in the TestDirector virtual directory, add a section with the following format for each of the files to be downloaded to client machines (that is, the files you added to the Install directory, excluding the test_type.ini file): [file_name] URLName=<URLName> Shortname=<shortname> Description=<description> Register=<register> ProgID=<progID> Version=<version> Checksize=<checksize>
36
The required parameters within the setup_a.ini file are described below:
Parameter URLName Description Mandatory. The location of the source file to be downloaded. Must start with %URL% and continue with the relative location under the main IIS virtual directory. For example: URLName=%URL%\Install\MyFile.xco shortname The options are:
The file name - the file is downloaded to the default destination directory. The file name with the full path - the file is downloaded to the specified directory. The file name with a partial path - the file is downloaded to the specified subdirectory of the default directory.
Note that the file name extension here must be the real/original extension. For example: MyFile.ocx description Optional. A free text description that is displayed during file download. For example: Description=My Test Type Manager register Optional. Relevant only for COM/DCOM servers (EXE,OCX,DLL). There are two possible values: Y - register COM/DCOM server after download. N - do not register COM/DCOM server after download. For example: Register=Y If you omit this item, the default value N is used. progID Optional. Relevant only for COM/DCOM servers (EXE,OCX,DLL). The prog ID (the default string at the registry) for the COM/DCOM server. For example: ProgID=TestType.Class1
37
Parameter version
Description Optional. Relevant only for files that have compiled version information. If there is a COM server on the client machine with the same prog ID and the same version, the file is not downloaded. For example: Version=1.48.9.2089
checksize
Optional. Relevant only if the ProgID and Version items are omitted. The file size in bytes. If there is a file with the same name and size in the destination directory, the file is not downloaded. For example: CheckSize=4589
These parameters download the control files to the client machine. This is done for every custom control file needed for this test type.
RemoteAgentCLSID and ScriptViewerCLSID variables. The result is (with different class ID strings, according to what you found using Regedit): .................... RemoteAgentCLSID = "{7840C2FC-7F9A-4330-8F8C-EBC0811FF288}" ScriptViewerCLSID = "{99BEBD66-58CD-4C83-8164-4BAF964776C5}" ....................... After changing this, recompile the MyTestType project by choosing File > Make MyTestType.exe from the menu bar. Save the project. Registering MyTestType with test_type.ini To register MyTestType with test_type.ini, you need to find the registered class ID of the MyTestType class. Run Regedit again. Search for MyTestType and write down its class ID. Then go to the test_types.ini file in the Install directory, under the TestDirector virtual directory on the server, and add the following lines: [My-TEST] CLSID={XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} where you replace the {XXX......} part with the class ID string you found using Regedit. Save the file. This file is downloaded to every registered client connecting to the server. You must delete this file from existing clients, so that it can be reloaded to these clients in its revised form. Downloading the Files to the Client Copy the three example files (MyTestType.exe, MyRunAgent.exe and MyscriptViewer.ocx) to the Install directory, under the TestDirector virtual directory on the server (typically, the TDBin\Install folder). Then rename their extension to .xxx for EXE files and .xco for the OCX file. Open the setup_a.ini file in the TestDirector virtual directory on the server (typically, the TDBin folder). Note that this is a list of files to be downloaded to the client (including the test_type.ini file), numbered [File_1], [File_2], and so forth.
39
Note the last number, and copy the information in these files to your file, continuing the numbering: [File_13] Register=Y URLName=%URL%/Install/MyScriptViewer.xco ShortName=MyScriptViewer.ocx Description=My Script Viewer ProgID=MyScriptViewer.UserControl1 Version=[the version is a sub key in the registry from within the class id] [File_14] Register=Y URLName=%URL%/Install/MyTestType.xxx ShortName=MyTestType.exe Description=DOS Batch Test Type ProgID=MyTestType.Class1 Version=[the version is a sub key in the registry from within the class id] [File_15] Register=Y URLName=%URL%/Install/MyRunAgent.xxx ShortName=MyRunAgent.exe Description=My Remote Run agent ProgID=MyRunagent.Class1 Version=[the version is a sub key in the registry from within the class id] Again, note that you will probably have to change the [File_13]....[File_15] numbering. Save the file.
40
Testing With MyTestType The example custom test type is now ready for use. First, delete the test_type.ini file from the TestDirector client directory (typically the E:\Program Files\Common Files\Mercury Interactive\TD2000_80 directory), if you have not yet done so. Then open the TestDirector client and choose TestDirector. The download progress bars are displayed, indicating that the new modules are being loaded. Click the Customize button on the login page (in the upper right corner), and log in as the administrator. Click the Customize Project Entities link to open the Customize Project Entities dialog box. In the Project Entities list, expand the Test entity, expand the System Fields folder under it, and select Type. Click the Goto List button to open the Customize Project Lists dialog box. Click the New Item button, and type the name My-TEST to add it to the list of test types. Close the Project Lists dialog box, and click OK to close the Customize Project Entities dialog box. Log out of the Project Customization window. The My-TEST type is added to the test type options. Log in to the TestDirector client. In the Test Plan module in the test plan tree, create a new WinRunner (WR-AUTOMATED) test. In the Test Grid view, find the test you just added (it should appear at the bottom of the grid) and change its Type field value to My-TEST. Note that the icon to the left of the test name, indicating the test type, changes to a question mark (the default). Write down the Path field value of the test. Log out of the TestDirector client for the change to take effect. As this example does not include a script creation method, you need to write the script manually. Go to the local TestDirector client folder, and open the sub-folder with your project name. Once there, open the Tests folder, and look for the folder with the same name as the Path you wrote down above. Open this folder. Create a batch file named Batch.bat in this folder, and type the following as its contents: echo *****test***** ping localhost pause This file will simulate a testing script.
41
Log in to the TestDirector client. In the Test Plan module in the test plan tree, select the test you added. Click the Test Script tab to display the tests text inside the MyScriptViewer control you created earlier. In the Test Lab module, select and add your test. Run the test on your host. A minimized console window opens, the script commands are run, and the status field of the test is updated to Completed.
42
Part II
TestDirector API
44
3
Using the TestDirector API
The TestDirector application program interface (API) enables you to extend TestDirector functionality to your testing and reporting applications. Your applications can communicate with any TestDirector project and create, retrieve, and update project contents. This chapter describes: Integrating Your Applications with TestDirector Accessing TestDirector API Functions How the OTAClient80.dll Communicates with TestDirector Downloading the OTAClient80.dll TestDirector API Terminology
45
from external applications to a project, and exporting information from a project to an external application. The following chapters explain how to integrate external applications so that they can access and process information contained in projects.
46
47
48
49
50
4
TestDirector Projects Data Structure
To fully utilize the TestDirector API to integrate external applications with TestDirector, you must understand the database design of the TestDirector project and its entities. The following sections explain the tables and fields that comprise the TestDirector project. This chapter describes: TestDirector Projects Table Relationships Data Tables System Tables and Security Tables
Note: It is not recommended to directly modify the TestDirector projects database back end. You should only modify the database back end using the TestDirector API.
TestDirector Projects
This chapter describes the tables that comprise a TestDirector project and how these tables relate to one another. You can view each table and the fields it contains using the Site Administrator. For more information about viewing project tables using the Site Administrator, refer to the TestDirector Administrators Guide. Each TestDirector project contains three types of tables: data tables, system tables, and security tables.
51
Data tables contain data entered by the users of the project at all stages of the testing process. For example, there are data tables that contain tests (Test table), test execution data (Run table), and defect information (Bug table). The TestDirector API focuses mainly on these tables, to which most of this chapter refers. System tables contain information used internally by TestDirector. For example, there are system tables that contain information about fields in the project (System_Field table), the conditions under which defect reports are mailed to users (Mailcond table), and the host servers to which TestDirector is connected (Hosts table). Security tables contain information used for generating, assigning, and controlling permissions within the project. For example, there are tables that control the actions that a user can perform (Actions table), the tables that a user can access and modify (Tables table), and the fields that the user can modify within the table (System_field table).
Table Relationships
The following diagram shows the relationship between the main data tables in a project, displaying their relevant fields. For clarity, the diagram is organized according to the TestDirector client entities.
Note: This is a partial description of the database and the relationships within it. The database does not contain actual foreign keys.
52
53
Data Tables
Data tables contain data entered by project users at all stages of the testing process. For example, the Test table lists each test and its name, ID, and type. Users can access this information through the main TestDirector window or through external applications that interface with the project, such as WinRunner. TestDirector projects include the following data tables:
Table Req Req_Cover Test Dessteps Cycle Testcycl Related Entity Requirements Requirements Tests Design Steps Test Sets Test Sets Description Contains information about testing requirements. Matches testing requirements to the tests and steps that cover them. Contains a list of all tests in TestDirector. Contains information about design steps that are part of a planned test. Contains a list of all test sets in TestDirector. Matches tests to test sets. Enables multiple instances of a single planned test within one test set. Contains information about test executions. Contains information about test step executions within a test execution. Contains information about all the defects recorded in the project. Matches defect records to tokens used to search for similar defects. Contains tokens used to enable automated searching for similar defects. Manages all files and URLs attached to any project entity. Contains record change information for the project entities.
Test Execution Test Step Execution Defects Defects Defects Attachments History
54
Table All_Lists
Description Contains the test plan tree with which the tests are associated. Also has a different role as a system table. Contains manual tests run parameters and their optional values. Contains automatic generated alerts for data objects and user-defined follow-ups for data objects. Contains the test lab tree with which the test sets are associated. Contains traceability identification rules which activate/deactivate rules and enable e-mail notifications.
Step_Params Alerts
Cycl_Fold Rules
You can customize a TestDirector project by adding user-defined fields. If you are using Oracle or Microsoft SQL Server databases, you can add up to 99 user-defined fields and 3 memo fields to each TestDirector entity. If you are using Microsoft Access or Sybase databases, see the following table:
Maximum Number of User-Defined Fields for Microsoft Access or Sybase Databases 24 24 6 6 24 12 6 24
55
Note: The maximum field size is 255 characters for Oracle or SQL Server databases and 40 characters for Sybase and Microsoft Access databases.
RQ_ISTEMPLATE
RQ_REQ_COMMENT
56
Description Indicates whether or not the User responsible for the project has reviewed the requirement. The requirement path in the requirements hierarchy. The aggregated status of previous runs of tests in the requirement coverage. Indicates whether a test that covers the requirement fails. Possible values of this field: No Run, Failed, Passed, Not Completed, N/A. Additional user-defined values may be added to this field by the user.
RQ_REQ_PRIORITY
The requirement priority level. Possible values: 1-Low, 2-Medium, 3-High, 4-Very High, 5-Urgent.
The requirement type (that is, system or functional). The product for which the requirement is designed. The name assigned to the requirement by the tester that designed the requirement. The user that designed the requirement. A number indicating the revision number of this requirement. Increases each time a change is made. Indicates whether the requirement has any attachments. The value of this field can be either Y or N. The date the requirement was added to the project. The time the requirement was added to the project. The number of requirements that have this requirement as a father requirement (have their RQ_FATHER_ID field set to this requirements ID). Indicates if this requirement has folder-like behavior. Contains either Y or N. The version time stamp. Indicates the time this record was last changed.
RQ_IS_FOLDER RQ_VTS
57
Field RQ_USER_01...102
Description You can add user-defined fields to customize the table (see page 55 for the maximum allowable number). You can also add up to 3 memo fields. For future use.
RQ_TASK_STATUS
58
59
Description Indicates the execution status of the test. Possible values: Not Completed, No Run, Passed, N/A, Failed. Indicates that this test is a test template. The value of this field can be either Y or N. Not in use. The version time stamp. Indicates the time this record was last changed. The last checked-in version of the test. Used by the Version Control engine. For future use.
60
Field DS_USER_01...102
Description You can add user-defined fields to customize the table (see page 55 for the maximum allowable number). You can also add up to 3 memo fields. Indicates whether the design step has any attachments. The value of this field can be either Y or N. Contains the ID of a test to be run when this design step is executed. If no ID is present, no test will be run. Indicates whether this design step has parameters associated with it. This field can be either Y or N.
61
CY_EXEC_EVENT_HANDLE
CY_MAIL_SETTINGS
CY_USER_01..102
CY_VTS
62
Description The ID of the folder containing test sets. For future use.
TC_CYCLE TC_TEST_INSTANCE
TC_TEST_ORDER TC_STATUS
63
Field TC_ACTUAL_TESTER TC_EXEC_DATE TC_EXEC_TIME TC_PLAN_ SCHEDULING_DATE TC_PLAN_ SCHEDULING_TIME TC_HOST_NAME TC_EPARAMS TC_ATTACHMENT
Description The name of the user that is actually executing the test. The date on which the test was last executed. The time at which the test was last executed. The date on which the tester plans to next run the test. The time at which the tester plans to next run the test. The name or IP address of the host server on which the test will be executed. This field holds the testing tool configuration string, created by the testing tool itself. Indicates whether the test instance has any attachments. The value of this field can be either Y or N. You can add user-defined fields to customize the table (see page 55 for the maximum allowable number). You can also add up to 3 memo fields. The current test version. A number indicating the revision number of this record. Increases each time a change is made. This field contains actions to be executed in reaction to various execution events during the test set run. This field is in proprietary format. The version time stamp. Indicates the time this record was last changed. For future use.
TC_USER_01...102
64
RN_TEST_ID
65
Field RN_PATH
Description The directory path of the test run or a string in the form a_b where a is the RN_CYCLE_ID field and b is the RN_RUN_ID field. You can add user-defined fields to customize the table (see page 55 for the maximum allowable number). You can also add up to 3 memo fields. The version of the application being tested. Indicates whether the run has any attachments. The value of this field can be either Y or N. The revision number of this record. Increases each time a change is made. The version time stamp. Indicates the time at which this record was last changed. For future use. The number of the test instance being run. This is defined in the Testcycl table TC_TEST_INSTANCE field. The name of the operating system on which the test run is running. The current service pack to which the operating system is updated. The current operating system build number. The name of the User that locked the test. Used by the Version Control engine. The version control status of the test instance during execution. This field value can be one of the following: CHECKEDOUT, CHECKEDIN or GETTED. The test instance version during execution. Not in use. Not in use.
RN_USER_01...102
66
ST_STEP_ORDER ST_DESSTEP_ID
67
Description Indicates whether the step has any attachments. The value of this field can be either Y or N. The test ID to which this step belongs. The ID of the design step on which the test step is based. This is defined in the Dessteps tables DS_STEP_ID field.
BG_BUG_ID BG_STATUS
68
Description Comments about the defect by the developer responsible for the defect. Indicates whether the tester was able to reproduce the defect. The severity level of the defect. Possible values: 1Low, 2-Medium, 3-High, 4-Very High, 5-Urgent. The priority level of the defect. Possible values: 1Low, 2-Medium, 3-High, 4-Very High, 5-Urgent. The name of the tester that found the defect. The ID of the test in which the defect was found. This is defined in the Test table TS_TEST_ID field. The name of the test set in which the defect was found. This is defined in the Cycle table CY_CYCLE field. The index of the test run in which the defect was found. This is defined in the Run table RN_RUN_ID field. The ID of the test run step in which the defect was found. This is defined in the Step table ST_STEP_ID field. The date the defect was found. The version in which the defect was detected. The version in which the developer estimates the defect will be closed. The number of days the developer estimates will be required to fix the defect. The number of days taken to fix the defect. The date the defect record was closed. The version in which the defect record was closed.
BG_RUN_REFERENCE
BG_STEP_REFERENCE
69
Description Indicates whether a defect report should be mailed to users registered to receive such reports. Indicates whether the defect record has any attachments. The value of this field can be either Y or N. You can add user-defined fields to customize the table (see page 55 for the maximum allowable number). You can also add up to 3 memo fields. Not in use. A number indicating the revision number of this record. Increases each time a change is made. For backward compatibility. The version time stamp. Indicates the time this record was last changed. For future use.
BG_USER_01...102
70
71
72
CR_OLE_IND CR_REF_TYPE
CR_DESCRIPTION CR_VC_CUR_VER
73
Note: Not all changes made to a project entity are logged in the History table. Only changes made to specific, pre-defined fields are logged.
74
75
Field AL_SYSTEM
Description The type of list item. This can be one of the following: R - read-only but can add sub-folders. S - system field (TestDirector does not permit changes to this field). A - all actions are available. C - can change but not delete.
The list item path in the lists hierarchy. The order of the child item in the specified node. A comment field. Indicates whether the record has any attachments. The value of this field can be either Y or N. The version time stamp. Indicates the time this record was last changed.
76
Description The ID of the test that was executed by the run. For Run entities only. Not in use. Not in use. The number of steps in which this parameter is used. For Test entities only. Not in use. Not in use. Not in use.
77
78
Field AT_KEY1
Description The field to which the actual alert refers. The information in this field is the first primary key of the table referenced by the alert: Bug table - BG_BUG_ID, Test table - TS_TEST_ID, Testcycl table - TC_CYCLE_ID
AT_KEY2
The field that contains the primary key data of the Testcycl table: TC_TEST_ID. If the Bug table or Test table is selected, than this field is not used and the value is -1. The string representation of the next primary key of the Testcycl table: TC_TEST_INSTANCE. If the Bug table or Test Table is selected, than this field is not used and the value is -1. A description of the alert. The date the alert was sent by the system or the follow-up was configured to be sent. Indicates that the follow-up was sent via e-mail. The value of this field can be either Y or N. The type of alert created. Possible values are: 0 - Automatic, 1 - Follow-up.
AT_KEY3
AT_ALERT_STATUS
The status of the alert sent. Possible values are: 0 -Unread, 1 -Read.
79
80
Description For internal use. A description of the rule. Indicates if the alert should be sent via e-mail. The value of this field can be either Y or N. Indicates if the rule is active. The value of this field can be either Y or N. For future use.
81
82
Description Version control locking management. Shadow tables for version control. Represents as tables beginning with VC_.
Security tables contain information used for generating, assigning, and controlling access permission. For example, the Actions table defines the actions that users can perform, the Tables table defines the tables that users can access and modify, and the Transition Rules table defines the values that users can modify within tables. TestDirector includes the following security tables:
Table System_Field Actions Subject Fields Actions Description Contains information about all project fields, including access permissions. Lists all TestDirector actions and the types of access permissions associated with each action. Lists TestDirector tables and the types of access permission associated with each table. Enables control over user group module access.
Tables
Tables
Modules
83
SF_IS_BY_CODE SF_IS_REQUIRED
84
Field SF_GRANT_MODIFY
Description Grants permission for the users in a user group to modify the field. This is a 32-bit mask that indicates whether the modify action is granted to a specific group. If bit X in this mask is assigned the number 1, the modify action is granted to all users in group X. Indicates whether transition logic exists for the field. The field user column type. Indicates whether the field stores its last value. Indicates whether the field is shown in the customization user interface. Indicates whether the user can change the permission status of the field. Indicates whether the field can be modified only by the owner of the entity. The field size. Reserved for future use. Reserved for future use. Indicates whether there can be a summation of field contents for analysis. The value of this field can be either Y or N. Used for data fields only. Indicates whether this field is under version control. The value of this field can be either Y or N. Used for test fields only.
SF_IS_TRANSITION_ LOGIC SF_USER_COLUMN_ TYPE SF_IS_KEEP_VALUE SF_IS_CUSTOMIZABLE SF_CAN_CHANGE_ PERMISSIONS SF_OWNER_SENSIBLE SF_FIELD_SIZE SF_IS_VISIBLE_IN_NEW_ BUG SF_IS_VISIBLE_FOR_ GROUPS SF_IS_TO_SUM
SF_IS_UNDER_VCS
85
GH_DESCRIPTION
86
87
88
Description The users address. The users telephone number. The users full name.
The constant names supported by TestDirector 8.0: Constant Name bug_file checkout_directory CustSysFields Description Used by RDR. The relative path of the version control checkout directory. If this constant is Y, the system fields labels are customizable (not relevant for TestDirector 8.0). The path where the projects related files reside. If the value is not empty, it is used instead of the directory path that was defined for the project using the Site Administrator. Same as CustSysFields for custom reports (applies to version 6.x only). The relative path where the test details and scripts are located. For future use.
db_directory
89
VcsDb_directory version
The relative path where the version control database resides. The current TestDirector version number.
90
project administrator can specify that a group can change the status of a defect from Fixed to Closed. The table contains the following fields:
Field TR_TABLE_NAME TR_FIELD_NAME TR_GROUP_ID Description The name of the table in which the field resides. The name of the field for which the transition rule has been defined. The ID of the group to which the transition rule has been assigned. This is defined in the Group table GR_GROUP_ID field. The transition rule to be performed on the field.
TR_RULES
91
Description The reference ID of the locked object. For a TEST this is the test ID. You can add user-defined fields to customize the table (see page 55 for the maximum allowable number). You can also add up to 3 memo fields.
92
93
Field AC_GRANT_MASK
Description The user groups that have permission to perform the action. This is a 32-bit mask that indicates whether permission to perform the action has been granted to a specific group. If bit X in this mask is set to 1, group X has permission to perform the action. The action owners sensibility mask. The name of the table on which the action is performed. Indicates whether the Columns dialog box can be opened or closed from this table. This field can be set to either Y or N. Indicates whether the action is an internal system action.
TB_GRANT_MODIFY
94
Field TB_GRANT_ADD
Description Grants permission for the users in a user group to add a record to a table. This is a 32-bit mask that indicates whether the action is granted to a specific group. If bit X in this mask is assigned the number 1, the add action is granted to all Users in group X. Specifies whether records in the table can only be deleted by their owners. Specifies whether records in the table can only be modified by their owners. The column in the table representing the owner of the record.
95
96
5
TestDirector API Object Model
This chapter describes the TestDirector API object model. For a full listing and description of each object, see Chapter 6, TestDirector API Object Reference. This chapter includes: Object Model Description Objects by Category Performance Issues and Pre-fetching
97
98
As mentioned above, most objects are created from factory objects. The factory object inheritance hierarchy is illustrated in the following diagram.
The most important objects created through the above creation mechanism are the actual data entity objects. The main data interface hierarchy is illustrated in the following diagram.
99
Objects by Category
This section lists the TestDirector objects according to the following categories: Base Interfaces Utility Classes Data Objects System and Security Objects Customization Objects A brief description of each object is included within each category. For a detailed description of each object, see Chapter 6, TestDirector API Object Reference.
Base Interfaces
The following base interfaces are implemented by the data entities and factory classes. They encapsulate the basic behavior of a data entity and factory within the context of TestDirector. Interface IBaseField IBaseFieldEx Description Represents a basic data field/entity, such as an attachment. This interface enhances the IBaseField interface to support entities that have attachments associated with them, or history tracking. This interface is descended from IBaseFieldEx, and adds the ability to mail users during events concerning this entity. This interface supports basic factory behaviors, such as adding and removing items. This interface enhances the IBaseFactory interface to support mailing.
IBaseFieldExMail
IBaseFactory
IBaseFactoryEx
100
IAlertable
This interface provides auto-generated alerts that allow the user to receive notifications in the event of changes to the TestDirector objects.
Utility Classes
This category includes interfaces and classes that are used by TestDirector classes to utilize resources such as file storage, database filters, and lists. Object TDConnection Description Responsible for establishing and terminating project sessions. All other objects are created through this object. Represents a database command. Represents the entire set of records resulting from an executed command. Contains folder or file information, such as name, size, and type. Creates a list of field objects without any SQL knowledge. Represents a project field. Contains additional information for any given database field. Creates and maintains lists for any given factory object. Creates a list of field objects without any SQL knowledge. This is a descendent of IList. Downloads a storage structure to the client system. Manages the follow-ups which are userdefined and configured to activate on the date chosen by the user.
Command Recordset FileData TDFilter TDField FieldProperty List FactoryList ExtendedStorage FollowupManager
101
AlertManager
Manages the alerts related to the Bug, Test and TSTest objects.
Data Objects
The following objects deal with the data elements of a project, such as tests, runs, and attachments. Object AttachmentFactory Description Manages attachments. AttachmentFactory objects are created through SubjectNode objects. Represents a single attachment in a project. Manages project requirements. Represents a project requirement. Manages tests. Represents a planning test. Represents the execution status of the test that is currently running. Manages design steps. Represents a single design step in a test. Manages test sets. Represents a test set.
Attachment ReqFactory Req TestFactory Test TestExecStatus DesignStepFactory DesignStep TestSetFactory TestSet
ExecEventNotifyByMailSettings Represents an email notification. ExecSettings ExecEventActionParams Represents an execution of a test set. Represents actions taken after completion of a test set.
ExecEventRestartActionParams Represents actions taken during a restart after completion of a test set.
102
ConditionFactory Condition TestSetFolder TestSetTreeManager TSTestFactory TSTest RunFactory Run StepFactory Step StepParams BugFactory Bug Graph
Manages conditions. ConditionFactory objects are created through TestSet objects. Represents a condition for test execution. Manages test and test sets in a particular folder. Manages the test set tree and its related test set folders. Manages execution tests. Represents an execution test. Manages test runs. RunFactory objects are created through TSTest objects. Represents the result of a test run. Manages test run steps. StepFactory objects are created through Run objects. Represents a step in a test run. Manages test parameters. Manages defect records. Represents a project defect record. Represents a defect-tracking graph. Graph objects are created through BugFactory and TestFactory objects. Retrieves history records for specified field objects. Represents a single history record. Manages project alerts and follow-ups.
103
HostGroup VCS VersionItem TreeManager SysTreeNode SubjectNode Settings ActionPermission TSScheduler ExecutionStatus ExecEventInfo Rule CacheMgr
104
ActionPermission
Customization Objects
The following objects are used to perform administrative customization tasks, such as adding users to user groups, configuring access privileges, and defining user-defined fields. Object Customization Description Responsible for loading customization data from the server and posting customization changes to the database. Holds a collection of all CustomizationAction objects in the project. Determines which user groups can perform the type of action represented by the object. Holds a collection of all CustomizationField objects in the project. Represents a user-defined field. Holds a collection of all CustomizationList objects in the TestDirector project. Represents a user list in a TestDirector project. Represents a node in a user list. Defines the ability of user groups to add, remove, and modify TestDirector entities, such as defect reports and tests.
CustomizationTransitionRules Gathers a collection of transition rules and applies them to a specific field and user group. CustomizationTransitionRule Represents a single transition rule.
105
CustomizationUsersGroups Holds a collection of all CustomizationUsersGroup objects in the project. CustomizationUsersGroup Represents a user group for purposes of adding and removing users to and from the user group. Holds a collection of all CustomizationUser objects in the project. Represents a user when adding and removing the user to and from user groups.
CustomizationUsers CustomizationUser
CustomizationMailConditions Handles the CustomizationMailCondition objects. CustomizationMailCondition Represents a customization mail condition in a TestDirector project. CustomizationModules Handles the customization modules in the project.
106
For example, when you create a Test object (using the Test property of the TestFactory object), only three Test object fields contain values: Test Name, Test ID, and Test Type. To obtain the value of the Test Status field, you must request this field through the network. When you do this, all remaining non-BLOB field values are retrieved as well. However, to obtain the value of the Test Description field, you must make an additional request through the network, since Test Description is a BLOB field.
107
108
6
TestDirector API Object Reference
This chapter describes the TestDirector API objects by category. For the category listing, see Chapter 5, TestDirector API Object Model. For each object, this chapter describes: the object and its purpose the object properties the object methods In addition, many object descriptions include one or more Visual Basic examples showing how the object is used. These examples can be adapted for use in Visual C++. This chapter includes the following sections: Pages 110 through 112 provide an example of the format used for each object description. Pages 113 through 114 describe special notations used in the object descriptions. The object reference begins on page 114. The reference begins with a table that lists all the objects alphabetically and the page on which each object description can be found.
109
Object Name
Interfaces Implemented by the Object (inherited interfaces for interfaces) Describes the object and what it does.
Object Properties
Lists all the properties of the object. The object properties are organized into the following 3 categories: Collection (List) Properties - Properties that return a collection or list of items. For example, the object property ProjectsList returns a list of all available TestDirector projects on the TestDirector server. Object Properties - Properties that implement the interface IDispatch to call another object. For example, the object property ActionPermission returns a reference to an ActionPermission object.
Note: A factory object is an object that exists to manufacture other objects of a specific class.When you use a factory object to manufacture a new object, the factory object does not keep the created object. It only creates the object and passes you the interface. You are responsible for freeing the object when you are finished with it.
Simple Data Type Properties - Properties that set or return a data value such as a boolean, integer, or data string. For example, the TDConnection property Connected returns a boolean value to indicate whether a TestDirector server connection is initialized. For each category, a table appears listing all of the properties in that category, including the property name, description, what it does, and an indication of whether the property is read-only (R), write-only (W), or both read and write (R/W). For Simple Data Type Properties, an additional column indicates the type of data returned by the property (boolean, date, integer, long, or string).
110
Object Methods
Lists each method in alphabetical order. Each method is described in the following format:
Method Name
Describes the method and what it does. Syntax The syntax of the object and method. For example, the TDConnection method ConnectProject has the following syntax: ConnectProject ( BSTR ProjectName, BSTR UserName, [BSTR Password] ) In this example, ConnectProject includes the parameters ProjectName, UserName, and Password. Parameters surrounded by square brackets are optional parameters (Password in the example). Parameters without square brackets are required parameters (ProjectName and UserName in the example). The three parameters are of the BSTR (string) type. Parameters Includes a table listing the method parameters. For each parameter, the table includes the parameter name, description, and default value (if any). A default value of None indicates that a value must be explicitly given unless the parameter is optional. A value of indicates a null value for a string parameter. Returns Lists the possible return values for the method. Note that this section refers to values returned through parameters, and not to the HRESULT value returned by all the interfaces methods.
111
Note: When specifying the properties and methods of an object/interface that inherits/implements an interface that is not fully documented here, the properties and methods of this interface will be detailed separately within the object description.
Object Example
Many object descriptions include one or more Visual Basic examples of the object use. You can adapt these examples for use in Visual C++. To run these examples in Visual Basic: 1 From your TestDirector installation, select Project > References. A list of all TestDirector COM libraries is displayed. 2 Select OTA COM 8.0 Type Library. All TestDirector COM objects are located in this library. To run these examples in Visual C++: Include the full path of the location of the OTAClient80.dll file. This file is located in the bin directory of your TestDirector installation. For example:
#import "c:\Program Files\Common Files\Mercury Interactive\ TDAPIClient\OTAClient80.dll"
This creates the following two files in the build path: TDClient.tlh TDClient.tli These files act as C++ header files. For further information, refer to: http://msdn.microsoft.com/library/ and Visual Studio 6.0 Documentation/Visual C++ Documentation.
112
Note: New open test architecture examples are constantly being added to the Knowledge Base on Mercury Interactive Customer Support Web site. To search the TestDirector Knowledge Base for new information, select Using the Open Test Architecture - API from the Topic list.
The Property or Method Name column lists the properties or methods in the inherited interface with variant parameters. The Parameter Name column lists the variant parameters. The Variation column describes the parameter variant value as used with the specific object.
113
Array Indexes
When the parameter value is an array, each item in the array is preceded by its array index. For example:
This parameter identifies the item by an array consisting of the following elements: (0) Name - The name of the item (string, required). (1) Type - The item type (long, optional). (2) Description - A description of the item (string, optional).
Integer Values
When a text item has an integer value, the integer is placed in brackets after the item description. For example: TDOLE_LONG [1] TDOLE_ULONG [2] TDOLE_FLOAT [3]
114
Description Manages defect records. Manages the system cache. Represents a database command. Represents a condition for test execution. Manages conditions. Responsible for loading and posting customization details from and to the server. Determines whether a certain users group can preform a certain action. Handles the CustomizationAction objects. Represents a user-defined field. Handles the CustomizationField objects. Represents a user list. Represents a node in a user list. Handles the CustomizationList objects. Represents a customized module in the TestDirector project. Represents action permissions for users groups. Represents a single transition rule. Gathers a collection of transition rules, and applies them to a specific field and user group.
CustomizationAction CustomizationActions CustomizationField CustomizationFields CustomizationList CustomizationListNode CustomizationLists CustomizationModules CustomizationPermissions CustomizationTransitionRule CustomizationTransitionRules
412 411 419 416 426 428 424 451 432 439 435
115
Object CustomizationUser
Description Represents a user for the proposes of adding and removing the user to /from a users group. Handles the CustomizationUser objects. Represents a users group for the proposes of adding and removing the user to/from the group. Handles the CustomizationUsersGroup objects. Represents a single design step in a test. Manages design steps. Represents actions taken after completion of a test set. Returns execution information for events in particular test sets. Represents actions during a restart after completion of a test set. Represents an execution of a test set. Represents the execution status of the scheduler. Handles storage operations on the server and the client. Creates and maintains lists for factory objects. Contains properties for field objects. Contains folder or file information. Manages single object follow-ups. Represents a defect graph.
Page 448
CustomizationUsers CustomizationUsersGroup
445 442
CustomizationUsersGroups DesignStep DesignStepFactory ExecEventActionParams ExecEventInfo ExecEventRestartActionParams ExecSettings ExecutionStatus ExtendedStorage FactoryList FieldProperty FileData FollowUpManager Graph
399
116
Object History HistoryRecord Host HostFactory HostGroup HostGroupFactory IAlert IAlertable IBaseFactory IBaseFactoryEx IBaseField IBaseFieldEx
Description Retrieves history records for field objects. Represents a single history record. Represents a single host server. Manages host servers. Represents a group of hosts. Manages host groups. Represents a single alert. Manages single object alert. Supports basic factory behaviors, such as adding and removing items. Enhances the IBaseFactory interface to support mailing. Represents a basic data field/entity, such as an attachment. Enhances the IBaseField interface to support entities that have attachments associated with them, or history tracking. Adds the ability to mail users during events concerning this entity. Creates and maintains object lists. Represents a set of retrieved records. Represents a project requirement. Manages requirements. Manages Rules of project. Represents a result of a test run. Manages test runs.
Page 347 350 356 353 362 359 351 132 126 130 120 123
117
Object Settings Step StepFactory StepParams SubjectNode SysTreeNode TDConnection TDField TDFilter Test TestExecStatus TestFactory TestSet TestSetFolder TestSetFactory TestSetTreeManager TreeManager TSScheduler
Description Represents user settings saved on the server. Represents a step in a test run. Manages test run steps. Manages test parameters. Represents a subject folder in the subject tree. Represents a node in the system tree. Responsible for establishing and terminating project sessions. Represents a project field. Represents a filter for data objects. Represents a planning test. Represents the execution status of the current test. Manages tests. Represents a group of tests. Represents a test set. Manages test sets. Represents the TestDirector test set folders tree. Represents the TestDirector system tree. Responsible for executing selected automated tests. (Valid for tests in TD 7.5 or later). Represents an execution test. Manages execution tests.
Page 390 322 318 325 384 377 135 170 166 246 252 233 275 270 259 274 374 395
TSTest TSTestFactory
307 304
118
Description Represents a Version Control System connection. Represents a specific version of information.
119
Base Interfaces
These are the basic interfaces shared and implemented by the most common TestDirector objects. Note that these are all interfaces and have no direct implementations or examples.
IBaseField
IObjectLockingSupport The IBaseField interface is common to all objects in the TestDirector API representing database entity entries. You can use the properties and methods in IBaseField to perform certain field-related actions, such as setting and refreshing field values. The ancestor interface, IObjectLockingSupport, is for field locking support.
IBaseField Properties
Simple Data Type Properties
Property Name AutoPost R/W R/W Type Boolean Description Determines or indicates whether the field value is updated in the TestDirector project database immediately every time the field is changed. Returns or sets the value of the field specified by the FieldName (string) parameter. Returns the ID of the specified item.
R/W
String
ID
Variant
120
Chapter 6 IBaseField
R/W R
Type Boolean
Description Returns True if the specified item has been modified since the last post operation. Indicates that the current field properties are not updated on the server side.
Virtual
Boolean
Returns True if the specified item is a virtual item, i.e., an item that does not have corresponding database records.
IBaseField Methods
Post Method
Posts all updated field values to the TestDirector project database. Syntax Post() Parameters None Returns None
Refresh Method
Refreshes the value of all fetched fields. Syntax Refresh() Parameters None
121
Returns None
Undo Method
Undoes changes to a field values that have not yet been posted. Syntax Undo() Parameters None Returns None
122
Chapter 6 IBaseFieldEx
IBaseFieldEx
IBaseField The IBaseFieldEx interface is common to some field objects in the TestDirector API, including Run, Step, and TSTest. In addition to supporting the IBaseField properties and methods, it adds properties and methods to support certain field-related actions involving attachments and history items.
IBaseFieldEx Properties
Object Properties
Property Name Attachments History R/W R R Description Returns a reference to an AttachmentFactory object for the current field. Returns a reference to a History object for the current field.
IBaseFieldEx Methods
IBaseFieldEx inherits the methods of IBaseField.
123
IBaseFieldExMail
IBaseFieldEx The IBaseFieldExMail interface is common to some field objects in the TestDirector API, including Test, Bug, and Req. In addition to supporting the IBaseFieldEx properties and methods, it adds properties and methods to support the mailing of factory items.
IBaseFieldExMail Properties
IBaseFieldExMail inherits the methods of IBaseFieldEx.
IBaseFieldExMail Methods
Mail Method
The Mail() method is used for mailing the field item. Syntax Mail(BSTR SendTo [,BSTR SendCc] [,long Option] [,BSTR Subject] [,BSTR Comment]) Parameters
Parameter Name SendTo Description A string containing the recipient address. Note that addresses can be separated by a comma or a semi-colon. (Optional) A string containing the recipients of a carbon copy of the mail. Note that addresses can be separated by a comma or a semi-colon. Default None
SendCc
Empty
124
Chapter 6 IBaseFieldExMail
Description (Optional). Indicates mailing options in a bitwise manner. The bits options are:
Default 0
TDMAIL_ATTACHMENT [1] TDMAIL_HISTORY [2] TDMAIL_TEXT [4] TDMAIL_DES_STEP [8] TDMAIL_COVER_TEST [16] TDMAIL_SINGLEMAIL [32] TDMAIL_COMMENT_AS_BODY [64]
Subject Comment (Optional) A string containing the subject line for the mail. (Optional) A comment on the sent e-mail. If the TDMAIL_COMMENT_AS_BODY option is on, this will be sent as the message body. Empty Empty
Returns None
125
IBaseFactory
IDispatch The IBaseFactory interface is common to all factory objects in the TestDirector API. You can use the properties and methods in IBaseFactory to add and remove factory child (entity) objects to and from a TestDirector project, and to create lists of child objects.
IBaseFactory Properties
Collection (List) Properties
Property Name Fields R/W R Description Returns an IList interface of available fields for the item object.
Object Properties
Property Name Filter History Item (VARIANT ItemKey) R/W R R R Description Returns a reference to a TDFilter object, for filtering the factory items. Returns a reference to a History object of this factory, referring to its entity history. Returns a reference to a child object specified in the ItemKey parameter. The data type of ItemKey varies based on the specific object factory implementing this interface.
126
Chapter 6 IBaseFactory
TDOLE_FIRST_LEVEL [0] active and system fields TDOLE_SECOND_LEVEL [1] memo fields TDOLE_THIRD_LEVEL [2] user-defined fields
IBaseFactory Methods
AddItem Method
Creates a new item object in a TestDirector project. This method can be used in two ways: You can pass a null parameter (NULL). This creates a virtual object, which does not appear in the project database. You can use the relevant object properties to fill the object. You can then use the Post method to save the object in the database. This is the recommended way to create an item to be added to the database. You can pass an ItemData parameter identifying the item to be added. When this syntax is used to create database items, no check is performed that all required fields are initialized. Syntax AddItem ( VARIANT ItemData )
127
Parameters
Parameter Name ItemData Description Required. Identifies the item to be added. The data type depends on the specific factory implementation. You can also pass the NULL parameter, as described above. Default None
NewList Method
Creates a list of objects according to the specified filter. Syntax NewList(BSTR SQLFilter) Parameters
Parameter Name SQLFilter Description Required. A string containing an SQL query statement, that filters the items in the factory. An empty string returns all child items of the current factory object. Default Empty string ( )
Returns An IList interface to the list created. The list index starts from 1 (i.e., the first item it item(1), etc.).
RemoveItem Method
Removes an item object from a TestDirector project. Syntax RemoveItem (VARIANT ItemKey)
128
Chapter 6 IBaseFactory
Parameters
Parameter Name ItemKey Description Required. Identifies the item to be removed. The data type depends on the specific factory implementation. Default None
Returns None
129
IBaseFactoryEx
IBaseFactory The IBaseFactoryEx interface is the super class of factory objects in the TestDirector API that require mailing. In addition to supporting the IBaseFactory methods and properties, this interface adds one method supporting the mailing of factory items.
Mail Method
The Mail() method is used for mailing factory items, such as bugs and requirements. Syntax Mail(VARIANT Items, BSTR SendTo [,BSTR SendCc] [,long Option] [,BSTR Subject] [,BSTR Comment]) Parameters
Parameter Name Items SendTo SendCc Option Description The ID numbers of the factory items to be mailed. A string containing the recipient address. Optional. A string containing the recipients of a carbon copy of the mail. Optional. This argument indicates various options, with each bit indicating another option. The available options/bits are: Default None None Empty 0
TDMAIL_ATTACHMENT [1] TDMAIL_HISTORY [2] TDMAIL_TEXT [4] TDMAIL_DES_STEP [8] TDMAIL_COVER_TEST [16] TDMAIL_SINGLEMAIL [32] TDMAIL_COMMENT_AS_BODY [64]
130
Chapter 6 IBaseFactoryEx
Description Optional. A string containing the subject line for the mail. Optional. A comment regarding the sent items. If the TDMAIL_COMMENT_AS_BODY option is on, this will be sent as the message body.
Returns None
131
IAlertable
TestDirector provides auto-generated alerts that allow the user to receive notifications in the event of changes to TestDirector objects based on specific rules. The IAlertable interface manages (adds, removes, and returns parameters) these alerts which result from the Bug, Test, and TestSet objects.
IAlertable Methods
DeleteAlert Method
Removes alert(s) which are relative to the current object from the database. Syntax IAlertable.DeleteAlert(VARIANT IDs) Parameters
Parameter Name IDs Description Required. Identifies items to be removed. Default None
Returns None
CleanAllAlerts Method
Removes all current object alerts from the database. Syntax IAlertable.CleanAllAlerts() Parameters None
132
Chapter 6 IAlertable
Returns None
GetAlert Method
Returns the alert related to the alert ID. Syntax IAlertable.GetAlert(long ID) Parameters
Parameter Name ID Description Required. Represents the alert ID. Default None
Returns A reference to the child object. The data type of the child object is IAlert.
GetAlertList Method
Returns a list of all relevant alerts to a particular object from the Bug, Test, or TSTest objects. Syntax IAlertable.GetAlertList([VARIANT_Bool NeedRefresh]) Parameters
Parameter Name NeedRefresh Description Determines whether to refresh cache data from server. Default False
Returns If set to True, returns a list of IAlert objects from the server. If set to False, takes the data from the client cache.
133
HasAlerts Method
Checks if a particular object has any alerts associated with it. Syntax IAlertable.HasAlerts() Parameters None Returns Returns a True if alerts exist, or False if no alerts exist.
HasNewAlerts Method
Checks if a particular object has any unread alerts associated with it. Syntax IAlertable.HasNewAlerts() Parameters None Returns Returns a True if unread alerts exist, or False if no unread alerts exist.
134
Chapter 6 TDConnection
Utility Classes
These are classes of objects used by TestDirector to perform common tasks, such as connecting to the server, managing the lists, storing data, and creating databases.
TDConnection
ITDConnection The TDConnection object is the only object that can be created directly within TestDirector, and represents a single TestDirector server connection. All other objects can be created from the TDConnection object. The first method to call with TDConnection is InitConnectionEx. The last method to call is ReleaseConnection. ConnectProject establishes a new project session, and DisconnectProject should be called at the end of each project session.
TDConnection Properties
Collection (List) Properties
Property Name DomainsList R/W R Description Returns an object with an IList interface, containing a list of the domain names for this site. Returns a list of metadata for the data type specified in the DataType parameter. Returns an IList interface, which contains the projects that are available in the domain to which TestDirector is connected. Returns an IList interface, which contains the available TestDirector projects within the domain specified by the DomainName parameter.
Fields ProjectsList
R R
135
R/W R R
Description Returns a list (IList interface) of names of the users. Returns a list (IList interface) of names of the user groups.
Object Properties
Property Name ActionPermission AlertManager AllowReconnect R/W R R R/W Description Returns a reference to an ActionPermission object. Returns a reference to an AlertManager object, which manages all alerts in a project. Returns a reference to an AllowReconnect object, which allows multiple use of the TDConnection object when true. For future use. Returns a reference to a BugFactory object. Returns a reference to a Command object. Returns a reference to a Settings object for all users. Returns a reference to a Customization object. Returns a reference to a Directory Path object. The object returns the path of the project directories. Returns a project manager. Returns an ExtendedStorage object associated with the connection, for general file storage by the third party tool. Returns a reference to a HostFactory object. Returns a reference to a HostGroupFactory object. Returns a reference to a TDMailCondition object.
R R R R R R R R
R R R
136
Chapter 6 TDConnection
Property Name ProjectProperties ReqFactory Rules RunFactory TDSettings TestFactory TestSetFactory TestSetTreeManager TextParam TreeManager UserSettings VCS
R/W R R R R R R R
Description Returns an IProjectProperties interface for the project properties object. Returns a reference to a ReqFactory object. Returns a reference to a RuleManager object. Returns a reference to a RunFactory object. Not in use. Returns a reference to a TestFactory object. Returns a reference to a TestSetFactory object. Returns a reference to a TestSetTreeManager object.
R R R R
Not in use. Returns a reference to a TreeManager object. Returns a reference to a Settings object per user. Returns a reference to a TestDirector Version Control System connection (VCS object).
DomainName
String
137
R/W R/W
Type Boolean
Description Indicates if memo and description fields are returned with HTML tags. The user interface allows many text fields to be formatted. Methods or properties that return these fields will return the embedded HTML tags if this property is false, or flat text if true. For future use. Returns TRUE if the module specified by the ModuleID parameter should be visible to the current user. Returns FALSE otherwise. Returns the current user password. Indicates whether TDConnection is connected to a TestDirector project. Returns the name of the TestDirector project that is connected. If no project is connected, this property is empty. Returns the report role of the connected user, as a numerical value. The options are: 0 - Cannot generate actuate reports 1 - Can generate actuate reports
Boolean Boolean
R R R
ReportRole
String
ServerName
String
Returns the name of the connected TestDirector server. If no server is connected, this property is empty. Returns the time and date of the currently connected server. Returns the parameter value by its name, specified by the Request parameter. Returns the path of the tests directory of the connected TestDirector project.
R R
Date String
String
138
Chapter 6 TDConnection
R/W R R/W R R
Description Returns the name of the current user connected to the TestDirector project. Indicates whether a progress bar should be displayed. Returns the path of the VCS database of the connected TestDirector project. For future use.
TDConnection Methods
InitConnection Method
For TestDirector 8.0 and up, do not use this method. Use the InitConnectionEx Method instead. Initializes the TestDirector server connection for the specified domain. Syntax TDConnection.InitConnection (BSTR ServerName [,BSTR DomainName] [,BSTR DomainPswd]) Parameters
Parameter Name Server Name DomainName DomainPswd Description Required. The name of the TestDirector server (string). Optional. The name of the domain (string). Optional. The domain password (string). Default None
Returns None
139
InitConnectionEx Method
Initializes the TestDirector server connection. This method does not contain domain information. The domain specification is performed later as part of the ConnectProjectEx method. For further details, see ConnectProjectEx Method on page 141. Syntax TDConnection.InitConnectionEx (BSTR ServerName) Parameters
Parameter Name Server Name Description Required. The name of the TestDirector server (string). Default None
Returns None
ReleaseConnection Method
Releases the TestDirector server connection. This method must be called at the end of each server session. Syntax TDConnection.ReleaseConnection() Parameters None Returns None
ConnectProject Method
For TestDirector 8.0 and up, do not use this method. Use the ConnectProjectEx Method instead.
140
Chapter 6 TDConnection
Connects to a TestDirector project. Syntax TDConnection.ConnectProject ( BSTR ProjectName ,BSTR UserName [,BSTR Password]) Parameters
Parameter Name ProjectName UserName Password Description Required. The name of the TestDirector project to connect to (string). Required. The name of the user establishing the connection to the project (string). Optional. The password of the user establishing the connection to the project (string). Default None None
Returns None
ConnectProjectEx Method
Connects to a TestDirector project. This method uses domain names. Syntax TDConnection.ConnectProjectEx (BSTR DomainName, BSTR ProjectName ,BSTR UserName [,BSTR Password]) Parameters
Parameter Name DomainName ProjectName Description Required. The domain name for the connection (string). Required. The name of the TestDirector project to connect to (string). Default None None
141
Description Required. The name of the user establishing the connection to the project (string). Optional. The password of the user establishing the connection to the project (string).
Default None
Returns None
ConnectToVcsAs Method
This method is used to indicate the active user during copy/paste action to the VCS. This method is for internal use only, and should not be used by third party applications. Syntax TDConnection.ConnectToVCSAs(BSTR UserName, BSTR Password, BSTR CopyDesStep) Returns A string containing the requested directory.
DisconnectProject Method
Disconnects from a TestDirector project. This method must be called at the end of each project session. Syntax TDConnection.DisconnectProject() Parameters None Returns None
142
Chapter 6 TDConnection
ChangePassword Method
This method changes the password for the current user. Syntax TDConnection.ChangePassword (BSTR OldPassword, BSTR NewPassword) Parameters
Parameter Name OldPassword NewPassword Description Required. The current user password (string). Required. The new password for the current user (string). Default None None
Returns None
GetLicense Method
Gets a license for the specified client type. Syntax TDConnection.GetLicense ( long ClientType )
143
Parameters
Parameter Name ClientType Description Required. The type of client (long). The options are: Default None
Returns
LIC_OTA_CLIENT - general API license LIC_DEFECT - Defect License LIC_REQUIREMENT - Requirement license LIC_TEST_LAB - Planning and Test Execution license LIC_COLLABORATION - Collaboration license
144
Chapter 6 TDConnection
GetLicenses Method
Gets licenses simultaneously for all the modules. Syntax TDConnection.GetLicenses(long ClientsType, BSTR *pVal) Parameters
Parameter Name ClientsType Description Required. The type of client (long). The options are: Default None
pVal
Returns a structure. Note that this method is for internal use only.
Returns None
GetLicenseStatus Method
Gets the license for the specified client type. Syntax TDConnection.GetLicenseStatus ( long ClientType, long *InUse, long * Max )
145
Parameters
Parameter Name ClientType Description Required. The type of client (long). The options are: Default None
InUse Max
LIC_OTA_CLIENT - general API license LIC_DEFECT - Defect License LIC_REQUIREMENT - Requirement license LIC_TEST_LAB - Planning and Test Execution license. LIC_COLLABORATION - Collaboration license
Returns the number of modules of the specified type that are currently in use. Returns the maximum number of modules of the specified type that can be used simultaneously.
Returns None
PurgeRuns Method
The PurgeRuns method deletes all the runs that comply with a filter specified by its parameters. Syntax TDConnection.PurgeRuns(BSTR TestSetFilter, long KeepLast, VARIANT OlderThan, long UnitCount, VARIANT_BOOL StepsOnly)
146
Chapter 6 TDConnection
Parameters
Parameter Name TestSetFilter Description Required. The filter specifying the test sets from which the runs should be deleted (String). For example, "1,5,78,14", "CY_STATUS='Open", or the regular text of the ITDFilter.Text. For internal use only. Required. The date before which the runs should be deleted (Date). For internal use only. For internal use only. Default None
Returns None
SendMail Method
Uses the TestDirector server to send e-mail. Syntax TDConnection.SendMail ( BSTR To [, ,BSTR From] [,BSTR Subject][,BSTR Message] [,VARIANT attachArray] [,BSTR bsFormat] )
147
Parameters
Parameter Name To From Description Required. TestDirector user name, any e-mail address, or a list of e-mail addresses. Optional. The user name or e-mail address of the sender. If left blank, the e-mail associated with the connected user will be used. Optional. The subject of the e-mail (string). Optional. The body of the e-mail (string). An array of attachments. The mail format. Can be either HTML or Text. If this field is empty, TestDirector looks at the TDParams parameter. Default None
None
Returns None
SynchronizeFollowUps Method
Sends all previously unsent follow-ups. Syntax TDConnection.SynchronizeFollowUps(BSTR Password) Parameters
Parameter Name Password Description Required. An administrator password with encryption. Default None
Returns None
148
Chapter 6 TDConnection
TDConnection Examples
Example 1 - Server Connection The following Visual Basic example explains how to connect to a TestDirector server. 1 Create a new standard EXE project by selecting File > New Project and Standard EXE. 2 Add a reference to the OTA API by selecting Project > References, and choosing the OTA COM 8.0 Type Library reference. 3 Add a text box and a button to the form. 4 Add the following lines to declare the TDConnection object, and to connect to the server address in the text box by clicking the <Command1> button:
Dim tdc As New TDConnection Private Sub Command1_Click() tdc.InitConnection Text1.Text Command1.Caption = "Connect" End Sub
6 Run the project by entering a TestDirector address in the text box (such as http://localhost/tdbin), and clicking the <Command1> button to connect to the server.
149
Example 2 - Project Connection The following Visual Basic example explains how to establish a connection to a project. 1 Perform the procedure described in Example 1. 2 Add a list box and another button to the form. 3 Add the following code lines to the end of the Command1_Click() subroutine (just after setting the caption) to obtain the project names and add them to the list box:
List1.Clear For Each Project In tdc.ProjectsList List1.AddItem (Project) Next
4 Add the following sub-routine to connect to the project selected in the list box, using the <Command2> button:
Private Sub Command2_Click() tdc.ConnectProject List1.Text, "admin" Command2.Caption = "Connect to " + tdc.ProjectName End Sub
150
Chapter 6 TDConnection
6 Run the project. The dialog box you created should be in the following format:
Example 3 - Base Example The following Visual Basic project is used in later examples as a base code. You should hard code the server address and project name so that you can reuse them. Create a project as in Example 1, and add the following code:
Dim tdc As New TDConnection Private Sub Form_Load() tdc.InitConnection "<server name>" tdc.ConnectProject "TestDirector_Demo", "admin" End Sub Private Sub Form_Unload(Cancel As Integer) If tdc.Connected Then If tdc.ProjectConnected Then tdc.DisconnectProject End If tdc.ReleaseConnection End If End Sub
Note that the above procedure connects to the project, creates a blank dialog box, and disconnects the project upon closure of the dialog box.
151
Example 4 - SendMail The following Visual Basic example explains how to use the SendMail method. 1 Create a new standard EXE project by selecting File > New Project and Standard EXE. 2 Add a reference to the OTA API by selecting Project > References, and choosing the OTA COM 8.0 Type Library reference. 3 Add a button to the form. 4 Add the following code:
Dim Clnt As TDConnection Private Sub Command1_Click() On Error GoTo error_handle Set Clnt = New TDAPIOLELib.TDConnection Clnt.InitConnection "<Machine Name>" Clnt.ConnectProject "<Project Name>", "<User Name>" Dim message As String message = "test" + vbCRLF message = message + "" + vbCRLF Dim a a = Array("c:\tmp\a.txt", "c:\tmp\b.txt") Clnt.SendMail "bob@mercuryinteractive.com", "", _ "Attachment From VB", message, a, "" MsgBox "Message Sent" Clnt.DisconnectProject Clnt.ReleaseConnection Set Clnt = Nothing Exit Sub error_handle: MsgBox Err.Description Resume Next End Sub
152
Chapter 6 Command
Command
ICommand IParam The Command object defines a database command. The object implements two interfaces: IParam, which handles the command parameters, and ICommand, which handles execution of the command. You can use a Command object to query the database and return records in a Recordset object, to execute a bulk operation, and to manipulate the structure of the database. For more information on Recordset objects, see Recordset on page 158.
AffectedRows
Long
153
ParamValue (VARIANT Key) R/W Variant
TDOLE_LONG [0] TDOLE_ULONG [1] TDOLE_FLOAT [2] TDOLE_STRING [3] TDOLE_MEMO [4] TDOLE_DATE [5] TDOLE_TIMESTAMP [6]
Returns or sets the value of the parameter specified by the Key parameter. Key can represent the parameter index (long) or name (string).
154
Chapter 6 Command
Returns None
155
DeleteParam Method
Removes the specified parameter from the current command. Syntax Command.DeleteParam (VARIANT Key ) Parameters
Parameter Name Key Description Represents the parameter index (long) or name (string). Default None
Returns None
DeleteParams Method
Removes all parameters from the current command. Syntax Command.DeleteParams() Parameters None Returns None
156
Chapter 6 Command
Command Example
The following procedure declares Command and RecordSet objects for executing an SQL command and displaying its results. 1 Start with the base code (Example 3 - Base Example on page 151). 2 Add a button and a list box to the form. 3 Add the following sub-routine:
Private Sub Command1_Click() Dim com As TDAPIOLELib.Command Dim RecSet As TDAPIOLELib.Recordset
The Command object command is set and executed. The RecordSet object is then set as the return value and displayed in the second column of data in the list box.
157
Recordset
IRecordset IColumnInfo The Recordset object represents the entire set of records resulting from an executed command. At any given time, the Recordset object refers to a single record within the record set as the current record. The IRecordset interface inherits from the IColumnInfo interface.
CacheSize
R/W
Long
EOR
Boolean
R/W
Variant
Position RecordCount
R/W R
Long Long
158
Chapter 6 Recordset
Long
TDOLE_LONG [0] TDOLE_ULONG [1] TDOLE_FLOAT [2] TDOLE_STRING [3] TDOLE_MEMO [4] TDOLE_TIMESTAMP [6]
ColName (long Index) ColIndex (BSTR Name) R Long R String Gets the name of a column in Recordset specified by the index parameter. Gets the index of a column in a Recordset object specified by its column name (the Name parameter).
159
Recordset Methods
Clone Method
Creates a duplicate Recordset object from the current Recordset object. Syntax Recordset.Clone() Parameters None Returns A new record set.
First Method
Moves the cursor to the first record in the current Recordset object and makes this record the current record. Syntax Recordset.First() Parameters None Returns None
160
Chapter 6 Recordset
Last Method
Moves the cursor to the last record in the current Recordset object and makes this record the current record. Syntax Recordset.Last() Parameters None Returns None
Next Method
Moves the cursor to the next record in the current Recordset object and makes this record the current record. Syntax Recordset.Next() Parameters None Returns None
161
Prev Method
Moves the cursor to the previous record in the current Recordset object and makes this record the current record. Syntax Recordset.Prev() Parameters None Returns None
Refresh Method
Refreshes the current Recordset object according to the specified range. Syntax Recordset.Refresh([Range] [,Low] [,High]) Parameters
Parameter Name Range Low High Description Reserved for future use. Optional. The index of the lowest record in the range (long). Optional. The index of the highest record in the range (long). Default 0 None None
Returns None
162
Chapter 6 Recordset
Recordset Example
The following procedure declares Command and RecordSet objects for executing an SQL command and displaying its results. 1 Start with the base code (Example 3 - Base Example on page 151). 2 Add a button and a list box to the form. 3 Add the following sub-routine:
Private Sub Command1_Click() Dim com As TDAPIOLELib.Command Dim RecSet As TDAPIOLELib.Recordset
The Command object command is set and executed. The RecordSet object is then set as the return value and displayed in the second column of data in the list box.
163
FileData
IFileData The FileData object represents folder or file information, such as name, size, and type.
FileData Properties
Collection (List) Properties
Property Name Items R/W R Description Only relevant for folders. Returns a list (with an IList interface) of all objects in the folder, including files and sub-folders.
R R R
TDOLE_FOLDER [0] - The object is a folder. TDOLE_FILE [1] - The object is a file.
164
Chapter 6 FileData
FileData Methods
None
FileData Example
The following Visual Basic example describes how to retrieve project attachment names. 1 Start with the base code (Example 3 - Base Example on page 151). 2 Add a button and a list box to the form. 3 Add the following sub-routine:
Private Sub Command1_Click() Dim es As ExtendedStorage Dim Root As FileData Dim file As FileData
Note that this example uses two types of FileData objects: a folder (Root) and a file (file).
165
TDFilter
ITDFilter The TDFilter object lets you create a filtered list of field objects without any SQL knowledge. TDFilter implements an abstract filter interface, ITDFilter. To create a filtered list of objects, you can add conditions to TDFilter specifying order, position, and direction. The TDFilter object understands filter conditions with the same filter syntax, as defined in TestDirector. For more information on filter conditions, refer to the TestDirector User Guide.
TDFilter Properties
Simple Data Type Properties
Property Name CaseSensitive (BSTR FieldName) R/W R/W Type Boolean Description Indicates/determines whether the filter for the field specified by the FieldName parameter is case sensitive. Note that the default is not case sensitive. Indicates the filtered entity type. Possible values: BUG, TEST, CYCLE, REQ, HOSTS, TESTCYCL, DESSTEPS, RUN, STEP. Returns or sets the filter condition for the field specified by the FieldName parameter. Returns or sets the specified field position in the field order. Returns or sets the specified field order direction. Possible values are:
DataType
String
R/W
String
R/W
Long
R/W
Integer
Text R/W String
TDOLE_ASCENDING TDOLE_DESCENDING
Gets/sets the full fields filter as text, which is displayed above the grid.
166
Chapter 6 TDFilter
R/W R/W
Type String
Description Gets/sets the union filtering on the entity types specified by the type parameter. Gets/sets the cross reference filtering according to the entity types specified by the type parameter. Possible values:
R/W
String
'BUG-TEST', 'TESTSET-TEST', 'REQTEST', 'BUG-TESTSET', 'TESTTESTSET', 'TEST-BUG', 'TSTESTBUG', 'TESTSET-BUG', 'REQ-BUG', 'TEST-REQ', 'BUG-REQ', 'TSTESTREQ'. List Properties
Property Name Fields R/W R Description Returns an IList interface containing the filter for each field as text.
TDFilter Methods
Clear Method
Clears the current filter. Syntax TDFilter.Clear() Parameters None Returns None
167
NewList Method
Creates a new list from the current filter. Syntax TDFilter.NewList() Parameters None Returns List object. The list index starts from 1 (i.e., the first item it item(1), etc.).
Refresh Method
Refreshes the fetched list according to the current filter. Syntax TDFilter.Refresh() Parameters None Returns None
168
Chapter 6 TDFilter
TDFilter Example
The following Visual Basic example describes how to display the IDs and status of defects, filtered by the user responsible for the defects. 1 Start with the base code (Example 3 - Base Example on page 151). 2 Add a button, text box, and list box to the form. 3 Add the following sub-routine:
Private Sub Command1_Click() Dim Filter As TDFilter Dim Bgf As BugFactory Dim Str As String
4 Enter a user name in the text box and click the button. A list of bug IDs and their status, filtered according to the bugs for which the specified user is responsible, is displayed.
169
TDField
ITDField The TDField object represents a TestDirector project field, with field system properties and other properties specific to TestDirector. For a list of TestDirector fields, see Data Tables on page 54.
TDField Properties
Object Properties
Property Name Property R/W R Description Returns a reference to the FieldProperty object associated with the current field.
TDOLE_LONG [0] TDOLE_ULONG [1] TDOLE_FLOAT [2] TDOLE_STRING [3] TDOLE_MEMO [4] TDOLE_DATE [5] TDOLE_TIMESTAMP [6]
170
Chapter 6 TDField
TDField Methods
IsValidValue Method
Checks whether the value entered into a particular field is valid. Syntax TDField.IsValidValue(VARIANT Value ) Parameters
Parameter Name Value Description Required. Default None
TDField Example
The following Visual Basic example describes how to display all field names for the Bug (defect) object/table. 1 Start with the base code (Example 3 - Base Example on page 151). 2 Add a button and list box to the form. 3 Add the following sub-routine:
Private Sub Command1_Click() Dim fld As TDField Dim bgf As BugFactory Set bgf = tdc.BugFactory For Each fld In bgf.Fields List1.AddItem (fld.Name) Next End Sub
4 Run the program and click the button to display the fields of the defect factory in the list box.
171
FieldProperty
IFieldProperty A FieldProperty object contains specific TestDirector properties for the object fields. Use it to return property information for an object field.
FieldProperty Properties
Object Properties
Property Name Root R/W R Description Returns a reference to a SysTreeNode object representing the tree root connected to the current field.
IsActive
Boolean
172
Chapter 6 FieldProperty
R/W R
Type Boolean
Description Indicates whether the field saves the Tree Node ID, rather than the passed value. Possible values are:
IsCanFilter R Boolean
TRUE - Available values for the current field are node names for the field tree root. FALSE - The field uses the passed value.
Indicates whether the field is enabled to appear in the TestDirector filter dialog box. Indicates whether the field is shown in the customization user interface. Indicates whether the field is editable. Indicates whether the field stores its change history. Indicates whether the field stores its last value. Indicates whether the field is a database key field. Indicates whether users on the list to be notified of changes are notified when the field is changed. Indicates that this field has been modified, but not yet updated to the database. Indicates whether the field is required. If the field is required, then no new item can be created without filling it. Indicates whether the field is a predefined TestDirector system field.
R R R R R R
IsModify
Boolean
IsRequired
Boolean
IsSystem
Boolean
173
R/W R
Type Boolean
Description Indicates whether a summation of this field can be performed for graph presentation. Indicates whether the field requires verification. Indicates whether this field is under version control. For future use. Indicates whether this field is visible in the New Bug form. Returns the database key order. Indicates whether this field is readonly. Returns the user column type. Possible values: char, number, date, and an empty string. Returns a user-defined label.
R R R R R R R
UserLabel
String
FieldProperty Methods
None
174
Chapter 6 FieldProperty
FieldProperty Example
The following Visual Basic example describes how to display property information for an object field. 1 Follow the procedure in the TDField Example on page 171. 2 Add a button and label to the form. 3 Add the following sub-routine to the code:
Private Sub Command2_Click() Dim bgf As BugFactory Dim fld As TDField Dim fldp As FieldProperty
4 Click the upper button, select a field from the list, and click the lower button. The field user label is displayed.
175
List
IList The List object is used to create and maintain lists. You can use any factory object to create any number of list instances for objects in the factory. You can use the _NewEnum method to create a standard enumerator with an IEnumVARIANT interface. The IEnumVARIANT interface provides a method for enumerating a factory of variants, including heterogeneous factories of objects and intrinsic types. The Next method of the IEnumVARIANT interface can return several enumerated elements at once. IEnumVARIANT is a standard COM interface. The IFactoryList interface is derived from the IList interface.
List Properties
Property Name Count Item (long Index) R/W R R Type Long Variant Description Returns the number of elements in the list. Returns a list item by the item index parameter.
List Methods
_NewEnum Method
Creates a list enumerator. Syntax List._NewEnum() Parameters None
176
Chapter 6 List
Add Method
Adds a new item to the current List object. Syntax List.Add (VARIANT vNew ) Parameters
Parameter Name vNew Description Required. An IDispatch interface to the object to be added. Default None
Returns None
Insert Method
Inserts a new item to the current List object, at a specific position. Syntax List.Insert(long Pos, VARIANT vNew)
177
Parameters
Parameter Name Pos vNew Description The list position into which the item should be inserted. Required. An IDispatch interface to the object to be added. Default None None
Returns None
Remove Method
Removes the specified item from the current List object. Syntax List.Remove (long Index ) Parameters
Parameter Name Index Description Required. The index of the item to be removed. Default None
Returns None
Swap Method
Swaps two list elements, specified by their positions. Syntax List.Swap(long Pos1, long Pos2)
178
Chapter 6 List
Parameters
Parameter Name Pos1 Pos2 Description The position of the first element to be swapped with the second element. The position of the second element to be swapped with the first element. Default None None
Returns None
179
FactoryList
IFactoryList IList The FactoryList object is used to create and maintain lists within entity factories. You can use any factory object to create any number of list instances for objects in the factory. The IFactoryList interface inherits from the IList interface.
FactoryList Properties
Collection (List) Properties
Property Name Fields R/W R Description Returns an object, with an IList interface, of meta data for the items in the list.
180
Chapter 6 FactoryList
FactoryList Methods
Post Method
Posts all updated data from all items in the list to the TestDirector project database. Syntax FactoryList.Post() Parameters None Returns None
Refresh Method
Refreshes the list filter and all data in the listed objects. Syntax FactoryList.Refresh() Parameters None Returns None
181
ExtendedStorage
IExtendedStorage The ExtendedStorage object downloads a storage structure from the server to the client file system. It also supports file manipulations and saves the file back to the server side.
ExtendedStorage Properties
Object Properties
Property Name Root R/W R Description Returns an IFileData interface to the storage root.
ServerPath
R/W
String
182
Chapter 6 ExtendedStorage
ExtendedStorage Methods
Cancel Method
Cancels a load/save action. Syntax ExtendedStorage.Cancel() Parameters None Returns None
GetLastError Method
Returns any error that occurred during the operation. Used only for asynchronous load/save operations, when error handling cannot be used. Syntax ExtendedStorage.GetLastError() Parameters None Returns None. The error is actually returned through the function HRESULT return value.
Load Method
Starts the download operation. Syntax ExtendedStorage.Load ([BSTR FSysFilter], [VARIANT_BOOL Synchronize])
183
Parameters
Parameter Name FSysFilter Description Optional. File system filter. Can contain "-r" at the beginning. This indicates that the filter is applied recursively to all subfolders. If the filter is an empty string, then all files with all subfolders are downloaded to the client side. Optional. Specifies if the load operation is synchronous or asynchronous. If the operation is synchronous (true), the process begins and is not checked for status until the process is completed. This can take a lot of time when downloading large files. If the operation is asynchronous, the function immediately begins the download operation and checks process status constantly, to check if the download is finished. In this case, the user must check the "ActionFinished" property periodically, and use a "GetLastError" method in case of error (boolean). Default *.*
Synchronize
FALSE
Returns The path on the client machine where the downloaded file(s) reside.
Progress Method
Checks the progress of the download action. Syntax ExtendedStorage.Progress (long* Total, long* Current)
184
Chapter 6 ExtendedStorage
Parameters
Parameter Name Total Current Description Required. The total number of bytes of memory to be downloaded (long). Required. The number of bytes of memory that has been downloaded so far (long). Default None None
Save Method
Uploads storage structure to server. Syntax ExtendedStorage.Save ([BSTR FSysFilter] [, VARIANT_BOOL Synchronize]) Parameters
Parameter Name FSysFilter Description Optional. File system filter. Can contain "-r" at the beginning. This indicates that the filter is applied recursively to all subfolders. If the filter is an empty string, then all files with all subfolders are downloaded to the client side. Default *.*
185
Description Optional. Specifies if the load operation is synchronous or asynchronous. If the operation is synchronous (true), the process begins and is not checked for status until the process is completed. This can take a lot of time when downloading large files. If the operation is asynchronous, the function immediately begins the download operation and checks process status constantly, to check if the download is finished. In this case, the user must check the "ActionFinished" property periodically, and use a "GetLastError" method in case of error (boolean).
Default FALSE
Returns None
Delete Method
Deletes the loaded files. Syntax ExtendedStorage.Delete ([BSTR FSysFilter], long nDeleteType)
186
Chapter 6 ExtendedStorage
Parameters
Parameter Name FSysFilter Description Optional. File system filter. Can contain "-r" at the beginning, meaning that the filter is applied recursively (to all subfolders). If the filter is an empty string, then all files with all subfolders are downloaded to the client side (string). The delete type to be used. Default *.*
nDeleteType
None
Returns None
LoadEx Method
Starts the download operation. Syntax ExtendedStorage.LoadEx ([BSTR FSysFilter] [, VARIANT_BOOL Synchronize], VARIANT_BOOL IList, VARIANT_BOOL NonFatalErrorOccured)
187
Parameters
Parameter Name FSysFilter Description Optional. File system filter. Can contain "-r" at the beginning. This indicates that the filter is applied recursively to all subfolders. If the filter is an empty string, then all files with all subfolders are downloaded to the client side. Optional. Specifies if the load operation is synchronous or asynchronous. If the operation is synchronous (true), the process begins and is not checked for status until the process is completed. This can take a lot of time when downloading large files. If the operation is asynchronous, the function immediately begins the download operation and checks process status constantly, to check if the download is finished. In this case, the user must check the "ActionFinished" property periodically, and use a "GetLastError" method in case of error (boolean). For future use. Indicates an error that occurred was nonfatal. This feature is only available when Synchronize is True. None Default *.*
Synchronize
FALSE
IList NonFatalErrorOccurred
Returns None
SaveEx Method
Uploads storage structure to server. Syntax ExtendedStorage.SaveEx ([BSTR FSysFilter] [, VARIANT_BOOL Synchronize], VARIANT_BOOL IList,
188
Chapter 6 ExtendedStorage
Synchronize
FALSE
IList NonFatalErrorOccurred
Returns None
ExtendedStorage Example
See FileData Example on page 165.
189
FollowUpManager
IFollowUpManager The FollowUpManager object manages the follow-ups which are user-defined and configured to activate on the date chosen by the user.
FollowUpManager Properties
Simple Data Type Properties
Property Name HasFollowUp IsFollowUpOverdue R/W R R Type Boolean Boolean Description Checks whether object has a follow-up associated with it. Compares date of unsent follow-up with current server date.
FollowUpManager Methods
GetFollowUp Method
Gets the date and description for the follow-up associated with the current object. Syntax GetFollowUp(TDateTime FollowUpDate, BSTR Description)
190
Chapter 6 FollowUpManager
Parameters
Parameter Name FollowUpDate Description Description The date the follow-up was configured to activate. The description of the follow-up. Default None None
SetFollowUp Method
Sets an alert flag for follow-up for the current object. Syntax SetFollowUp(TDateTime FollowUpDate, BSTR Description) Parameters
Parameter Name FollowUpDate Description Description The date the follow-up was configured to activate. The description of the follow-up. Default None None
Returns None
191
CancelFollowUp Method
Deletes the follow-up associated with the current object. Syntax CancelFollowUp() Parameters None Returns None
192
Chapter 6 AlertManager
AlertManager
IAlertManager The IAlertManager interface is common to the Bug, Test, and TSTest objects in the TestDirector API. The interface manages the addition, deletion, and returning of parameters for the alerts related to these objects.
AlertManager Properties
Object Properties
Property Name Alert AlertList R/W R R Description Returns reference to the Alert object, based on the alert ID. Returns a reference to the list of user alerts of the current project.
AlertManager Methods
DeleteAlert Method
Removes alert(s) which are relative to the current object from the database. Syntax DeleteAlert(VARIANT IDs) Parameters
Parameter Name IDs Description Required. Identifies items to be removed. Default None
Returns None
193
CleanAllAlerts Method
Removes all current object alerts from the database. Syntax CleanAllAlerts() Parameters None Returns None
194
Chapter 6 AttachmentFactory
Data Objects
These are the main and most common TestDirector objects. They represent actual data entities or their containers.
AttachmentFactory
IBaseFactory IAttachmentFactory The AttachmentFactory object adds and removes attachments to and from the current field object. For an explanation of attachments, see the Attachment object description on page 198.
AttachmentFactory Properties
Object Properties
Property Name AttachmentStorage R/W R Description Returns the ExtendedStorage object for downloading and uploading attachment files.
AttachmentFactory Methods
FactoryProperties Method
The FactoryProperties method returns the owner type and owner key for the AttachmentFactory object. Syntax FactoryProperties (BSTR* OwnerType, VARIANT* OwnerKey )
195
Parameters
Parameter Name OwnerType OwnerKey Description A string returning the attachment owner type. A string returning the attachment ID. Default None None
The following variations exist for IBaseFactory method parameters when used with an AttachmentFactory object.
Method Name AddItem RemoveItem Parameter Name ItemData ItemKey Variation You must pass a NULL parameter. Identifies the item by Attachment ID (long).
AttachmentFactory Example
The following Visual Basic example describes how to add URL links as attachments to defects. 1 Start with the base code (Example 3 - Base Example on page 151). 2 Add a button, text box, and list box to the form. 3 Add the following declarations to the global declarations at the top of the code:
Dim Dim Dim Dim Dim bgf As BugFactory bg As Bug attf As AttachmentFactory att As Attachment attList As List
196
Chapter 6 AttachmentFactory
5 Click the button to add the URL address in the text box as an attachment to the defect. Use forward slashes (/) in the address. The attachment list for the defect is displayed.
197
Attachment
IAttachment The Attachment object represents a single attachment in a TestDirector project. An attachment is a file or Internet address attached to a field object and opened directly from TestDirector. For example, design documents, detailed defect descriptions, graphic files, and Web pages can be used as attachments.
Attachment Properties
Object Properties
Property Name AttachmentStorage R/W R Description Returns the ExtendedStorage object of this attachment. This property is only relevant for file attachments.
R/W R R
198
Chapter 6 Attachment
R/W R R
Description Returns the time of the last modification to the attachment. Returns the name of the attachment. An optional parameter, ViewFormat (long), specifies the format of the attachment name. A value of 1 indicates the field contains a file name, 0 (the default) indicates the field contains a file name with a prefix indicating its item type and number.
ServerFileName Type
R R/W
String Long
The attachment file name on the server machine. Returns/sets the attachment type. This can be one of the following:
FileName R/W String
TDATT_FILE [1] - A file in the attachment repository. TDATT_INTERNET [2] - A link to a file or Internet address.
If the attachment is an actual file, this property returns the file location. If the attachment is a virtual file, this property sets the file location for the attachment before it is uploaded to the server. If the attachment is a URL, this property returns or sets the link address. Use forward slashes (/) in the link address.
Attachment Methods
In addition to the methods described below, this object implements all the IBaseField methods. See IBaseField on page 120.
199
Load Method
This method downloads an attachment file to a client machine. Syntax Attachment.Load (VARIANT_BOOL Synchronize, BSTR* Rootpath) Parameters
Parameter Name Synchronize Description If TRUE, the file is downloaded synchronously. This means that any running function stops until the downloading is finished. If FALSE, the file is loaded asynchronously. This means that all functions continue running while the file is downloading. Represents the path to which the file should be downloaded on the client machine (string). Default None
RootPath
None
Returns None
Rename Method
This method renames the attachment. Syntax Attachment.Rename (BSTR NewName)
200
Chapter 6 Attachment
Parameters
Parameter Name NewName Description A string containing the new name that should be assigned to the attachment. Default None
Returns None
201
Save Method
This method uploads a file to the TestDirector server. Syntax Attachment.Save (VARIANT_BOOL Synchronize) Parameters
Parameter Name Synchronize Description If TRUE, the file is uploaded synchronously. This means that any running function stops until the upload is finished. If FALSE, the file is loaded asynchronously. This means that all functions continue running while the file is uploaded. Default None
Returns None
Attachment Example
The following Visual Basic example describes how to load attachment files from the server to the client. 1 Follow the procedure in the AttachmentFactory Example on page 196. 2 Add a label to the form, and add the following sub-routine:
Private Sub List1_Click() Set att = attList.Item(List1.ListIndex + 1) Label1.Caption = att.Name If att.Type = TDATT_FILE Then att.Load True, "C:" Label1.Caption = att.FileName End If End Sub
3 Click the file attachment after the attachment list has been retrieved. The file will be downloaded to the location displayed by the label.
202
Chapter 6 ReqFactory
ReqFactory
IBaseFactory IBaseFactoryEx IReqFactory The ReqFactory object is a single-instance object responsible for adding and removing test requirements to and from a TestDirector project. You can use the Item property to return an IDispatch interface to a Req object by Requirement ID. You can also use the NewList method to return an IDispatch interface to a List object listing the project requirements.
ReqFactory Properties
The following variations exist for IBaseFactory property parameters when used with a ReqFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the requirement ID (long).
203
ReqFactory Methods
The following variations exist for IBaseFactory method parameters when used with a ReqFactory object.
Method Name AddItem Parameter Name ItemData Variation Identifies the requirement by one of the following:
The parent requirement ID (Variant). An array consisting of the following elements: (0) FatherID - The parent requirement ID (long or string, required). (1) Order - The new requirement position in the children list (long, optional). Possible values are: - A number representing the requirement position. - TDPOSITION_LAST [-4] - Default. Indicates that the requirement is inserted last.
RemoveItem
ItemKey
Identifies the requirement by its ID (long) or an IDispatch interface to the Req object itself.
204
Chapter 6 ReqFactory
BuildPerfGraph Method
Creates a graph object. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildPerfGraph([BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT FRDate] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is RG_REG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only requirements with a change date after this date are reflected in the graph. Default
SumOfField MaxCols
Filter FRDate
None None
205
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
BuildPerfGraphEx Method
The BuildPerfGraphEx method creates a graph object. This method contains all of the same features as the BuildPerfGraph method, with additional support for the ShowNullParents parameter. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildPerfGraph([BSTR GroupByField] [, BSTR SumOfField] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] [, VARIANT_BOOL ShowNullParents])
206
Chapter 6 ReqFactory
Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is RG_REG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only requirements with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: Default
SumOfField MaxCols
Filter FRDate
None None
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique. Only for Requirements mode. Overrides the feature that prevents parent folders, which are not covered, from being viewed during Cover Status queries. A value of true allows these folders to appear.
ShowNullParents
FALSE
207
BuildProgressGraph Method
Creates a requirement progress graph that shows the number of requirements in a TestDirector project over a period of time. All parameters are optional, so you can create a default progress graph without passing any parameters. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildProgressGraph ( [BSTR GroupByField] [, BSTR SumOfField] [, VARIANT_BOOL ByHistory] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] ) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is RG_REG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. Determines whether to use history information to create the graph. Possible values are: Default
SumOfField ByHistory
TRUE
208
Chapter 6 ReqFactory
Description Optional. Determines the interval type shown in the graph (long). Possible values are:
Default 0
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of requirements as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only requirements with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: 1 0
Filter FRDate
None None
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
209
BuildProgressGraphEx Method
The BuildProgressGraphEx method creates a graph object. This method contains all of the same features as the BuildProgressGraph method, with additional support for the ShowNullParents parameter. All parameters are optional, so you can create a default progress graph without passing any parameters. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildProgressGraphEx ( [BSTR GroupByField] [, BSTR SumOfField] [, VARIANT_BOOL ByHistory] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] [, VARIANT_BOOL ShowNullParents] ) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is RG_REG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. Determines whether to use history information to create the graph. Possible values are: Default
SumOfField ByHistory
TRUE
210
Chapter 6 ReqFactory
Description Optional. Determines the interval type shown in the graph (long). Possible values are:
Default 0
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of requirements as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only requirements with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: 1 0
Filter FRDate
None None
ForceRefresh
FALSE
211
Description Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique. Only for Requirements mode. Overrides the feature that prevents parent folders, which are not covered, from being viewed during Cover Status queries. A value of true allows these folders to appear.
Default FALSE
ShowNullParents
FALSE
212
Chapter 6 ReqFactory
BuildSummaryGraph Method
Creates a requirement summary graph that shows the number of requirements reported in the TestDirector project database according to the requirement tracking information specified by the user. All parameters are optional, so you can create a default requirement summary graph without passing any parameters. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildSummaryGraph ( [BSTR XAxisField] [,BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath] ) Parameters
Parameter Name XAxisField SumOfField GroupByField Description Optional. A database field representing the name of the graph x-axis (string). For internal use only. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is RG_REG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Default None None
MaxCols
Filter
None
213
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
214
Chapter 6 ReqFactory
BuildSummaryGraphEx Method
All parameters are optional, so you can create a default requirement summary graph without passing any parameters. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildSummaryGraphEx ( [BSTR XAxisField] [,BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath] [,VARIANT_BOOL ShowNullParents]) Parameters
Parameter Name XAxisField SumOfField GroupByField Description Optional. A database field representing the name of the graph x-axis (string). For internal use only. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is RG_REG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: Default None None
MaxCols
Filter ForceRefresh
None FALSE
215
Description Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique. Only for Requirements mode. Overrides the feature that prevents parent folders, which are not covered, from being viewed during Cover Status queries. A value of true allows these folders to appear.
Default FALSE
ShowNullParents
FALSE
216
Chapter 6 ReqFactory
BuildTrendGraph Method
Creates a graph that shows the number of status changes in the requirements of a TestDirector project over a time period. The x-axis indicates the time intervals, and the y-axis indicates the number of status changes. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildTrendGraph([BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT FRDate] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is RG_REG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only requirements with a change date after this date are reflected in the graph. Default
SumOfField MaxCols
Filter FRDate
None None
217
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
218
Chapter 6 ReqFactory
BuildTrendGraphEx Method
The BuildTrendGraphEx method creates a graph object. This method contains all of the same features as the BuildTrendGraph method, with additional support for the ShowNullParents parameter. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildTrendGraphEx([BSTR GroupByField] [, BSTR SumOfField] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] [, VARIANT_BOOL ShowNullParents]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is RG_REG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only requirements with a change date after this date are reflected in the graph. Default
SumOfField MaxCols
Filter FRDate
None None
219
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique. Only for Requirements mode. Overrides the feature that prevents parent folders, which are not covered, from being viewed during Cover Status queries. A value of true allows these folders to appear.
ShowNullParents
FALSE
Find Method
This method finds a value in a specified field and returns a list of requirements containing this value for the field. Syntax ReqFactory.Find(long StartRootID, BSTR FieldName, BSTR Pattern [,long Mode] [,long Limit]) Parameters
Parameter Name StartRootID FieldName Description Required. The ID of the root of the subtree from which to start the search. Required. The name of the field to scan for the value. Default None None
220
Chapter 6 ReqFactory
Description Required. The search pattern/value to look for (regular expression are permitted in SQL format only). Optional. Indicates the requirement search mode. The available values are:
Default None
Mode
Returns An IList interface to the found records list, formatted as a string "ID,NAME".
GetChildrenList Method
This method creates a list of all the child requirements of the specified father requirement. Syntax ReqFactory.GetChildrenList(long FatherID)
221
Parameters
Parameter Name FatherID Description Required. The ID of the father requirement for which we request the children requirements. Default None
ReqFactory Example
Example 1 The following example fetches all the requirements in the project. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button and a list box to the form. 3 Add the following declarations to the global declarations at the top of the code:
Dim Reqf As ReqFactory Dim ReqList As List Dim req As req
5 Run the program. Pushing the button, this program simply details all the requirements names.
222
Chapter 6 ReqFactory
Example 2 The following example finds requirements by name pattern. 1 Follow the procedure in Example 1 on page 222. 2 Add a button, a text box, and a list box to the form. 3 Add the following sub-routine:
Private Sub Command2_Click() ' Getting start root ID Set req = Reqf.NewList("").Item(0)
4 Run this program, enter a search pattern, and click the second button to display the search results in the second list box.
223
Req
IReq IBaseFieldExMail IReqSummaryStatus IReqCoverageStatus The Req object represents a requirement in a TestDirector project. A project can have various requirements for which testing much be performed. Tests which cover elements of the requirement are assigned to the requirement. For example, product initialization can be a requirement. All tests that involve initialization of the application being tested can be assigned to this requirement. For each requirement, it is possible to retrieve statistical data regarding the requirement base status and coverage status, such as the number of children and children statuses.
Req Properties
Object Properties
Property Name PossibleStatuses ReqCoverageStatus ReqSummaryStatus R/W R R R Description Returns a list of possible requirement statuses. Returns the status of a particular requirement. Returns a reference to the IReqSummaryStatus object. The object returns a summary of all statuses for a particular Receives the status and returns the number of related children nodes. Total amount of children nodes covered by requirement status.
SummaryStatuses TotalSummaryNodes
R R
224
Chapter 6 Req
HasCoverage
Boolean
IsFolder
R/W
Boolean
R/W R R R/W
Product R/W String
225
R/W R/W
Type String
Description Determines or indicates whether the requirement has been reviewed. Possible values are:
Status R String
Passed - All tests assigned to the requirement were passed. Failed - One or more of the tests assigned to the requirement were failed.
Req Methods
AddCoverage Method
Assigns a test to the current requirement and specifies the test step that applies to the requirement. Syntax Req.AddCoverage (long TestID, long Order)
226
Chapter 6 Req
Parameters
Parameter Name TestID Order Description Required. The ID of the test assigned to the requirement (long). Required. The test position in the requirement coverage list (long). Possible values are: Default None None
A number representing the requirement position. TDPOSITION_LAST [-4] - Indicates that the test is inserted last.
Returns A number indicating the actual position of the test in the requirement coverage list. When the test is inserted last, this indicates the test actual numerical position.
AddCoverageEx Method
Assigns all the tests in the specified subject folder to the current requirement. Syntax Req.AddCoverageEx (long SubjectID, long Order)
227
Parameters
Parameter Name SubjectID Order Description Required. The ID of the subject folder containing the tests to be added to the requirement (long). Required. The position of the first test in the folder in the requirement coverage list (long). Possible values are: Default None None
A number representing the requirement position. TDPOSITION_LAST [-4] - Indicates that the test is inserted last.
Returns A number indicating the actual position of the first test in the folder in the requirement coverage list. When the test is inserted last, this indicates the test actual numerical position.
GetCoverList Method
An IDispatch interface to a List object containing all tests covering the current requirement. Syntax Req.GetCoverList ([VARIANT_BOOL Recursive])
228
Chapter 6 Req
Parameters
Parameter Name Recursive Description Optional. If TRUE, GetCoverList returns a list of coverage tests for current requirement and all its children. Otherwise, the method returns a list of coverage tests only for the current requirement (boolean). Default FALSE
Returns An IDispatch interface to a List object containing all tests covering the current requirement.
Move Method
Moves a requirement to being a child of a specified father requirement in the requirements tree. Syntax Req.Move(long NewFatherId, long NewOrder) Parameters
Parameter Name Description Required. The ID of the designated new father requirement (long). Required. The requirement position in the requirement coverage list (long). Possible values are: Default None None
NewFatherId NewOrder
A number representing the requirement position. TDPOSITION_LAST [-4] - Indicates that the test is inserted last.
229
Returns None
RemoveCoverage Method
Removes a test from the list of tests covering the current requirement. Syntax Req.RemoveCoverage (VARIANT vTest [, VARIANT_BOOL Recursive]) Parameters
Parameter Name vTest Recursive Description Required. A test object or array of tests objects (long). Optional. If TRUE, the specified coverage is removed for all the requirements under the current one recursively. If FALSE, only the coverage at the current requirement is removed. (boolean). Default None FALSE
Returns None
IReqSummaryStatus Methods
None
IReqCoverageStatus Methods
None
230
Chapter 6 Req
Req Example
The following Visual Basic example retrieves the coverage test for a selected requirement. 1 Follow the procedure in Example 1 on page 222. 2 Add a list box to the form. 3 Add the following sub-routine:
Private Sub List1_Click() Dim FilterString As String Dim ReqId As Long Dim TestList As List Dim tst As Test
231
4 This program retrieves the requirements of a project. When a requirement is selected, it displays the coverage test in the second list box. Note that in this simple example, the requirements are set by their name without real support for duplicating names.
232
Chapter 6 TestFactory
TestFactory
IBaseFactory ITestFactory The TestFactory object is responsible for adding and removing tests to and from a TestDirector project. You can use the Item property to return an IDispatch interface to a Test object by test ID, full network path, or subject path in the subject tree. You can also use the NewList method to create a List object by specifying a filter. TestFactory also creates various types of graphs. The ITestFactory interface is derived from the IBaseFactory interface.
TestFactory Properties
Object Properties
Property Name RepositoryStorage R/W R Description Returns an ExtendedStorage object, that is connected by default to the test repository folder on the server side, and enables file system operation with a test repository.
233
The following variation exists for IBaseFactory property parameters when used with a TestFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the test ID (long).
TestFactory Methods
In addition to the methods listed below, TestFactory implements the methods in IBaseFactory. See IBaseFactory on page 126. The following variations exist for IBaseFactory method parameters when used with a TestFactory object.
Method Name AddItem Parameter Name ItemData Variation Identifies the test by one of the following:
The test name. An array consisting of the following elements: (0) Name - The test name (string, required). (1) Type - The test type (string, optional). The possible test types are detailed in the table below. (2) Tester - The name of the user that created the test (string, optional). The default value is the name of the user currently logged in (string, optional). (3) SubjectID - The ID of the subject folder in which to create the test (long, optional).
RemoveItem
ItemKey
Identifies the test by its ID (long) or an IDispatch interface to the Test object itself.
234
Chapter 6 TestFactory
235
BuildPerfGraph Method
Creates a graph object. For more information on Graph objects, see page 342. Syntax TestFactory.BuildPerfGraph([BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT FRDate] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: Default
SumOfField MaxCols
Filter FRDate
None None
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
236
Chapter 6 TestFactory
BuildSummaryGraph Method
Creates a test execution summary graph. This graph shows the number of tests executed in a test set according to test and test run information supplied by the user. All parameters are optional, so you can create a default test summary graph without passing any parameters. For more information on Graph objects, see page 342. Syntax TestFactory.BuildSummaryGraph ( [BSTR XAxisField] [,BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath] )
237
Parameters
Parameter Name XAxisField SumOfField GroupByField Description Optional. A database field representing the name of the graph x-axis (string). For internal use only. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: Default None None
MaxCols
Filter ForceRefresh
None FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
238
Chapter 6 TestFactory
BuildProgressGraph Method
Creates a test progress graph. This graph shows the number of tests in a test set executed over a period of time. The graph appears in line format. The xaxis represents the dates on which the tests were executed. The y-axis shows the total number of tests in the test set. All parameters are optional, so you can create a default test progress graph without passing any parameters. For more information on Graph objects, see page 342. Syntax TestFactory.BuildProgressGraph ( [BSTR GroupByField] [, BSTR SumOfField] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] ) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Default
SumOfField
239
Description Optional. Determines the interval type shown in the graph (long). Possible values are:
Default 0
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of defects as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: 1 0
Filter FRDate
None None
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
240
Chapter 6 TestFactory
BuildProgressGraphEx Method
The BuildProgressGraphEx method creates a graph object. This method contains all of the same features as the BuildProgressGraph method, with additional support for the ShowNullParents parameter. All parameters are optional, so you can create a default progress graph without passing any parameters. For more information on Graph objects, see page 342. Syntax ReqFactory.BuildProgressGraphEx ( [BSTR GroupByField] [, BSTR SumOfField] [, VARIANT_BOOL ByHistory] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] [, VARIANT_BOOL ShowNullParents] ) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. Determines whether to use history information to create the graph. Possible values are: Default
SumOfField ByHistory
TRUE
241
Description Optional. Determines the interval type shown in the graph (long). Possible values are:
Default 0
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of defects as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: 1 0
Filter FRDate
None None
ForceRefresh
FALSE
242
Chapter 6 TestFactory
Description Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique. Only for Requirements mode. Overrides the feature that prevents parent folders, which are not covered, from being viewed during Cover Status queries. A value of true allows these folders to appear.
Default FALSE
ShowNullParents
FALSE
243
BuildTrendGraph Method
Creates a graph that shows the number of status changes in the defects of a TestDirector project over a time period. The x-axis indicates the time intervals, and the y-axis indicates the number of status changes. For more information on Graph objects, see page 342. Syntax TestFactory.BuildTrendGraph([BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT FRDate] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Default
SumOfField MaxCols
Filter FRDate
None None
244
Chapter 6 TestFactory
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
TestFactory Example
The following Visual Basic example lists the test names for the project. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button and a list box to the form. 3 Add the following declarations to the global declarations at the top:
Dim TestF As TestFactory Dim TestList As List Dim tst As test
5 This simple program lists the test names for the project when you click the button.
245
Test
IBaseField IBaseFieldEx IBaseFieldExMail ITest The Test object represents a TestDirector planning test. You can use Test for all test-related actions. You can also use Test to call a DesignStep object for the current test, and a list of test sets in which the current test appears.
Test Properties
In addition to the properties listed below, Test implements the properties in IBaseField and IBaseFieldEx. See IBaseFactory on page 126 and IBaseFieldEx on page 123. Object Properties
Property Name DesignStepFactory ExtendedStorage LastRun Params Vcs R/W R R R R R Description Returns a reference to a DesignStepFactory object for the current test. Returns a reference to the ExtendedStorage object for the current test. Returns the IDispatch interface for the last Run object. Returns a reference to a StepParams object with the current test parameters. Returns a reference to the VCS version control object of this test.
246
Chapter 6 Test
String String
Boolean
R R/W R R/W
247
Test Methods
CoverRequirement Method
Specifies a test coverage requirement. Syntax Test.CoverRequirement ( VARIANT Req, long Order, VARIANT_BOOL Recursive ) Parameters
Parameter Name Req Description Required. Specifies the coverage requirement. This parameter can be the requirement ID (long) or an IDispatch interface to the Req object itself. Required. Determines the order position of the current test in the existing coverage list (long). Possible values are: Default None
Order
-4
Recursive
A number representing the requirement position. TDPOSITION_LAST [-4] - Indicates that the requirement is inserted last. None
If true, all child requirements will be covered by this test too (boolean).
Returns The real order position of the current test in the coverage list.
248
Chapter 6 Test
GetCoverList Method
Creates a list of all coverage requirements for the test. Syntax Test.GetCoverList() Parameters None Returns A list of all coverage requirements for the test.
RemoveCoverage Method
Removes a test from the list of tests covering the current requirement. Syntax Test.RemoveCoverage (VARIANT vTest [, VARIANT_BOOL Recursive]) Parameters
Parameter Name vTest Recursive Description Required. A test object or array of tests objects (long). Optional. If TRUE, the specified coverage is removed for all the requirements under the current one recursively. If FALSE, only the coverage at the current requirement is removed. (boolean). Default None FALSE
Returns None
249
Test Example
The following Visual Basic example details the requirements covering a selected test. 1 Follow the procedure in TestFactory Example on page 245. 2 Add another list box to the form. 3 Add the following sub-routine to the code:
Private Sub List1_Click() Dim ReqList As List Dim rq As Req Dim fltr As TDFilter
250
Chapter 6 Test
4 Run the program and click a test name in the first list box. The second list box will display the requirements covering this test. Note that the test is retrieved via its name and finds the coverage for the first test with this name.
251
TestExecStatus
ITestExecStatus TestExecStatus represents the execution status of the test currently running through the TSScheduler object. TSScheduler can return an ExecutionStatus object for the whole running session, and the user can enumerate through the ExecutionStatus object to get the test execution status for each test.
TestExecStatus Properties
Simple Data Type Properties
Property Name Message Status R/W R R Type String String Description Execution message. The test execution status. The possible values are:
252
Chapter 6 DesignStepFactory
DesignStepFactory
IBaseFactory The DesignStepFactory object adds and removes design steps to and from a Test object. For an explanation of design steps, see the DesignStep object description on page 256. For an explanation of Test objects, see page 246. You can use the Item property to return an IDispatch interface to a DesignStep object by Design Step ID.
DesignStepFactory Properties
In addition to the property described below, DesignStepFactory implements the properties in IBaseFactory. For more information, see IBaseFactory on page 126. Simple Data Type Properties
Property Name FetchLevel R/W R/W Type Integer Description Returns or sets the fetch level for the specified field. Passes the field name (string) to the property as a parameter.
The following variations exist for IBaseFactory property parameters when used with a DesignStepFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the design step ID (long).
253
DesignStepFactory Methods
DesignStepFactory implements the methods in IBaseFactory. For more information, see IBaseFactory on page 126. The following variations exist for IBaseFactory method parameters when used with a DesignStepFactory object.
Method Name AddItem RemoveItem Parameter Name ItemData ItemKey Variation NULL Identifies the design step by its ID (long) or an IDispatch interface to the DesignStep object itself.
DesignStepFactory Example
The following Visual Basic example details the design steps and the design step descriptions for a selected test. 1 Follow the procedure in TestFactory Example on page 245. 2 Add another list box to the form. 3 Add the following declarations to the global declarations at the top:
Dim Dim Dim Dim DesStepF As DesignStepFactory DSList As List ds As DesignStep fltr As TDFilter
254
Chapter 6 DesignStepFactory
5 Select a test from the first list box. This displays the design steps of the test, and the design step descriptions.
255
DesignStep
IBaseField IBaseFieldEx IDesignStep TestDirector tests are divided into design steps. These are detailed step-bystep instructions that describe the actions the tester (manual tests) or testing tool (automated tests) should perform as the test is executed. The DesignStep object represents a single design step in a test. The IDesignStep interface is derived from the IBaseFieldEx interface.
DesignStep Properties
In addition to the properties listed below, DesignStep implements the properties in IBaseField and IBaseFieldEx. See IBaseField on page 120 and IBaseFieldEx on page 123. Object Properties
Property Name LinkedParams LinkTest R/W R R/W Description Gets an IDispatch interface to the StepParams object with the linked test parameters. Gets/sets the test to be linked to this design step. The input parameter can be either a test ID or the IDispatch interface to the test. The returned value is an IDispatch interface to the test object. Returns the IDispatch interface to the test object to which the design step belongs.
ParentTest
256
Chapter 6 DesignStep
DesignStep Example
The following Visual Basic example adds a design step to a selected test. 1 Start with the code in DesignStepFactory Example on page 254. 2 Add a button and two text boxes to the form.
257
' Adding the new design step (last by default) Set DesStepF = tst.DesignStepFactory Set ds = DesStepF.AddItem(Null) ds.StepName = Text1.Text ds.StepDescription = Text2.Text ' Saving the changed field values to the server ds.Post ' Refreshing the steps list List1_Click End Sub 4 Click the second button to add a new design step to the selected test. The design step name and description are taken from the text boxes. Note that by default, the new design step is added as the last step. To change this, use the Order property of the DesignStep object.
258
Chapter 6 TestSetFactory
TestSetFactory
IBaseFactory IBaseFactoryEx ITestSetFactory The TestSetFactory object is responsible for adding TestDirector test sets. For an explanation of test sets, see the TestSetFolder object description on page 270. You can use the Item property to return an IDispatch interface to a TestSet object.
TestSetFactory Properties
The following variations exist for IBaseFactory property parameters when used with a TestSetFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the test set ID (long).
259
TestSetFactory Methods
In addition to the methods listed below, TestSetFactory implements the methods in IBaseFactory. See IBaseFactory on page 126. The following variations exist for IBaseFactory method parameters when used with a TestSetFactory object.
Method Name AddItem Parameter Name ItemData Variation
The test set name. An array consisting of the following elements: (0) Name - The test set name (string, required). (1) TestSetID - The ID of the test set folder in which to create the test set (long, optional).
RemoveItem
ItemKey
260
Chapter 6 TestSetFactory
BuildPerfGraph Method
Creates a graph object. For more information on Graph objects, see page 342. Syntax TestSetFactory.BuildPerfGraph(long TestSetID [, BSTR GroupByField] [, BSTR SumOfField] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name TestSetID GroupByField Description The unique ID of the test set. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Default None
SumOfField MaxCols
Filter FRDate
None None
261
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
BuildProgressGraph Method
Creates a test set progress graph. This graph shows the number of tests in all the test sets executed over a period of time. The graph appears in line format. The x-axis represents the dates on which the tests were executed. The y-axis shows the total number of tests in all the test sets. All parameters are optional, so you can create a default progress graph without passing any parameters. For more information on Graph objects, see page 342. Syntax TestSetFactory.BuildProgressGraph ( long TestSetID [, BSTR GroupByField] [, BSTR SumOfField] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] )
262
Chapter 6 TestSetFactory
Parameters
Parameter Name TestSetID GroupByField Description The unique ID of the test set. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. Determines the interval type shown in the graph (long). Possible values are: Default None
SumOfField MajorSkip
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of defects as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. 1 0
Filter FRDate
None None
263
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
BuildProgressGraphEx Method
The BuildProgressGraphEx method creates a graph object. This method contains all of the same features as the BuildProgressGraph method, with additional support for the ShowNullParents parameters. All parameters are optional, so you can create a default progress graph without passing any parameters. For more information on Graph objects, see page 342. Syntax TestSetFactory.BuildProgressGraphEx ( long TestSetID [,BSTR GroupByField] [, BSTR SumOfField] [, VARIANT_BOOL ByHistory] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] )
264
Chapter 6 TestSetFactory
Parameters
Parameter Name TestSetID GroupByField Description The unique ID of the test set. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. Determines whether to use history information to create the graph. Possible values are: Default None
SumOfField ByHistory
TRUE
MajorSkip
Optional. Determines the interval type shown in the graph (long). Possible values are:
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of defects as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. 1 0
Filter
None
265
Description Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default None
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
BuildSummaryGraph Method
Creates a requirement summary graph that shows the number of requirements reported in the TestDirector project database according to the defect tracking information specified by the user. All parameters are optional, so you can create a default requirement summary graph without passing any parameters. For more information on Graph objects, see page 342. Syntax TestSetFactory.BuildSummaryGraph (long TestSetID [, BSTR XAxisField] [, BSTR GroupByField] [, BSTR SumOfField] [, long MaxCols] [, VARIANT Filter] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] )
266
Chapter 6 TestSetFactory
Parameters
Parameter Name TestSetID XAxisField SumOfField GroupByField Description The unique ID of the test set. Optional. A database field representing the name of the graph x-axis (string). For internal use only. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: Default None None None
MaxCols
Filter ForceRefresh
None FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
BuildTrendGraph Method
Creates a graph that shows the number of status changes in the defects of a TestDirector project over a time period. The x-axis indicates the time intervals, and the y-axis indicates the number of status changes. For more information on Graph objects, see page 342.
267
Syntax TestSetFactory.BuildTrendGraph( long TestSetID [, BSTR GroupByField] [, BSTR SumOfField] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh], [VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name TestSetID GroupByField Description The unique ID of the test set. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: Default None
SumOfField MaxCols
Filter FRDate
None None
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
268
Chapter 6 TestSetFactory
TestSetFactory Example
The following Visual Basic example enumerates the test set names for the project. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button and a list box to the form. 3 Add the following declarations to the global declarations at the top:
Dim TestSetF As TestSetFactory Dim TestSetList As List Dim ts As TestSet
5 Run this program and click the button to list the test set names for the project.
Note: For an example including several Test Lab module interfaces, see page 324.
269
TestSetFolder
ITestSetFolder ISysTreeNode The TestSetFolder object manages the tests and test sets included in a particular test set folder. The object can be used to move, add, delete, or search for test set folders in the current project.
TestSetFolder Properties
Object Properties
Property Name Attachments Description FatherID FatherDisp HasAttachment SubNodes TestSetFactory ViewOrder R/W R R/W R R R R R R/W Description Returns a reference to the Attachment Factory object. Returns or sets the description of the test set folder. Returns the unique ID of the folder. Returns a reference to the FatherDisp object. Returns true if this folder has any attachments. Returns a reference to the SubNodes object. Returns a reference to the TestSetFactory object. Returns a reference to the ViewOrder object.
270
Chapter 6 TestSetFolder
TestSetFolder Methods
AddNodeDisp Method
Creates a new test set folder and returns a reference to the newly created folder. Syntax TestSetFolder.AddNodeDisp(BSTR NodeName) Parameters
Parameter Name NodeName Description The name of the folder to add. Default None
RemoveNodeEx Method
Delete a test set folder, with or without test sets included within. Syntax TestSetFolder.RemoveNodeEx( VARIANT Node, [, VARIANT_Bool DeleteTestSets])
271
Parameters
Parameter Name DeleteTestSets Node Description The value to determine whether or not to delete test sets along with their parent test set folder. The parent folder to delete. Default None None
Returns None
Move Method
Moves test sets from parent folder to another parent folder. Syntax TestSetFolder.Move(VARIANT Father) Parameters
Parameter Name Father Description The new parent folder of the selected test sets. Default None
Returns None
272
Chapter 6 TestSetFolder
FindTestSets Method
Searches for a test set in the current project. Syntax TestSetFolder.FindTestSets( BSTR Pattern [, VARIANT_Bool MatchCase] [, BSTR Filter] ) Parameters
Parameter Name Pattern MatchCase Filter Description A text pattern designating a folder or item of which to start the search in. Toggle case-sensitivity in search. Definition of the search filter. Default None False None
Refresh Method
Refreshes the contents of the test set folder, including its description and the description of its child folders. Syntax TestSetFolder.Refresh() Parameters None Returns None
273
TestSetTreeManager
ITestSetTreeManager The TestSetTreeManager object manages the test set tree and its related test set folders.
TestSetTreeManager Properties
Object Properties
Property Name Root Unattached R/W R R Description Returns a reference to the Root object. Returns a reference to the Unattached object.
ITestSetTreeFolder Methods
None
274
Chapter 6 TestSet
TestSet
IBaseField IBaseFieldEx IBaseFieldExMail ITestSet
The TestSet object represents a group of tests designed to meet a specific testing goal. For example, to verify that the application being tested is functional and stable, the tester can create a sanity test set that checks the application basic features. You can use the TSTestFactory property to obtain a TSTestFactory object to produce test set entries.
TestSet Properties
In addition to the properties listed below, TestSet implements the properties in IBaseField and IBaseFieldEx. See IBaseField on page 120 and IBaseFieldEx on page 123. Object Properties
Property Name ConditionFactory ExecEventNotifyByMailSettings R/W R R Description Returns a reference to a ConditionFactory object. Returns a reference to the ExecEventNotifyByMailSettings object associated with this test set. Returns a reference to the ExecSettings object associated with this test set. Returns a reference to an ExecutionSettings object containing the default settings.
ExecutionSettings TestDefaultExecutionSettings
R R
275
R/W R/W R
Description Returns or sets a reference to the father node object. Returns a reference to a TSTestFactory object.
TestSet Methods
ResetTestSet Method
Resets the NoRun status of each test of the TestSet. Syntax TestSet.ResetTestSet ( VARIANT_BOOL DeleteRuns ) Parameters
Parameter Name DeleteRuns Description Deletes previous runs of each test in a test set, if True. Default None
276
Chapter 6 TestSet
BuildPerfGraph Method
Creates a graph object. For more information on Graph objects, see page 342. Syntax TestSet.BuildPerfGraph([BSTR GroupByField] [, BSTR SumOfField] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Default
SumOfField MaxCols
Filter FRDate
None None
277
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
BuildProgressGraph Method
Creates a test set progress graph. This graph shows the number of tests in all the test sets executed over a period of time. The graph appears in line format. The x-axis represents the dates on which the tests were executed. The y-axis shows the total number of tests in all the test sets. All parameters are optional, so you can create a default test set progress graph without passing any parameters. For more information on Graph objects, see page 342. Syntax TestSet.BuildProgressGraph ( [BSTR GroupByField] [, BSTR SumOfField] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] )
278
Chapter 6 TestSet
Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. Determines the interval type shown in the graph (long). Possible values are: Default
SumOfField MajorSkip
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of defects as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. 1 0
Filter FRDate
None None
279
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
BuildSummaryGraph Method
Creates a test set summary graph. This graph shows the number of tests executed in all the test sets according to test and test run information supplied by the user. All parameters are optional, so you can create a default test set summary graph without passing any parameters. For more information on Graph objects, see page 342. Syntax TestSet.BuildSummaryGraph ( [BSTR XAxisField] [,BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath] )
280
Chapter 6 TestSet
Parameters
Parameter Name XAxisField SumOfField GroupByField Description Optional. A database field representing the name of the graph x-axis (string). For internal use only. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: Default None None
MaxCols
Filter ForceRefresh
None FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
281
BuildTrendGraph Method
Creates a graph that shows the number of status changes in the defects of a TestDirector project over a time period. The x-axis indicates the time intervals, and the y-axis indicates the number of status changes. For more information on Graph objects, see page 342. Syntax TestSet.BuildTrendGraph([BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT FRDate] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Default
SumOfField MaxCols
Filter FRDate
None None
282
Chapter 6 TestSet
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
PurgeExecutions Method
Purges all the running executions within the test set. Syntax TestSet.PurgeExecution() Returns None
StartExecution Method
Starts the execution controller. Syntax TestSet.StartExecution (BSTR ServerName)
283
Parameters
Parameter Name ServerName Description Required. The name of the server that the tests should be scheduled to run on (string). Default None
Returns A test set scheduler object filled with execution tests from the current test set, prepared to run the tests on the specified server.
CheckTestInstances Method
Returns tests in a particular test set, and the number of instances. Syntax TestSet.CheckTestInstances (BSTR TestIDs ) Parameters
Parameter Name TestIDs Description The ID of the Test. Default None
284
Chapter 6 TestSet
BuildProgressGraphEx Method
The BuildProgressGraphEx method creates a graph object. This method contains all of the same features as the BuildProgressGraph method, with additional support for the ShowNullParents parameters. For more information on Graph objects, see page 342. Syntax TestSet.BuildProgressGraphEx ( [BSTR GroupByField] [, BSTR SumOfField] [, VARIANT_BOOL ByHistory] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] ) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. Determines whether to use history information to create the graph. Possible values are: Default
SumOfField ByHistory
TRUE
285
Description Optional. Determines the interval type shown in the graph (long). Possible values are:
Default 0
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of defects as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: 1 0
Filter FRDate
None None
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
Indicates whether instances are grouped together by name or are shown individually based on location (path), in the created graph. A value of true shows the full path of each instance, thus treating them as unique.
286
Chapter 6 TestSet
Refresh Method
Refreshes the contents of the test set object. Syntax TestSet.Refresh() Parameters None Returns None
TestSet Example
The following Visual Basic example displays the conditions for a selected test set. 1 Start with the code in TestSetFactory Example on page 269. 2 Add another list box to the form.
287
Note: For an example including several Test Lab module interfaces, see page 324.
288
Chapter 6 ExecEventNotifyByMailSettings
ExecEventNotifyByMailSettings
IDispatch IExecEventNotifyByMailSettings
The ExecEventNotifyByMailSettings object represents the notification to be sent by email after a test has completed its run. A notification can be triggered by a successful completion of the test run or by a failure.
ExecEventNotifyByMailSettings Properties
Simple Data Type Properties
Property Name EmailTo UserMessage Enabled (VARIANT EventType) R/W R/W R/W R/W Type String String Boolean Description Returns or sets the email address. Returns or sets the user message. Returns or sets whether the notification is activated.
ExecEventNotifyByMailSettings Methods
Save Method
Uploads the notification settings to the server. Syntax ExecEventNotifyByMailSettings.Save([VARIANT_BOOL AutoPost]) Parameters
Parameter Name AutoPost Description Determines or indicates whether the notification is updated in the TestDirector project database immediately every time the field is changed. Default TRUE
289
Returns None.
290
Chapter 6 ExecSettings
ExecSettings
IExecutionSettings
The ExecSettings object represents the information on the execution of a test set including the date, time and actions to be taken after the completion of the tests. You can use the ExecutionSettings property of TSTest or TestSet to obtain an ExecSettings object.
ExecSettings Properties
Object Properties
Property Name OnExecEventScheduleActionParams (VARIANT EventType) R/W R Description Returns a reference to the ExecEventRestartActionParams object.
291
EXECEVENT_TESTFAIL [1] EXECEVENT_TESTFINISH [2] EXECEVENT_ENVIRONME NTFAIL[3] EXECEVENT_RUNTIMEDO UT [4]. Not in use. EXECEVENT_MANUAL_LU NCH[5]. Not in use.
292
Chapter 6 ExecEventActionParams
ExecEventActionParams
IExecEventActionParams
The ExecEventActionParams object represents the information on actions to be taken after the completion of a test set. You can use the ExecSettings.OnExecEventSchedulerActionParams property to obtain an ExecEventActionParams object.
ExecEventActionParams Properties
Simple Data Type Properties
Property Name OnExecEventScheduleAction (VARIANT EventType) Parameter([long Index]) R/W R/W R/W Type Integer Variant Description Returns or sets the action to be taken at finish of test. Not available.
ExecEventActionParams Example
This module shows how to get an ExecEventActionParams reference and display the scheduled action: Option Explicit Global td As TDAPIOLELib.TDConnection Global Const QC_URL = "http://Pride/qcbin" Global Const DOMAIN_NAME = "pemberley" Global Const PROJECT_NAME = "elizabeth" Global Const USER_NAME = "fitzwilliam" Global Const USER_PASSWORD = "darcy" Dim errMsg$
293
Sub Main() On Error GoTo InitQCErr 'Use global constants: ' QC_URL,DOMAIN_NAME,PROJECT_NAME ' USER_NAME, USER_PASSWORD Set td = New TDConnection td.InitConnection QC_URL td.ConnectProjectEx DOMAIN_NAME, PROJECT_NAME, _ USER_NAME, USER_PASSWORD Dim tSet As TDAPIOLELib.TestSet Set tSet = GetFirstTestSet See below for this function 'Use arbitrary event type for example Dim eType As TDAPIOLELib.tagTDAPI_EXECUTIONEVENT eType = EXECEVENT_TESTSETFINISH dim aType as string aType = TestSetActionTypeString(tSet, eType) See below for this function MsgBox aType
CleanClose: 'Close connections and release TDConnection reference Set tSet = Nothing td.DisconnectProject td.ReleaseConnection Set td = Nothing Exit Sub InitQCErr: errMsg = "InitQC Error" & vbCrLf & Err.Description MsgBox errMsg GoTo CleanClose End Sub
294
Chapter 6 ExecEventActionParams
Function GetFirstTestSet() As TDAPIOLELib.TestSet On Error GoTo GetFirstTestSetErr Dim tFact As TDAPIOLELib.TestSetFactory Dim TestSetList As List Dim ts As TDAPIOLELib.TestSet Set tFact = td.TestSetFactory Set TestSetList = tFact.NewList("") 'Get first test set Set ts = TestSetList.Item(1) MsgBox ts.Name Set GetFirstTestSet = ts Exit Function GetFirstTestSetErr: Set GetFirstTestSet = Nothing errMsg = "Error getting test set" & vbCrLf & Err.Description MsgBox errMsg End Function
Function TestSetActionTypeString(tSet As TDAPIOLELib.TestSet, _ ByVal EventType As TDAPIOLELib.tagTDAPI_EXECUTIONEVENT) _ As String Dim sType As String Dim execSets As TDAPIOLELib.ExecSettings Dim execEventParams As TDAPIOLELib.ExecEventActionParams Dim ActionType As TDAPIOLELib.tagTDAPI_EXECUTIONEVENTACTION 'Get the ExecSettings object Set execSets = tSet.ExecutionSettings 'Get the ExecEventActionParams object
295
Set execEventParams = _ execSets.OnExecEventSchedulerActionParams(EventType) ActionType = execEventParams.OnExecEventSchedulerAction Select Case ActionType Case EXECEVENTACTION_DEFAULT sType = "Do Nothing" Case EXECEVENTACTION_DONOTHING sType = "Do Nothing" Case EXECEVENTACTION_STOP sType = "Stop TestSet" Case EXECEVENTACTION_RESTART sType = "Restart TestSet" Case Else sType = "Unknown Event Type" End Select TestSetActionTypeString = "Action Type = " & sType End Function
296
Chapter 6 ExecEventRestartActionParams
ExecEventRestartActionParams
IOnExecEventRestartActionParams IDispatch
The ExecEventRestartActionParams object represents the information on actions to be taken during restart after the completion of a test set. You can use the ExecSettings.OnExecEventSchedulerActionParams property to obtain an ExecEventRestartActionParams object.
ExecEventRestartActionParams Properties
Simple Data Type Properties
Property Name OnExecEventScheduleAction (VARIANT EventType) Parameter([long Index]) CleanupTest NumberOfRetries R/W R/W R/W R/W R/W Type Integer Variant Variant Long Description Returns or sets the action to be taken at finish of test. Returns or sets parameters. ID of test to be done after restart. Number of retries.
297
ConditionFactory
IBaseFactory IConditionFactory The ConditionFactory object adds and removes conditions to and from an execution test. For an explanation of conditions, see the Customization object description on page 407. You can use the Item property to return an IDispatch interface to a Condition object by Condition ID. You cannot save an individually selected condition. Instead, you must use the Save method to save all changes to conditions. The IConditionFactory interface is derived from the IBaseFactory interface.
ConditionFactory Properties
Simple Data Type Properties The following variation exists for IBaseFactory property parameters when used with a ConditionFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the condition ID (long).
298
Chapter 6 ConditionFactory
ConditionFactory Methods
The following variations exist for IBaseFactory method parameters when used with a ConditionFactory object.
Method Name AddItem Parameter Name ItemData Variation Identifies the condition by an array consisting of the following elements:
(0) Type - The condition type (long, required), which can be one of the following: TDCOND_RUN [1] - A run condition. TDCOND_TIME [2] - A time condition.
(1) Source - For a run condition, the source condition ID (long, required). For a time condition, the date-time string (required). (2) Target - The target condition ID (long, required). (3) Value - The condition value (required). For a time condition, use a date-time string. For a run condition, use one of the following options: TDCOND_PASSED [2] TDCOND_FAILED [3]
RemoveItem ItemKey
299
Save Method
Saves all conditions and changes in the TestDirector project database. Syntax ConditionFactory.Save() Parameters None Returns None
ConditionFactory Example
The following Visual Basic example displays the conditions for a selected test set. 1 Follow the procedure in TestSetFactory Example on page 269. 2 Add another list box to the form. 3 Add these declarations on top:
Dim CondF As ConditionFactory Dim Cond As Condition Dim CondList As List
300
Chapter 6 ConditionFactory
301
Condition
ICondition The Condition object represents an execution test condition, i.e., a condition for a test to be executed. For example, a time condition is a time at which the test is executed. A run condition is a condition based on the result of a previous test (passed or failed). Changes for the condition are only saved in the TestDirector project after calling the Save method in the ConditionFactory object.
Condition Properties
Simple Data Type Properties
Property Name Description ID Source R/W R/W R R Type String Variant Variant Description Returns or sets a description of the condition. Returns the ID of the condition. Returns the source of the condition. For a run condition, the source is the source condition ID (long). For a time condition, the source is a date-time string. Returns the source test instance number of the condition. Returns the source test ID. Returns the Target ID of the condition. Returns the target test instance number of the condition. Returns the target test ID.
R R R R R
302
Chapter 6 Condition
R/W R
Type Integer
Value R/W Variant
Condition Methods
None
Condition Example
See ConditionFactory Example on page 300.
303
TSTestFactory
IBaseFactory The TSTestFactory object adds and removes execution tests (TSTest objects) in a TestDirector project. You can use the Item property to return an IDispatch interface to a TSTest object by Test ID.
TSTestFactory Properties
In addition to the property listed below, TSTestFactory implements the properties in IBaseFactory. See IBaseFactory on page 126. Simple Data Type Properties The following variations exist for IBaseFactory property parameters when used with an TSTestFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the test ID (long).
TSTestFactory Methods
TSTestFactory implements the methods in IBaseFactory. See IBaseFactory on page 126.
304
Chapter 6 TSTestFactory
The following variations exist for IBaseFactory method parameters when used with an TSTestFactory object.
Method Name AddItem Parameter Name ItemData Variation Identifies the test by one of the following:
The test ID (long or string). An array consisting of the following elements: (0) TestID - The test ID (long or string, required). (1) Tester - The name of the user that created the test (string, optional). The default value is the name of the user currently logged in.
RemoveItem
ItemKey
Identifies the test by its ID (long) or an IDispatch interface to the TSTest object itself.
TSTestFactory Example
The following Visual Basic example details TSTests for a test set. 1 Follow the procedure in TestSet Example on page 287. 2 Add the following declaration to the global declarations section:
Dim TStst As TSTest
305
4 Select a test set to display the TSTests in the second list box.
Note: For an example including several Test Lab module interfaces, see page 324.
306
Chapter 6 TSTest
TSTest
IBaseField IBaseFieldEx ITSTest The TSTest object represents an execution test in a TestDirector project. You can use TSTest to create a factory of all runs per test set (RunFactory object). The ITSTest interface is derived from the IBaseFieldEx interface.
TSTest Properties
Object Properties
Property Name ExecutionSettings LastRun Params RunFactory Test R/W R R R R R Description Returns a reference to the ExecSettings object for the current execution test. Returns a reference to the Run object of the last run. Returns a reference to the StepParams object for the current execution test. Returns a reference to a RunFactory object for the current execution test. Returns a reference to a Test object to use as a planning test for the current execution test.
307
Name
String
R/W R R R
TSTest Methods
TSTest implements the methods in IBaseField and IBaseFieldEx. See IBaseField on page 120 and IBaseFieldEx on page 123.
308
Chapter 6 TSTest
TSTest Example
The following Visual Basic example details the runs for a TSTest. 1 Follow the procedure in TSTestFactory Example on page 305. 2 Add a third list box to the form. 3 Add the following global declarations:
Dim Dim Dim Dim RunF As RunFactory rn As Run RunList As List TSTestList As List
5 Select a TSTest to display its run names in the third list box.
Note: For an example including several Test Lab module interfaces, see page 324.
309
RunFactory
IBaseFactory IRunFactory The RunFactory object creates test runs. For an explanation of test runs, see the Run object description on page 314. You can use the Item property to return an IDispatch interface to a Run object by Run ID. The IRunFactory interface is derived from the IBaseFactory interface.
RunFactory Properties
The following variations exist for IBaseFactory property parameters when used with a RunFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the run ID (long).
310
Chapter 6 RunFactory
RunFactory Methods
The following variations exist for IBaseFactory method parameters when used with a RunFactory object.
Method Name AddItem Parameter Name ItemData Variation Identifies the run by one of the following:
The name of the run (string). An array consisting of the following elements: (0) Name - The name of the run (string, required). (1) Tester - The name of the user responsible for the run (string, optional). (2) Location - The host name of the network host for the run (string, optional). The default value is the host name of the current machine.
Note: Following a call to AddItem with an array of parameters, the Run table field RN_PATH contains the value from in the array location (2), Location, if it was passed. If array location (2) was an empty string (""), then field RN_PATH contains "a_b" where "a" is the RN_CYCLE_ID and "b" is the RN_RUN_ID. Field RN_HOST is always empty following a call to the RunFactory's AddItem method. RemoveItem ItemKey Identifies the run by its ID (long) or an IDispatch interface to the Run object itself.
DeleteDuplicateRuns Method
Not implemented in this version.
311
Returns None
RunFactory Example
Example 1 The following Visual Basic example enumerates all runs for a project, and displays them with their status. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button and a list box to the form. 3 Add the following declarations to the global declarations at the top:
Dim RunF As RunFactory Dim rn As Run Dim RunList As List
5 Click the button to display all the runs of the project, and each run status.
312
Chapter 6 RunFactory
313
Run
IBaseField IBaseFieldEx IRun The Run object represents a test run. A test run stores information on each test performance during test execution. You can use Run to perform all runrelated activities.
Run Properties
In addition to the properties listed below, Run implements the properties in IBaseField. See IBaseField on page 120. Object Properties
Property Name ExtendedStorage Params (long SourceMode) R/W R R Description Returns the reference to the ExtendedStorage object for the current run. Returns a reference to the StepParams object of this run. The SourceMode parameter can take two values, indicating the source of the structure:
314
Chapter 6 Run
R/W R R R
Description Returns the test ID of the test that has been run. Returns the instance number of the test in the test set. Returns the ID of the test set to which the run belongs.
Run Methods
In addition to the methods described below, Run implements the methods in IBaseField. See IBaseField on page 120.
CopyDesignSteps Method
Copies design steps into the test run of an executed test. An executed test whose design steps were not copied into the test run does not show the design steps in the run. Syntax Run.CopyDesignSteps() Returns None
CopyStepsToTest Method
Copies all run execution steps, including new added steps, into the design steps of the corresponding planning test. Syntax Run.CopyStepsToTest() Returns None
315
ResolveStepsParameters Method
Updates the run steps values by resolving the parameter values during run time. Syntax Run.ResolveStepsParameters([VARIANT_BOOL UpdateLocalCache]) Parameters
Parameter Name UpdateLocalCache Description Optional. Indicates whether to update the local client cache with the changed values. Default -1
Returns None
Run Example
The following Visual Basic example adds a run to a TSTest. 1 Follow the procedure in TSTest Example on page 309. 2 Add a button and a label to the form. 3 Add the following sub-routine to the code:
Private Sub Command2_Click() ' Getting and displaying a unique run name Label1.Caption = RunF.UniqueRunName
316
Chapter 6 Run
4 Click the button to add the run to the current TSTest with a unique name. Note the use of AddItem with a parameter, instead of Null and Post. Also note that a run factory created from a TSTest object was used instead of the run factory from the TDConnection object, as no runs can be added to the global run factory.
Note: For an example including several Test Lab module interfaces, see page 324.
317
StepFactory
IBaseFactory The StepFactory object creates test steps for a Run object. For an explanation of test steps, see the Step object description on page 322. You can use the Item property to return an IDispatch interface to a Step object by Step ID.
StepFactory Properties
Simple Data Type Properties The following variations exist for IBaseFactory property parameters when used with a StepFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the step ID (long).
318
Chapter 6 StepFactory
StepFactory Methods
The following variations exist for IBaseFactory method parameters when used with a StepFactory object.
Method Name AddItem Parameter Name ItemData Variation Identifies the step by an array consisting of the following elements:
(0) Name - The step name (string, required). (1) Status - The step status (string, optional). Possible values are: NO_RUN - Default. The step is never executed. NOT_COMPLETED - Execution of the step has not been completed. FAILED - The step failed during test execution. PASSED - The step passed during test execution. N/A - The execution status for the step is not available. The user can define additional status values.
(2) Desc - A description of the step (string, optional). (3) Path - The file path of the step (string, optional). (4) LineNum - The step line number (string, optional). The default value is 0.
RemoveItem
ItemKey
Identifies the step by its index (long) or an IDispatch interface to the Step object itself.
319
StepFactory Example
In the following Visual Basic example, the steps of a selected run are displayed.
Note: For an example including several Test Lab module interfaces, see page 324.
1 Follow the procedure in RunFactory Example on page 312. 2 Add a second list box to the form. 3 Add the following global declarations at the top:
Dim StepF As StepFactory Dim stp As Step Dim StepList As List
320
Chapter 6 StepFactory
5 Select a run to display its steps and the status of each step in the second list box.
321
Step
IBaseField IBaseFieldEx IStep The Step object represents a test step in a test run. Each test step contains detailed information on the actions performed during each test run. This includes the IDs of the test and test run, the name of the test step, the status of the step, and the line number at which the step appears in the test script. The IStep interface is derived from the IBaseField interface.
Step Properties
In addition to the properties listed below, Step implements the properties in IBaseField. See IBaseField on page 120. Simple Data Type Properties
Property Name CreationMode DesignStepSource Name Status TestSource R/W W R R/W R/W R Type Integer Long String String Long Description Sets virtual run step creation mode; STD_Mode = 0 and Update_Mode = 1. Returns the ID of the design step from which this step originates. Returns or sets the step name. Returns or sets the step status. Returns the test ID of the test from which this step run originates.
Step Methods
Step implements the methods in IBaseField. See IBaseField on page 120.
322
Chapter 6 Step
Step Example 1
The following Visual Basic example adds a new step to the specified run. 1 Follow the procedure in StepFactory Example on page 320. 2 Add three text boxes and one button to the form. 3 Add the following sub-routine to the code:
Private Sub Command2_Click() Dim oStep as Step
4 Click the button to add a step to the run. The step properties are taken from the text boxes. Note that a step is added using a data array containing the properties.
Once you have added a step using the above procedure, you can use the step interface for updating the Status and Description fields.
323
4 Click the second list box to set that step to the actual result and its run to Failed.
324
Chapter 6 StepParams
StepParams
IStepParams The StepParams object manages test parameters for the following objects: DesignStep, Test, TSTest, and Run. A test parameter is a variable that replaces a fixed value in a test or a called test. For more information on test parameters, refer to the TestDirector User Guide.
StepParams Properties
Object Properties
Property Name Count ParamValue ParamExist ParamName BaseValue ParamType Type R/W R R/W R R Description Returns the number of parameters for the object. Returns the value of the ParamName parameter you specified. Checks whether the ParamName parameter you specified exists. Returns the name of the ParamName parameter in the list that you specified. Not in use. Not in use. Not in use.
StepParams Methods
AddParam Method
Adds a new parameter to the object. Syntax StepParams.AddParam([in]BSTR ParamName [, in]BSTR ParamType)
325
Parameters
Parameter Name ParamName Type Description Required. The name of the parameter. Set the value to text. Default None None
Returns None.
ClearParam Method
Clears a parameter value. Syntax StepParams.ClearParam([in]VARIANT vParam) Parameters
Parameter Name ParamName Description Required. The name of the parameter. Default None
Returns None.
DeleteParam Method
Deletes a parameter. Syntax StepParams.DeleteParam([in]BSTR ParamName)
326
Chapter 6 StepParams
Parameters
Parameter Name ParamName Description Required. The name of the parameter. Default None
Returns None
Save Method
Saves the value of the parameter. Syntax StepParams.Save() Returns None
Refresh Method
Refreshes the parameter data within the object. Syntax StepParams.Refresh() Returns None
327
BugFactory
IBaseFactory IBaseFactoryEx IBugFactory The BugFactory object adds and removes defect records to and from a TestDirector project. The IBugFactory interface is derived from the IBaseFactoryEx interface.
BugFactory Properties
Simple Data Type Properties The following variations exist for IBaseFactory property parameters when used with a BugFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the defect ID (long).
BugFactory Methods
The following variations exist for IBaseFactory method parameters when used with a BugFactory object.
Method Name AddItem RemoveItem Parameter Name ItemData ItemKey Variation Use the NULL parameter. Use the defect ID (long) or an IDispatch interface to the Bug object itself.
328
Chapter 6 BugFactory
BuildAgeGraph Method
The BuildAgeGraph method creates a graph that shows the lifetime of defects in a TestDirector project. The lifetime of a defect begins when it is reported, and ends when it is closed. All parameters are optional, so you can create a default defect age graph without passing any parameters. For more information on Graph objects, see page 342. Syntax BugFactory.BuildAgeGraph ( [,BSTR GroupByField][,BSTR SumOfField] [,long MaxAge] [,long MaxCols] [,VARIANT Filter] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_RESPONSIBLE, the graph breaks down defect age for each developer responsible for fixing defects. For internal use only. Optional. The maximum age (in Days) of defects included in the graph (long). A value of 0 signifies no age limit. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Default None
SumOfField MaxAge
MaxCols
Filter
None
329
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - To refresh the graph. FALSE - Not to refresh the graph. FALSE
BuildPerfGraph Method
Creates a graph object. For more information on Graph objects, see page 342. Syntax BugFactory.BuildPerfGraph([BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT FRDate] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Default
SumOfField MaxCols
330
Chapter 6 BugFactory
Description Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
BuildProgressGraph Method
The BuildProgressGraph method creates a graph that shows the accumulation of defects in a TestDirector project, or the estimated/actual amount of time taken to fix these defects, at specific points during a period of time. All parameters are optional, so you can create a default progress graph without passing any parameters. For more information on Graph objects, see page 342. Syntax BugFactory.BuildProgressGraph ( [BSTR GroupByField] [, BSTR SumOfField] [, VARIANT_BOOL ByHistory] [, long MajorSkip] [, long MinorSkip] [, long MaxCols] [, VARIANT Filter] [, VARIANT FRDate] [, VARIANT_BOOL ForceRefresh] [, VARIANT_BOOL ShowFullPath] )
331
Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. Determines whether to use history information to create the graph. Possible values are: Default
SumOfField ByHistory
TRUE
MajorSkip
Optional. Determines the interval type shown in the graph (long). Possible values are:
TDOLE_SKIP_DAYS [0] - Daily intervals. TDOLE_SKIP_WEEKS [1] - Weekly intervals. TDOLE_SKIP_MONTHS [2] - Monthly intervals. TDOLE_SKIP_YEARS [3] - Annual intervals.
For example, if the MajorSkip value is 0 and the MinorSkip value is 3, the x-axis of the graph displays the number of defects as of every three days. MinorSkip MaxCols Optional. Determines the length of the skip interval (long). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. 1 0
Filter
None
332
Chapter 6 BugFactory
Description Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default None
ForceRefresh
FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
BuildSummaryGraph Method
The BuildSummaryGraph method creates a graph that shows a summary of the number of defects in a TestDirector project, or the estimated/actual amount of time taken to fix these defects. All parameters are optional, so you can create a default defect summary graph without passing any parameters. For more information on Graph objects, see Graph on page 342. Syntax BugFactory.BuildSummaryGraph ( [,BSTR XAxisField] [,BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath] )
333
Parameters
Parameter Name XAxisField SumOfField GroupByField Description Optional. A database field representing the name of the graph x-axis (string). For internal use only. Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Determines whether or not to refresh graph data on the server side. Possible values are: Default None None
MaxCols
Filter ForceRefresh
None FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
334
Chapter 6 BugFactory
BuildTrendGraph Method
Creates a graph that shows the history of changes to specific Test Plan fields in a TestDirector project, for each time interval displayed. The x-axis indicates the time intervals, and the y-axis indicates the number of status changes. For more information on Graph objects, see page 342. Syntax BugFactory.BuildTrendGraph([BSTR GroupByField] [,BSTR SumOfField] [,long MaxCols] [,VARIANT Filter] [,VARIANT FRDate] [,VARIANT_BOOL ForceRefresh] [,VARIANT_BOOL ShowFullPath]) Parameters
Parameter Name GroupByField Description Optional. A database field representing the name of the graph y-axis (string). All data in the graph is grouped according to this parameter. For example, if the value of this parameter is BG_STATUS, the graph breaks down defects by defect status (such as open, closed, and fixed). For internal use only. Optional. The maximum number of groups represented in the graph (long). A value of 0 signifies no limit. Optional. An ITDFilter interface to a TDFilter object that sets the filter criteria for the graph. Optional. Specifies the date from which history records are reflected in the graph (date). Only defects with a change date after this date are reflected in the graph. Default
SumOfField MaxCols
Filter FRDate
None None
335
Description Optional. Determines whether or not to refresh graph data on the server side. Possible values are:
Default FALSE
ShowFullPath
TRUE - The graph is refreshed. FALSE - The graph is not refreshed. FALSE
FindSimilarBugs Method
Searches the TestDirector project defect summaries and descriptions for similar defects, according to a specified text pattern. Syntax BugFactory.FindSimilarBugs (BSTR Pattern [,long Ratio] ) Parameters
Parameter Name Pattern Ratio Description Required. Specifies the search text pattern (string). Optional. Specifies the percentage of similarity (long, 0-100). Default None 10
Returns An IDispatch interface to a List object containing all bugs that match the search criteria.
336
Chapter 6 BugFactory
BugFactory Example
The following Visual Basic example searches defects within the projects BugFactory object using a text pattern. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a text box, a button and a list box to the form, and add the following declarations to the global declarations at the top:
Dim BugF As BugFactory Dim bg As Bug Dim BugList As List
4 Click the button to display all the bugs resembling the pattern entered in the text box.
337
Bug
IBaseField IBaseFieldEx IBaseFieldExMail IBug The Bug object represents a defect discovered during test execution. The IBug interface is derived from the IBaseFieldExMail interface.
Bug Properties
List Properties
Property Name ChangeLinks R/W R Description For future use.
338
Chapter 6 Bug
Description Returns or sets the project to which the defect belongs. Returns or sets the status of the defect. Returns or sets a summary of the defect.
339
Bug Methods
In addition to the methods listed below, Bug implements the methods in IBaseField and IBaseFieldEx. For more information, see IBaseField on page 120 and IBaseFieldEx on page 123.
FindSimilarBugs Method
Searches the TestDirector project defect summaries and descriptions for similar defects, according to the current defect summary and description. Syntax Bug.FindSimilarBugs ( [long Ratio] ) Parameters
Parameter Name Ratio Description Optional. Specifies the search ratio threshold (percentage). Default 10
Returns An IList interface to a List object containing all defects that match the search criteria.
340
Chapter 6 Bug
Bug Example
The following Visual Basic example displays the properties of the selected defect. 1 Follow the procedure in BugFactory Example on page 337. 2 Add three labels to the form. 3 Add the following sub-routine to the code:
Private Sub List1_Click() Set bg = BugList.Item(List1.ListIndex + 1) Label1.Caption = bg.ID Label2.Caption = bg.Priority Label3.Caption = bg.Status End Sub
341
Graph
IGraph The Graph object represents a graph built through a method, such as BuildSummaryGraph. Each graph contains data points, columns, and rows. Each graph can perform drill-down operations and create lists of underlying objects. A drill-down operation is a procedure by which the user can select a specific portion of the graph and display detailed information on the data represented by that portion of the graph.
Graph Properties
Simple Data Type Properties
Property Name ColCount ColName (long Col) R/W R R Type Long String Description Returns the number of columns in the graph. Returns the name of the specified column. To specify the column, pass the column number to the property as a parameter (long). Returns the number of items in the specified column. To specify the column, pass the column number to the property as a parameter (long).
Long
342
Chapter 6 Graph
R/W R
Type Integer
Description Returns the column type of the specified column. To specify the column, pass the column number to the property as a parameter (long). Note that the possible column types are:
Normal column value [FixedSeriesTag = 0] Total column - for line graphs [TotalSeriesTag = 1] Custom category column [CustomSeriesTag = 2] Other - for more than maximum allowed columns [OtherSeriesTag = 3]
Long
Returns the data located in the specified cell. To specify the cell, pass the column number (long) and row number (long) to the property as parameters. Returns the total number of items represented in the graph. Returns the maximum value in the graph. Returns the number of rows in the graph. Returns the name of the specified row. To specify the row, pass the row number (long) to the property as a parameter.
R R R R
343
R/W R
Type Long
Description Returns the number of items in the specified row. To specify the row, pass the row number (long) to the property as a parameter. Gets the start date for the graph.
StartDate
Date
Graph Methods
DrillDown Method
Returns detailed information about the specified cell of the graph. Syntax Graph.DrillDown (VARIANT Col, VARIANT Row) Parameters
Parameter Name Col Row Description Required. The column number of the specified cell (long). Required. The row number of the specified cell (long). Default None None
Returns A list of objects representing the data in the specified cell of the graph. For example, in a defect graph, DrillDown returns a list of Bug objects.
MultiDrillDown Method
Returns detailed information about a graph area consisting of four sets of coordinates.
344
Chapter 6 Graph
Returns A list of objects representing the data in the specified areas of the graph.
Graph Example
The following Visual Basic example displays a generic text age graph. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button and a list box to the form. 3 Add the following declarations to the global declarations at the top:
Dim BugF As BugFactory Dim Grph As Graph Dim Str As String
345
346
Chapter 6 History
History
IHistory The History object lets you retrieve a list of history records for specified TestDirector objects, such as Test, Bug, Step, etc.
History Parameters
Object Properties
Property Name Filter R/W R Description Returns a reference to a TDFilter object for each history item.
History Methods
ClearHistory Method
Clears the history records using a filtering condition. Syntax History.ClearHistory ([BSTR SQLFilter]) Parameters
Parameter Name SQLFilter Description Required. A string containing an SQL filter statement, by which the history records will be deleted. Default
Returns None
347
NewList Method
Retrieves a filtered list of history data records. Syntax History.NewList (BSTR SQLFilter ) Parameters
Parameter Name SQLFilter Description Required. A string containing one of the following: Default None
Any field name. This returns all history records for the current object in which the specified field was changed. The format for the string is [FieldName]FieldName, for example, [FieldName]BG_STATUS. An empty string. This returns all history records for the current object.
Returns A list of all objects that match the search criteria. The list index starts from 1 (i.e., the first item it item(1), etc.).
348
Chapter 6 History
History Example
The following example displays the history records for a selected test. 1 Follow the procedure in Test Example on page 250. 2 Add the following global declarations to the top of the code:
Dim His As History Dim HisRec As HistoryRecord Dim HisList As List
4 Click a test to display its history records. The history records detail the field and the change.
349
HistoryRecord
IHistoryRecord The HistoryRecord object represents a single history change.
HistoryRecord Properties
Simple Data Type Properties
Property Name ChangeDate Changer FieldName NewValue ItemKey R/W R R R R R Type Date String String Variant Variant Description Returns the date of the change. Returns the name of the user that made the change. Returns the name of the database field that was changed (such as Status). Returns the new value of the field. Item key for changed item.
HistoryRecord Methods
None
HistoryRecord Example
See History Example on page 349.
350
Chapter 6 Alert
Alert
IAlert The Alert object informs the user of alerts which result from changes in certain tables, tests, etc. The alerts are notifications sent to the user based on the selection of preset rules, from the IRule object. Alerts may also be userdefined follow-ups to remind the user regarding the object, sent at a predetermined date.
Alert Properties
Object Properties
Property Name AlertDate AlertType Description ParentalEntityURL R/W R R R R Description Returns the date that the alert was generated. Returns the type of alert generated: Alert or Follow-up. Returns the description of the alert. Returns the location of the parental object that the alert/follow-up is related to. Returns the text that describes the alert.
Subject
351
Alert Methods
None
352
Chapter 6 HostFactory
HostFactory
IBaseFactory The HostFactory object creates host servers in a TestDirector project. For an explanation of host servers, see The Hosts Table - Testing Hosts on page 86. You can use the Item property to return an IDispatch interface to a Host object by Host Name. You can also return a group of hosts by using the Groups property to return an IDispatch interface to a HostGroupFactory object.
HostFactory Properties
The following variations exist for IBaseFactory property parameters when used with a HostFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the name of the host (string).
353
HostFactory Methods
The following variations exist for IBaseFactory method parameters when used with a HostFactory object.
Method Name AddItem Parameter Name ItemData Variation Identifies the host by an array consisting of the following elements:
RemoveItem ItemKey
(0) Name - The name of the host (string, required). (2) Desc - A description of the host (string, optional). (3) Server - The host remote execution server (string, optional).
HostFactory Example
The following Visual Basic example lists all the hosts in the project. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button and a list box to the form. 3 Add the following declarations to the global declarations at the top:
Dim HostF As HostFactory Dim HostList As List Dim hst As Host
354
Chapter 6 HostFactory
5 Click the button to display the project hosts in the list box.
355
Host
IBaseField IHost The Host object represents a single host server in a TestDirector project. For an explanation of host servers, see The Hosts Table - Testing Hosts on page 86. The IHost interface is derived from the IBaseField interface.
Host Properties
Simple Data Type Properties
Property Name Name Description RexServer R/W R R/W R Type String String String Description Returns the name of the host server. Returns/sets a description of the host server. Returns the server name as it appears on the LAN.
LockObject Method
Locks the Host object. Syntax Boolean Host.LockObject () Returns TRUE on success, False on failure.
UnLockObject Method
Unlocks the Host object.
356
Chapter 6 Host
Host Example
The following Visual Basic example adds a host to the project. 1 Follow the procedure in HostFactory Example on page 354. 2 Add a button and a text box to the form.
357
4 Enter an host name in the text box. Click the button to add the host to the project.
358
Chapter 6 HostGroupFactory
HostGroupFactory
IBaseFactory IHostGroupFactory The HostGroupFactory object creates and removes groups of host servers in a TestDirector project. For an explanation of host servers, see The Hosts Table - Testing Hosts on page 86. You can use the Item property to return an IDispatch interface to a HostGroup object. You can use the RemoveHost method to remove a host from all the groups in a project.
HostGroupFactory Properties
In addition to the property listed below, HostGroupFactory implements the properties in IBaseFactory. For more information, see IBaseFactory on page 126. Simple Data Type Properties The following variations exist for IBaseFactory property parameters when used with a HostGroupFactory object.
Property Name Item Parameter Name ItemKey Variation Represents the name of the group (string).
HostGroupFactory Methods
In addition to the methods listed below, HostGroupFactory implements the methods in IBaseFactory. For more information, see IBaseFactory on page 126.
359
The following variations exist for IBaseFactory method parameters when used with a HostGroupFactory object.
Method Name AddItem RemoveItem Parameter Name ItemData ItemKey Variation Identifies the group by its name (string). Identifies the group by its name (string).
RemoveHost Method
Removes the specified host from all groups in the TestDirector project. Syntax HostGroupFactory.Removehost ( HostName ) Parameters
Parameter Name HostName Description Required. The name of the host to remove. Default None
Returns None
360
Chapter 6 HostGroupFactory
HostGroupFactory Example
The following Visual Basic example displays the host groups in the project. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button and a list box to the form. 3 Add the following declarations to the global declarations at the top:
Dim HostGrF As HostGroupFactory Dim HostGr As HostGroup Dim HostGrList As List
5 Click the button to display the project hosts groups in the list box.
361
HostGroup
IBaseField IBaseFieldEx IHostGroup The HostGroup object represents a group of host servers in a TestDirector project. For an explanation of host servers, see The Hosts Table - Testing Hosts on page 86. You can use the AddHost property to add a new host to the current group.
HostGroup Properties
The following variations exist for IBaseFactory property parameters when used with a HostGroup object.
Property Name Item Parameter Name Name Variation Represents the name of the host group (string).
HostGroup Methods
AddHost Method
Adds a host to the host group. Syntax HostGroup.AddHost (VARIANT Val)
362
Chapter 6 HostGroup
Parameters
Parameter Name Description Required. Either the IDispatch interface to the host object, the host name(string) or a string array containing the host names you wish to add. Default None
Val
Returns None
RemoveHost Method
Removes a host to a group. Syntax HostGroup.RemoveHost (VARIANT Val) Parameters
Parameter Name Description Required. Either the IDispatch interface to the host object, the host name(string) or a string array containing the host names you wish to remove. Default None
Val
Returns None
NewList Method
Returns a list of all hosts in the group. Syntax HostGroup.NewList()
363
Returns List of all hosts in the group. The list index starts from 1 (i.e., the first item it item(1), etc.).
HostGroup Example
The following Visual Basic example displays the hosts for a selected host group. 1 Follow the procedure in HostGroupFactory Example on page 361. 2 Add another list box to the form. 3 Add the following global declarations to the top of the code:
Dim HostList As List Dim hst As Host
5 Select a host group to display its hosts in the second list box.
364
Chapter 6 VCS
VCS
IVCS The VCS object represents a Version Control System connection.
VCS Properties
Collection (List) Properties
Property Name Versions VersionsEx R/W R R Description Returns a list of version strings, representing all the versions in the object. Returns a list of IVersionItem interfaces for accessing the details of each version in the object. For more information, see the VersionItem object on page 373.
Object Properties
Property Name CheckoutInfo R/W R Description Returns a reference to a VersionItem object, containing the checkout information of the current object. Returns a reference to a VersionItem object, containing information about a specific version, specified by the Version parameter.
365
R/W R R R R
Description Indicates whether this object is checked out or in a get status. Indicates whether this object is locked (checked out). Returns the name of the locking user. The version the current user is viewing.
VCS Methods
AddObjectToVcs Method
Adds an object to the Version control database. When using an automated test, this method must be used after the test files are uploaded from the client to the server. Syntax VCS.AddObjectToVcs([BSTR Version] [,BSTR Comments]) Parameters
Parameter Name Version Comments Description Optional. Specifies the starting version number of the test (string). Optional. Comments pertaining to the object version (string). Default 1.1.1 Test Created in VCS.
Returns None
366
Chapter 6 VCS
CheckIn Method
Checks in an object. Syntax VCS.CheckIn(BSTR Version, BSTR Comments [,VARIANT_BOOL Remove] [,VARIANT_BOOL SetCurrent]) Parameters
Parameter Name Version Comments Remove Description Required. Specifies the starting version number of the object (string). Required. Comments pertaining to the object version (string). Optional. Indicates whether to physically remove the files from the file system. It is recommended not to use this option. Optional. Sets the version you are currently working with as the current one. It is recommended not to use this option. Default None None TRUE
SetCurrent
TRUE
Returns None
CheckOut Method
Checks out an object. Syntax VCS.CheckOut(BSTR Version, BSTR Comments, VARIANT_BOOL Lock [,VARIANT_BOOL ReadOnly] [ ,VARIANT_BOOL Sync])
367
Parameters
Parameter Name Version Comments Lock ReadOnly Description Required. Specifies the starting version number of the object (string). Required. Comments pertaining to the object version (string). Optional. Indicates whether to lock the object (check out status) or not (get status). Optional. Indicates whether the checked out files will be read only. It is recommended not to use this option. Optional. Indicates whether to synchronize with the test repository. This option is for internal use only. Default None None FALSE
Sync
TRUE
Returns None
ClearView Method
For future use. This method is not implemented in this version. Syntax VCS.ClearView([BSTR Version]) Parameters
Parameter Name Version Description Optional. Specifies the starting version number of the object (string). Default
Returns None
368
Chapter 6 VCS
DeleteObjectFromVCS Method
Deletes the object from the Version Control database. Syntax VCS.DeleteObjectFromVCS() Returns None
LockVcsObject Method
Locks the VCS object, changing its status from get (get latest version) to check out. The object must be in a get status to use this method. Syntax VCS.LockVcsObject() Returns None
Refresh Method
Refreshes the VCS object from the server to the client. Syntax VCS.Refresh() Returns None
SetCurrentVersion Method
Sets the VCS object current version. It is recommended not to use this method. Syntax VCS.SetCurrentVersion(BSTR Version)
369
Parameters
Parameter Name Version Description Required. Specifies the current version number of the object (string). Default None
Returns None
UndoCheckout Method
Undoes the check out operation, falling back to the current version on the server. Syntax VCS.UndoCheckout(VARIANT_BOOL Remove) Parameters
Parameter Name Remove Description Required. Indicates whether to remove the checked out files from the server file system. It is recommended to use TRUE for the value of this parameter (boolean). Default None
Returns None
ViewVersion Method
For future use. Syntax VCS.ViewVersion(BSTR Version)
370
Chapter 6 VCS
Parameters
Parameter Name Version Description Required. The version requested for viewing (string). Default None
VCS Example
In the following Visual Basic example a test is checked out, if it is not already checked out, and the locking user name is displayed. Note that you have to work with a project which is under version control for this example to work. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button and a label to the form. 3 Add the following declarations to the global declarations at the top.
Dim TestF As TestFactory Dim TestList As List
371
6 Select a test in the list box. Click the button to try to check out the test, and display the locking user name.
372
Chapter 6 VersionItem
VersionItem
IVersionItem The VersionItem object represents specific version information.
VersionItem Properties
Simple Data Type Properties
Property Name Time User Date IsLocked Version Comments R/W R R R R R R Type String String String Boolean String String Description Returns the check in time of the specific version. Returns the user name of the user performing the check in. Returns the check in date of the specific version. Indicates whether the specific version is checked out. Returns the checked in version. Returns the checked in comments of the specific version.
373
TreeManager
ITreeManager The TreeManager object represents the TestDirector system tree, containing a subject tree and all hierarchical field trees. You can use the TreeRoot property to create a tree root node (SysTreeNode object) by Root Name. For example, TreeRoot["Subject"] retrieves the root of TestDirector subject tree. For more information on SysTreeNode objects, see page 377.
TreeManager Properties
Collection (List) Properties
Property Name RootList ([short Val]) R/W R Description Returns a list of available trees, using the optional Val parameter. Val represents the range of trees to be returned. Possible values are:
TDOLE_ALL [0] - Default. Includes all tree roots. TDOLE_SUBJECT [1] - Only includes subject tree roots. TDOLE_NOTSUBJECT [2] - Only includes tree roots that are not subject roots (includes all customization lists).
374
Chapter 6 TreeManager
Object Properties
Property Name NodeById (long NodeId) NodeByPath (BSTR Path) R R/W R Description Returns a reference to a SysTreeNode object representing a tree node, using the NodeId parameter. NodeId represents the node ID. Returns a reference to a SysTreeNode object representing a tree node, using the Path parameter. Path represents the tree path of the node (a string separated by slashes). Returns a reference to a SysTreeNode object representing a root node, using the RootName parameter. RootName represents the name of the node.
TreeManager Methods
None
375
TreeManager Example
The following Visual Basic example displays all the tree roots for a project. 1 Add the TreeView component to the components bar, by selecting Project > Components, and marking the Microsoft Windows Common Controls 6 (SP6) option. 2 Follow the procedure in Example 3 - Base Example on page 151. 3 Add a button and a TreeView component to the form. 4 Add the following global declarations:
Dim tm As TreeManager Dim TreeList As List
The code uses the RootList property to get the names of all the trees in the project.
376
Chapter 6 SysTreeNode
SysTreeNode
ISysTreeNode The SysTreeNode object represents a system folder, i.e., a tree node in the TreeManager object. For more information on TreeManager objects, see page 374.
SysTreeNode Properties
Object Properties
Property Name Child (long Index) R/W R Description Returns a reference to a SysTreeNode object representing a sub-folder of the current folder, using the Index parameter. Index represents the child level of the folder. Returns a reference to a SysTreeNode object representing the current folder parent folder.
Father
377
TDOLE_NODE_SYSTEM [0] - System folder. The folder cannot be modified, and sub-folders cannot be added or removed. TDOLE_NODE_READONLY [1] Read-only folder. The only operation the folder can perform is to add and delete sub-folders. TDOLE_NODE_CHANGEABLE [2] Changeable folder. The folder can perform any operation except delete. TDOLE_NODE_FULLACCESS [3] Full access folder. All operations are allowed.
Count DepthType
R R
Long Integer
Returns the number of sub-folders. Returns the depth type of the folder. Possible values are:
TDOLE_LEAF_TYPE [0] - The folder is a tree leaf, and cannot have subfolders. TDOLE_LIST_TYPE [1] - The folder has only one level of sub-folders. TDOLE_TREE_TYPE [2] - The folder has more than one level of sub-folders.
R/W R R
Returns or sets the folder name. Returns the folder ID. Returns the folder tree path (string separated by slashes), starting from the tree root.
378
Chapter 6 SysTreeNode
SysTreeNode Methods
AddNode Method
Adds a sub-folder to the current folder. Syntax SysTreeNode.AddNode (BSTR NodeName) Parameters
Parameter Name NodeName Description Required. The new folder name (string). Default None
FindChildNode Method
Finds a sub-folder. Syntax SysTreeNode.FindChildNode (BSTR ChildName ) Parameters
Parameter Name ChildName Description Required. The folder name (string). Default None
379
FindChildren Method
Finds sub-folders according to a specified search text pattern. Syntax SysTreeNode.FindChildren (BSTR Pattern [,VARIANT_BOOL MatchCase] [,BSTR Filter] ) Parameters
Parameter Name Pattern MatchCase Filter Description Required. Specifies the search text pattern (string). Optional. Indicates whether the search operation should be case sensitive (boolean). Optional. A logical filter to narrow the search. No SQL code necessary to utilize parameter. Default None FALSE
Returns An IList interface to a List object containing sub-folders that match the search criteria.
NewList Method
Creates a list containing the first level of sub-folders of the current folder. Syntax SysTreeNode.NewList() Parameters None Returns An IList interface to a List object containing the first level of the current folder sub-folders (SysTreeNode objects). The list index starts from 1 (i.e., the first item it item(1), etc.).
380
Chapter 6 SysTreeNode
Post Method
Posts all changed values to the Test Director database. Syntax SysTreeNode.Post() Parameters None Returns None
Refresh Method
Refreshes the node data, i.e., the node name, description, and number of children. Syntax SysTreeNode.Refresh() Parameters None Returns None
RemoveNode Method
Removes the specified folder. Syntax SysTreeNode.RemoveNode (VARIANT Node)
381
Parameters
Parameter Name Node Description Required. The name (string) or index (long) of the folder, or an IDispatch interface to the SysTreeNode object representing the folder. Default None
Returns None
SysTreeNode Example
The following Visual Basic example shows the first level of all the trees in the project. 1 Follow the procedure in TreeManager Example on page 376. 2 Add a button to the form. 3 Add these global declarations:
Dim STNode As SysTreeNode Dim NodeList As List Dim node As MSComctlLib.node
382
Chapter 6 SysTreeNode
5 Click the first button to add the root names. Click the second button to add the children nodes to each root. To display the children nodes, double-click a root name.
383
SubjectNode
ISysTreeNode ISubjectNode The SubjectNode object represents a subject folder in a TestDirector subject tree. The ISubjectNode interface is derived from the ISysTreeNode interface, and contains all of its methods and properties as well as those listed below.
SubjectNode Properties
Object Properties
Property Name Attachments R/W R Description Returns a reference to a group of attachments (AttachmentFactory object) for the current subject folder. Returns a reference to a TestFactory object for the current subject folder.
TestFactory
384
Chapter 6 SubjectNode
SubjectNode Methods
FindTests Method
Finds tests within the current subject folder that match the specified text pattern. Syntax SubjectNode.FindTests (BSTR Pattern, [VARIANT_BOOL MatchCase] [, BSTR Filter] ) Parameters
Parameter Name Pattern Description Required. Specifies the search text pattern (BSTR). Any test in which the search text pattern is embedded in its name will be selected. Optional. Indicates whether the search operation should be case sensitive (boolean). Optional. A logical filter to narrow the search. No SQL code necessary to utilize parameter. Default None
MatchCase Filter
FALSE
Returns An IDispatch interface to a List object containing tests that match the search criteria.
Move Method
Moves the current tree mode to be under the specified father. Syntax SubjectNode.Move (VARIANT Father)
385
Parameters
Parameter Name Father Description Required. Either the node object or node ID under which you want the tree mode. Default None
Returns None
RemoveSubjectNode Method
Removes the specified node from the subject tree. Syntax SubjectNode.RemoveSubjectNode (VARIANT Node [,VARIANT_BOOL DeleteTests]) Parameters
Parameter Name Node Description Required. Either the node object, node ID, or node name for the node that you want to remove. The node name search is done nonrecursively. Optional. Indicates whether to delete the tests under that node. Default None
DeleteTests
FALSE
Returns None
386
Chapter 6 SubjectNode
SubjectNode Example
In the following Visual Basic example, the project subject tree structure is built and displayed. 1 Follow the procedure in TreeManager Example on page 376. 2 Add these global declarations at the top:
Dim SubjNode As SubjectNode Dim nd As MSComctlLib.Node
387
5 Click the button to display subject tree root. To display the children nodes, double-click a node.
388
Chapter 6 SubjectNode
5 Enter a pattern in the text box. Click the button to display the tests matching the pattern.
389
Settings
ISettings The Settings object represents a configuration file on the user side that enables users to save settings in various user-defined categories. If the object is manufactured using the UserSettings property of the ITDConnection interface, the settings are only available to the user who saves them. If the object is manufactured using the CommonSettings property of the ITDConnection interface, the settings are available to all users.
Settings Properties
Collection (List) Properties
Property Name EnumItems R/W R Description Returns an IList interface to a list containing the settings items names as strings.
390
Chapter 6 Settings
Settings Methods
Close Method
Closes the current category. Syntax Settings.Close() Parameters None Returns None
DeleteCategory Method
Deletes Current Setting Folder. Syntax DeleteCategory (BSTR Category ) Parameters
Parameter Name Category Description Required. Specifies the name of the category to delete (string). Default None
Returns None
DeleteValue Method
Deletes the specified value.
391
Returns None
Open Method
Opens the specified category. Syntax Settings.Open (BSTR Category) Parameters
Parameter Name Category Description Required. Specifies the name of the category to open (string). Default None
Returns None
Post Method
Posts the new/changed categories to server. Syntax Settings.Post()
392
Chapter 6 Settings
Settings Example
The following Visual Basic example sets and retrieves the settings values. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add two buttons, two text boxes and a label to the form. 3 Add the following global declaration at the top:
Dim Sett As Settings
6 When the first button is clicked, the example adds a new setting named by the first text box, with a value taken from the second text box.
393
7 Click the second button to display the value of the category from the first text box in the label.
394
Chapter 6 TSScheduler
TSScheduler
ITSScheduler TSScheduler is responsible for executing selected automated tests.
TSScheduler Properties
Object Properties
Property Name ExecutionStatus R/W R Description Returns an ExecutionStatus object.
R/W
String
395
TSScheduler Methods
Run Method Executes specified tests. Syntax TSScheduler.Run(VARIANT TestData) Parameters
Parameter Name TestData Description Optional. Specifies the IDs of the tests to run. Either a series of test IDs separated by commas, or a list of test IDs (string). Default None
Returns None Stop Method Stops the execution of specified tests. Syntax TSScheduler.Stop(VARIANT TestData) Parameters
Parameter Name TestData Description Optional. Specifies the IDs of the tests to stop running. Either a series of test IDs separated by commas, or a list of test IDs (string). Default None
Returns None
396
Chapter 6 ExecutionStatus
ExecutionStatus
IExecutionStatus ExecutionStatus represents the execution status of the scheduler. The user can scan through each test in the scheduler and find out its status.
ExecutionStatus Properties
Object Properties
Property Name Item (long Index) _NewEnum R R/W R Description Returns the enumerator element for the specified index. Passes the element index as the Index parameter. Returns the IUnknown interface for the IEnumVARIANT enumerator of the elements.
397
ExecutionStatus Methods
RefreshExecStatusInfo Method
Refreshes the execution status from the execution controller. Syntax ExecutionStatus.RefreshExecStatusInfo(VARIANT TestData, VARIANT_BOOL Force) Parameters
Parameter Name TestData Force Description Required. Reserved for future use. Use NULL. Forces refresh for all running tests (boolean). Default None None
Returns None
EventsList Method
Gets the list of the execution events. Syntax ExecutionStatus.EventsList() Parameters None Returns An IList interface to a list object containing the ExecEventInfo objects of the events.
398
Chapter 6 ExecEventInfo
ExecEventInfo
IExecEventInfo ExecEventInfo retrieves the execution information of the scheduler. The user can scan through each test in the scheduler and find out what its execution information is. Options of events come from the EventsList method in the ExecutionStatus object.
ExecEventInfo Properties
Simple Data Type Properties
Property Name EventDate EventParam EventTime EventType R/W R R/W R R Type String String String Long Description Returns the date. Returns or set the parameter name. Returns the time Return the type
ExecEventInfo Methods
None
399
Rule
IRule IRuleManager The Rule object manages the rules associated with each project. Alerts are generated based on the properties of the Rule table, and only if the particular rule is enabled. Only the IsActive and ToMail Rule properties can be updated.
Rule Properties
Object Properties
Property Name Description ID IsActive Rules ToMail R/W R R R/W R R/W Description Returns the rule description. Returns the ID of the rule Indicates if the rule is active. Returns a list of the rules of the current project. Indicates if the alert is to be sent via e-mail.
Rule Methods
Post Method
Updates the changes to the Rules object to the server. Without using this method, changes to the rules will not be reflected in the server. Syntax Rule.Post () Parameters None
400
Chapter 6 Rule
Returns None
GetRule Method
References the Rule object and returns the rule associated to the ID. Syntax Rule.GetRule(long ID) Parameters
Parameter Name ID Description The ID of the rule Default None
401
CacheMgr
ICacheMgr The CacheMgr object is used to manage the system cache, in conjunction with the ExtendedStorage class of objects. The object manages the files that are placed in cache through downloading, uploading, and so forth, and ensures that old files are purged when the cache folder becomes too large.
Cache Properties
Object Properties
Property Name IsRunning R/W R Description Indicates whether ICacheMgr is currently running.
CacheMgr Methods
Run Method
Processes the ICacheMgr object, which runs the cache manager thread and returns immediately, without knowledge of the user. Syntax CacheMgr.Run() Parameters None Returns None
SetFileTime Method
Configures the ICacheMgr object to use the date of download from the server instead of the access date, when determining older files for deletion.
402
Chapter 6 CacheMgr
Returns None
403
ActionPermission
IActionPermission The ActionPermission object is used to determine whether a specified action can be performed by users.
ActionPermission Properties
Simple Data Type Properties
Property Name ActionEnabled (VARIANT ActionIdentity [, VARIANT ActionTarget]) R/W R Type Boolean Description Indicates whether or not the specified action can be performed by the user. This property takes two parameters, as detailed below.
ActionTarget
None
404
Chapter 6 ActionPermission
ActionPermission Methods
None
ActionPermission Example
In the following Visual Basic code, a query is made to determine whether the current user is permitted to perform a selected action. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add a button, a combo box and a label to the form. 3 Add the following sub-routines:
Private Sub Command1_Click() Dim cmd As Command Dim recSet As Recordset
405
4 Click the button to fill in the combo box with the available actions. Select an action from the combo box to determine whether this action is permitted for the current user.
406
Chapter 6 Customization
Customization Objects
These objects are used for system customization.
Customization
ICustomization The Customization object is the starting point for the TestDirector customization objects. These objects are used to perform administrative customization tasks, such as adding users to user groups, defining user-defined fields, and defining user access privileges. The first method to call with Customization is Load. This loads all customization data from the server. You can then use the Customization properties to create specific customization objects. When you are finished, call the Commit method to post all customization changes to the project database.
Customization Properties
Object Properties
Property Name Actions Fields Lists Modules Permissions R/W R R R R R Description Returns a reference to a CustomizationActions object. Returns a reference to a CustomizationFields object. Returns a reference to a CustomizationLists object. Returns a reference to a CustomizationModules object. Returns a reference to a CustomizationPermissions object.
407
R/W R R
Customization Methods
Commit Method
Posts all customization data changes to the TestDirector project database. Syntax Customization.Commit() Parameters None
408
Chapter 6 Customization
Returns None
Load Method
Loads all customization data from the server. This includes actions, fields, lists, modules, permissions, users, and user groups. Syntax Customization.Load() Parameters None Returns None
Customization Example
The following Visual Basic example demonstrates the usage of Customization methods and properties, by changing a user field label. 1 Follow the procedure in Example 3 - Base Example on page 151. 2 Add two buttons and a list box to the form.
409
+ " "+CustField.UserLabel)
Next End Sub Private Sub Command2_Click() Set CustField = CustFields.AddActiveField("BUG") CustField.UserLabel = "User Defined Field" Cust.Commit List1.Clear For Each CustField In FieldList List1.AddItem (CustField.ColumnName + " " _
+ CustField.UserLabel)
Next End Sub
4 Click the first button to display a list of the table fields and their labels. Click the second button to change the label of a user defined field and redisplay the list.
410
Chapter 6 CustomizationActions
CustomizationActions
ICustomizationActions The CustomizationActions object holds a collection of all CustomizationAction objects in the TestDirector project. For more information, see CustomizationActions object description on page 411.
CustomizationActions Properties
Collection (List) Properties
Property Name Actions R/W R Description Returns a list of CustomizationAction objects.
Object Properties
Property Name Action (BSTR Name) R/W R Description Returns a reference to the CustomizationAction object representing the specified action. Passes the action name (string) to the property as a parameter.
CustomizationActions Methods
None
411
CustomizationAction
ICustomizationAction The CustomizationAction object represents a type of user action, such as adding (AC_ADD_BUG) or deleting (AC_DELETE_BUG) a bug. Actions are listed in the AC_ACTION_NAME field of the Actions table. The CustomizationAction object is used to determine which user groups can perform the action represented by the object.
CustomizationAction Properties
Collection (List) Properties
Property Name Groups R/W R Description Returns a list of CustomizationUsersGroup objects representing the user groups for which the current action is allowed.
Object Properties
Property Name OwnerGroup R/W R/W Description Returns or sets a reference to the CustomizationUsersGroup object representing the user group that owns the action.
412
Chapter 6 CustomizationAction
Boolean
Boolean
Name Updated
R R/W
String Boolean
413
CustomizationAction Methods
AddGroup Method
Adds a user group to the list of user groups for which the current action is allowed. Syntax CustomizationAction.AddGroup (VARIANT Group) Parameters
Parameter Name Group Description Required. The name of the user group to be added (string) or an IDispatch interface to the CustomizationUsersGroup object representing the user group. Default None
Returns None
414
Chapter 6 CustomizationAction
RemoveGroup Method
Removes the specified user group from the list of groups for which the current action is allowed. Syntax CustomizationAction.RemoveGroup (VARIANT Group) Parameters
Parameter Name Group Description Required. The name of the user group to be removed (string) or an IDispatch interface to the CustomizationUsersGroup object representing the user group. Default None
Returns None
415
CustomizationFields
ICustomizationFields The CustomizationFields object holds a collection of all CustomizationField objects in the TestDirector project. For an explanation of the CustomizationField object, see the CustomizationField object description on page 419. You can use the AddActiveField method to add a user-defined field. This method returns a CustomizationField object representing the first available field in the specified table, which then becomes an active field. You can add up to 99 user-defined fields and 3 memo fields to each table, depending on the database used.
CustomizationFields Properties
Collection (List) Properties
Property Name Fields (BSTR TableName) R/W R Description Returns a list of all user-defined fields in the table specified by the TableName parameter. If this parameter is not specified, Fields returns a list of all user-defined fields in all tables.
Object Properties
Property Name Field (BSTR TableName, BSTR FieldName) FieldExists (BSTR TableName, BSTR FieldName) R R/W R Description Returns a reference to the CustomizationField object specified by the TableName and FieldName parameters. Returns a reference to the FieldExists object specified by the TableName and FieldName parameters.
416
Chapter 6 CustomizationFields
CustomizationFields Methods
AddActiveField Method
Finds the first free, non-active field in the specified table, signs the field as active, and returns the CustomizationFields object representing the field. The TableName parameter can be the name of any TestDirector table that includes user-defined fields. For a description of the TestDirector tables and fields, see Chapter 4, TestDirector Projects Data Structure. Syntax CustomizationFields.AddActiveField (BSTR TableName ) Parameters
Parameter Name TableName Description Required. The name of the table to which to add the active field (string). Default None
Returns An IDispatch interface to a CustomizationField object representing the newly active field.
AddActiveMemoField Method
This method creates a new memo field in a particular table. For a description of the TestDirector tables and fields, see Chapter 4, TestDirector Projects Data Structure. Syntax CustomizationFields.AddActiveMemoField (BSTR TableName )
417
Parameters
Parameter Name TableName Description Required. The name of the table to which to add the active field (string). Default None
Returns None
418
Chapter 6 CustomizationField
CustomizationField
ICustomizationField The CustomizationField object represents a user-defined field. The following TestDirector tables include user-defined fields: Bug (defects), Req (requirements), Run (test runs), Testcycle (test sets), Step (test steps), and Test (tests). For example, a user can define a field in the Tests table for recording the version of the application on which the test is to be performed. For a description of the TestDirector tables and fields, see Chapter 4, TestDirector Projects Data Structure.
CustomizationField Properties
Object Properties
Property Name List R/W R/W Description Sets/gets the IDispatch interface to the list this field contains. In a get operation, if the field contains a list, returns a reference to the CustomizationList object representing the list assigned to the field. If the field does not contain a list, returns NULL.
419
R/W R/W
Type Long
Description Returns or sets the size of the current field in the database. (For BLOB fields, the size of the field in the database is specified as -1.) Returns or sets the bit mask that determines which user groups can modify the field (long). Note: It is recommended that you use the CustomizationPermissions class instead of setting this property. Indicates or specifies if the field is active. Indicates or specifies if the field saves the Tree Node ID, rather than the passed value. Possible values are:
GrantModifyMask
R/W
Long
IsActive IsByCode
R/W R/W
Boolean Boolean
IsCanFilter IsCustomizable R/W R/W Boolean Boolean
TRUE - Available values for the current field are node names for the field tree root. FALSE - The field uses the passed value.
Indicates or specifies if the field is filter-enabled. Indicates or specifies if the field is shown in the customization user interface. Indicates or specifies if the field is editable. Indicates or specifies if the field stores its change history. Indicates or specifies if the field stores its last value. Indicates or specifies if the field is a database key field.
420
Chapter 6 CustomizationField
R/W R/W
Type Boolean
Description Indicates or specifies if users on the list to be notified of changes are notified when the field is changed. Indicates or specifies if the field is required. Indicates or specifies if the field is a system field. Indicates whether a summation of this field can be obtained for graph presentation. Indicates whether this field has a transition logic. Indicates or specifies if the field requires verification. Indicates whether this field is visible for the group mask in the Add Defect dialog box. Returns or sets the database key order. Indicates a field was created but not posted to the server. Returns or sets the bit mask that determines whether the field can be modified by its owner only, for every group. Note: It is recommended that you use the CustomizationPermissions class instead of setting this property. If the field contains a list, returns or sets the ID of the list root node. If the field does not contain a list, returns NULL. Gets/sets the database column name.
RootId
R/W
Variant
TableName
String
421
R/W R/W
Type Long
Description Returns or sets the field data type. Possible values are:
Updated R/W Boolean
TDOLE_LONG [0] TDOLE_ULONG [1] TDOLE_FLOAT [2] TDOLE_STRING [3] TDOLE_MEMO [4] TDOLE_DATE [5] TDOLE_TIMESTAMP [6] TDOLE_TREENODE [7] TDOLE_USER_LIST [8] TDOLE_TESTSET_LIST [9] TDOLE_HOST_LIST [10] TDOLE_SUBJECT_TREENODE [11]
As a read property, indicates whether the object update flag is set. The update flag is automatically set if the object has been modified since the last download from the server. As a write property, sets (TRUE) or removes (FALSE) the object update flag. Returns or sets the user column type. Returns or sets a user-defined label. Indicates whether this field is under version control. Currently eligible only for fields in the TEST table. Gets/sets the visibility bit mask for user groups. Determines which groups can see this field. Note: It is recommended that you use the CustomizationPermissions class instead of setting this property.
VisibleForGroups
R/W
Long
422
Chapter 6 CustomizationField
CustomizationField Methods
None
423
CustomizationLists
ICustomizationLists The CustomizationLists object holds a collection of all CustomizationList objects in the TestDirector project. For an explanation of the CustomizationList object, see the CustomizationList object description on page 426.
CustomizationLists Properties
Collection (List) Properties
Property Name List (VARIANT Param) R/W R Description Returns the IDispatch interface to a specified list. Passes the list name (string) or root ID (long) to the property as the Param parameter.
Object Properties
Property Name ListByCount (long Count) R/W R Description Returns a reference (IDispatch interface) to the CustomizationList object representing the list specified by its index number (the Count parameter) in the current CustomizationLists object.
424
Chapter 6 CustomizationLists
CustomizationLists Methods
AddList Method
Adds a new CustomizationList object. Syntax CustomizationLists.AddList (BSTR Name ) Parameters
Parameter Name Name Description Required. The name of the list to be added (string). Default None
RemoveList Method
Removes a CustomizationList object. Syntax CustomizationLists.RemoveList (BSTR Name ) Parameters
Parameter Name Name Description Required. The name of the list to be removed (string). Default None
Returns None
425
CustomizationList
ICustomizationList The CustomizationList object represents a user list in a TestDirector project.
CustomizationList Properties
Object Properties
Property Name RootNode R/W R Description Returns a reference to the CustomizationListNode object representing the root node of the current list.
Name
String
426
Chapter 6 CustomizationList
CustomizationList Methods
Find Method
Finds a node of the current list by the node name or ID. Syntax CustomizationList.Find (VARIANT Val ) Parameters
Parameter Name Val Description Required. The name (string) or ID (long) of the node. Default None
427
CustomizationListNode
ICustomizationListNode The CustomizationListNode object represents a node in a list. This object can represent the list root node or a child node within the list.
CustomizationListNode Properties
Collection (List) Properties
Property Name Children R/W R Description Returns a list (IList interface) of CustomizationListNode objects representing the sub-nodes of the current node.
Object Properties
Property Name Child (BSTR NodeName) R/W R Description Returns a reference to the CustomizationListNode object representing the specified sub-node. Passes the sub-node name to the property as the NodeName parameter. As a Read property, returns a reference to the CustomizationListNode object representing the current node parent node. As a Write property, removes the current node from its parent node and makes it a sub-node of the specified CustomizationListNode object. Returns a reference to the CustomizationList object that contains the current node.
Father
R/W
List
428
Chapter 6 CustomizationListNode
429
CustomizationListNode Methods
AddChild Method
Adds a new sub-node to the current node. Syntax CustomizationListNode.AddChild (VARIANT Node ) Parameters
Parameter Name Node Description Required. Specifies the name of the node to be added by name (string) or an IDispatch interface to the CustomizationListNode object representing the node. Default None
430
Chapter 6 CustomizationListNode
RemoveChild Method
Removes the specified sub-node from the current node. Syntax CustomizationListNode.RemoveChild (VARIANT Node ) Parameters
Parameter Name Node Description Required. Specifies the name of the node to be removed by name (string) or an IDispatch interface to the CustomizationListNode object representing the node. Default None
Returns None
431
CustomizationPermissions
ICustomizationPermissions The CustomizationPermissions object contains properties that let you define the ability of user groups to add, remove, and modify TestDirector entities, such as defect reports and tests. For example, you can use the CanAddItem property to determine which members of the specified user group can add a specified type of entity, as explained below. Similarly, you can use the TransitionRules property to determine what transition rules apply to the specified user group. Transition rules determine which actions can be performed in a specified field, as explained in the CustomizationTransitionRule object description on page 439.
CustomizationPermissions Properties
Object Properties
Property Name TransitionRules (BSTR EntityName, VARIANT Field, VARIANT Group) R/W R Description Returns a reference to the CustomizationTransitionRules object for the specified field and group. Passes the entity name (string), field (string or IDispatch to a CustomizationField object) and group (string or IDispatch to a CustomizationUsersGroup object) to the property as parameters.
432
Chapter 6 CustomizationPermissions
R/W
Long
433
R/W W
Type Boolean
Description Indicates whether the group specified by the Group parameter can modify an item of the entity specified by the EntityName parameter. The Group parameter can take either the group name (string) or a group object (IDispatch interface). Indicates or determines whether members of the specified group can remove the specified type of entity. Passes the entity name (string) and group (string or IDispatch to a CustomizationUsersGroup object) to the property as parameters. Indicates whether the fields of the entity specified by the EntityName parameter can be restricted for owner modifications only. Indicates whether the entity specified by the EntityName parameter can have attachments. Indicates whether a field in an entity is visible for a specified group in a new bug form. Passes the entity name (string), field (string or IDispatch to a CustomizationField object) and group (string or IDispatch to a CustomizationUsersGroup object) to the property as parameters.
R/W
Long
Boolean
HasAttachmentField (BSTR EntityName) IsVisibleInNewBug (BSTR EntityName, VARIANT Field, VARIANT Group)
Boolean
R/W
Boolean
434
Chapter 6 CustomizationTransitionRules
CustomizationTransitionRules
ICustomizationTransitionRules The CustomizationTransitionRules object gathers a collection of transition rules (CustomizationTransitionRule objects) and applies them to a specific field and user group. For an explanation of transition rules, see the CustomizationTransitionRule object description on page 439.
CustomizationTransitionRules Properties
Object Properties
Property Name Field R/W R Description Returns a reference to the CustomizationField object to which the transition rules in the current object are attached. Returns a reference to the CustomizationUsersGroup object to which the transition rules in the current object are attached. Returns a reference to the CustomizationTransitionRule specified object. Passes the count number of the object (i.e., its position in the object list of transition rules) to the property as the Count parameter.
Group
435
EntityName
String
Updated
R/W
Boolean
436
Chapter 6 CustomizationTransitionRules
CustomizationTransitionRules Methods
AddTransitionRule Method
Adds a new CustomizationTransitionRule object to the current object. By default, the new transition rule is open, i.e., allows the user to change the field from any value to any other value. To define the source and destination values of the new transition rule, set the SourceValue and DestinationValue of the new CustomizationTransitionRule object. Syntax CustomizationTransitionRules.AddTransitionRule() Parameters None Returns An IDispatch interface to the new CustomizationTransitionRule object.
437
RemoveTransitionRule Method
Removes the specified transition rule from the current object. Syntax CstmTransitionRules.RemoveTransitionRule(VARIANT Rule) Parameters
Parameter Name Rule Description Required. The count number of the transition rule to be removed (i.e., its position in the object list of transition rules), or an IDispatch interface to the CustomizationTransitionRule object representing the transition rule. Default None
Returns None
438
Chapter 6 CustomizationTransitionRule
CustomizationTransitionRule
ICustomizationTransitionRule The CustomizationTransitionRule object represents a single transition rule. Transition rules determine which actions members of a specific user group can perform in a specific field. For example, if the SourceValue property is Opened, the DestinationValue property is Fixed, and the IsAllowed property is TRUE, the transition rule lets the user change the specified field from Opened to Fixed. The fields and users to which the transition rule applies are determined through the CustomizationTransitionRules object, described on page 448.
CustomizationTransitionRule Properties
Simple Data Type Properties
Property Name DestinationValue IsAllowed R/W R/W R/W Type String Boolean Description Returns or sets the destination value of the transition rule. Verifies or determines if the action defined in the DestinationValue and SourceValue properties is allowed. Returns or sets the source value of the transition rule. As a read property, indicates whether the object update flag is set. The update flag is automatically set if the object has been modified since the last download from the server. As a write property, sets (TRUE) or removes (FALSE) the object update flag.
SourceValue Updated
R/W R/W
String Boolean
CustomizationTransitionRule Methods
None
439
CustomizationUsersGroups
ICustomizationUsersGroups The CustomizationUsersGroups object holds a collection of all CustomizationUsersGroup objects in the TestDirector project.
CustomizationUsersGroups Properties
Collection (List) Properties
Property Name Groups R/W R Description Returns a list of CustomizationUsersGroup objects.
Object Properties
Property Name Group (BSTR Name) R/W R Description Returns a reference to the CustomizationUsersGroup object representing the specified user group. Passes the name of the user group (string) to the property as the Name parameter.
440
Chapter 6 CustomizationUsersGroups
CustomizationUsersGroups Methods
AddGroup Method
Adds a new CustomizationUsersGroup object. Syntax CustomizationUsersGroups.AddGroup (BSTR Name ) Parameters
Parameter Name Name Description Required. The name of the user group to be added (string). Default None
RemoveGroup Method
Removes a CustomizationUsersGroup object. Syntax CustomizationUsersGroups.RemoveGroup (BSTR Name) Parameters
Parameter Name Name Description Required. The name of the user group to be removed (string). Default None
Returns None
441
CustomizationUsersGroup
ICustomizationUsersGroup The CustomizationUsersGroup object represents a user group in a TestDirector project for purposes of adding and removing users to and from the user group.
CustomizationUsersGroup Properties
Simple Data Type Properties
Property Name Deleted R/W R/W Type Boolean Description Verifies or determines if the Deleted flag is set for the current user group. Groups for which the Delete flag is set are deleted by the Commit method of the Customization object. Gets or sets the data hiding filter, as an internal structure format, for the entity specified by the FilterType parameter. Returns the user group ID. Indicates if the user group is a built-in system user group. Same as IsSystem. It is preferable to use IsSystem since it uses better error handling. Returns or sets the user group name. As a read property, indicates whether the object update flag is set. The update flag is automatically set if the object has been modified since the last download from the server. As a write property, sets (TRUE) or removes (FALSE) the object update flag.
R/W
String
ID IsSystem Is_System
R R R
Name Updated
R/W R/W
String Boolean
442
Chapter 6 CustomizationUsersGroup
CustomizationUsersGroup Methods
AddUser Method
Adds a new user to the user group. Syntax CustomizationUsersGroup.AddUser(VARIANT User ) Parameters
Parameter Name User Description Required. The name of the user to be added (string) or an IDispatch interface to the CustomizationUser object representing the user. Default None
Returns None
443
RemoveUser Method
Removes a user from the user group. Syntax CustomizationUsersGroup.RemoveUser (VARIANT UserName ) Parameters
Parameter Name UserName Description Required. The name of the user to be removed (string) or an IDispatch interface to the CustomizationUser object representing the user. Default None
Returns None
UsersList Method
Returns a list of all members of the user group. Syntax CustomizationUsersGroup.UsersList() Returns A list (IList interface) of all members of the users group.
444
Chapter 6 CustomizationUsers
CustomizationUsers
ICustomizationUsers The CustomizationUsers object holds a collection of all CustomizationUser objects in the TestDirector project. For an explanation of the CustomizationUser object, see the CustomizationUser object description on page 448.
CustomizationUsers Properties
Collection (List) Properties
Property Name Users R/W R Description Returns a list (IList interface) of CustomizationUser objects.
Object Properties
Property Name User (BSTR Name) R/W R Description Returns a reference to the CustomizationUser object representing the specified user. Passes the user name (string) to the property as the Name parameter.
445
CustomizationUsers Methods
AddSiteUser Method
Adds a new CustomizationUser object to the current site. Note that these changes will only take effect after using the Commit method of the Customization object. Syntax CustomizationUsers.AddSiteUser(BSTR UserName,BSTR FullName, BSTR Email,BSTR Description, BSTR Phone,VARIANT Group) Parameters
Parameter Name UserName FullName Email Description Phone Group Description Required. The name of the user to be added (string). Required. The full name of the user to be added (string). Required. The e-mail address of the user to be added (string). Required. The description of the user to be added (string). Required. The phone number of the user to be added (string). Required. The group to which the added user belongs. Can be either the group name (string) or an IDispatch interface to the CustomizationUsersGroup object. Default None None None None None None
Returns None
446
Chapter 6 CustomizationUsers
AddUser Method
Adds a new CustomizationUser object. Syntax CustomizationUsers.AddUser(BSTR Name) Parameters
Parameter Name Name Description Required. The name of the user to be added (string). Default None
RemoveUser Method
Removes a CustomizationUser object. Syntax CustomizationUsers.RemoveUser(BSTR Name) Parameters
Parameter Name Name Description Required. The name of the user to be removed (string). Default None
Returns None
447
CustomizationUser
ICustomizationUser The CustomizationUser object represents a user in a TestDirector project for purposes of adding and removing the user to and from user groups.
CustomizationUser Properties
Simple Data Type Properties
Property Name Address Deleted R/W R/W R/W Type String Boolean Description Returns or sets the user description. Can be used for various details. Verifies or determines if the Deleted flag is set for the current user. Users for which the Delete flag is set are deleted by the Commit method of the Customization object. Returns or sets the user e-mail address. Returns or sets the user full name. Indicates whether the current user is a member of the group specified by the GroupName parameter. The GroupName parameter can be the name of the group (string) or an IDispatch interface to the CustomizationUsersGroup object representing the group. Same as InGroup. It is preferable to use InGroup since it uses better error handling. Returns a unique name by which to identify the user.
R/W
Boolean
String
448
Chapter 6 CustomizationUser
Description Sets the user password. Returns or sets the user telephone number. As a read property, indicates whether the object update flag is set. The update flag is automatically set if the object has been modified since the last download from the server. As a write property, sets (TRUE) or removes (FALSE) the object update flag.
CustomizationUser Methods
AddToGroup Method
Adds the current user to the specified user group. Syntax CustomizationUser.AddToGroup(VARIANT Group) Parameters
Parameter Name Group Description Required. The name of the group (string) or an IDispatch interface to the CustomizationUsersGroup object representing the group. Default None
Returns None
449
GroupsList Method
Returns a list of all the user groups to which the current user belongs. Syntax CustomizationUser.GroupsList() Parameters None Returns An IList interface to a list object containing the user groups.
RemoveFromGroup Method
Removes the current user from the specified user group. Syntax CustomizationUser.RemoveFromGroup(VARIANT Group) Parameters
Parameter Name Group Description Required. The name of the group (string) or an IDispatch interface to the CustomizationUsersGroup object representing the group. Default None
Returns None
450
Chapter 6 CustomizationModules
CustomizationModules
ICustomizationModules The CustomizationModules object is used to handle the customization modules in the project.
CustomizationModules Properties
Simple Data Type Properties
Property Name Description (long ModuleID) R/W R/W Type String Description Gets/sets the string containing the module description. The ModuleID parameter specifies the module in the Modules (MD_ID) table for which we want to get/set the description. The module IDs are:
451
R/W R/W
Type String
Description Gets/sets the string containing the module name. The ModuleID parameter specifies the module for this property.
R/W
Long
452
7
Error Handling
This chapter describes how the TestDirector API handles errors. All errors are OLE exceptions. Error code values are located in TDAPI_ERRORCODES enumeration, which is defined in the TDOLE type library. This chapter includes: List of Error Codes Examples of Error Handling
453
Error Name TDOLE_DBVERMISMATCH TDOLE_NO_IDAPI_DLL TDOLE_RECNOTFOUND TDOLE_NOFIELD TDOLE_NOTAUTOTEST TDOLE_NODIRECTORY TDOLE_ATEOF TDOLE_ATBOF TDOLE_INVALIDATTRNAME TDOLE_ILLEGALSUBJECTPATH TDOLE_MANUALTEST TDOLE_CHANGED TDOLE_DBNOTCONNECTED TDOLE_INVALIDNODEID TDOLE_NONODE TDOLE_CANNTOPENTESTTB TDOLE_CANNTOPENSTEPTB TDOLE_CANNTOPENRUNTB TDOLE_CANNTOPENTESTCYCLTB TDOLE_CANNTOPENCYCLETB TDOLE_CANNTOPENDESSTEPTB
ID 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029
Description Project version mismatch. No BDE is installed. No record matches the key value. The specified field does not exist. The test is not an automated test. The specified directory does not exist. The end of the table has been reached. The beginning of the table has been reached. The specified attribute does not exist. The specified subject path does not exist. The specified test type is not an automatic test. The API has changed. The API is not connected to a project. The specified node ID is invalid. The specified node does not exist. Cannot open Test table. Cannot open Step table. Cannot open Run table. Cannot open Testcycle table. Cannot open Cycle table. Cannot open Dessteps table.
454
Error Name TDOLE_CANNTOPENHISTTB TDOLE_CANNTBUILDTREE TDOLE_NOASSOSIATEDROOT TDOLE_VCS_NOVCS TDOLE_VCS_NOTVCSDB TDOLE_VCS_CANNOTLOGIN TDOLE_VCS_NOTINVCSDB TDOLE_VCS_LOCKEDMETEST TDOLE_VCS_LOCKEDTEST TDOLE_VCS_NOTCONNECTED TDOLE_VCS_NOTCHECKEDOUT TDOLE_VCS_NOTLOCKED TDOLE_VCS_NOTDEFVERFILE TDOLE_VCS_FAILED_TO_SET_ CUR_VER TDOLE_VCS_FAILED_TO_GET_ CUR_VER TDOLE_NO_MAIL_DLL TDOLE_MAIL_NO_TO_FIELD TDOLE_MAIL_ERR_PARSING_ PARAMS TDOLE_MAIL_GENERROR TDOLE_MAIL_LOGIN_FAILURE TDOLE_MAIL_ERR_SENDING
ID 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1046 1047 1048 1049 1050 1051
Description Cannot open History table. Cannot build the test plan tree. No associated tree root. VCS support is not installed on the TestDirector server side. The TestDirector project is not connected to the VCS database. Cannot log into the VCS database. The test is not in the VCS database. The test is locked by the current user. The test is locked by another user. Not connected to the VCS database. The test is not checked out. The test is not locked. There is no version file defined for the test type. Failed to set the working version of the test. Failed to get the working version of the test. The mail dll was not found. The wrong To: address. The mail format is incorrect. General mail error. The mailbox login is incorrect. Failure sending mail.
455
ID 1052
Description There is a database corruption in ALL_LISTS table. Update or repair the database. A test already exists. No license to access this module. No license to access this module. No license to access this module. Failed to extract license status. License expired. Invalid license. Invalid license. The version already exists. Required version does not exist in the version control. Invalid request format. Attachment stream is invalid. Duplicate requirement coverage. File system error. File system path is not valid. File system permission error. Cannot update user-defined field customization. The project was disconnected by the administrator.
TDAPI_TEST_EXISTS TDOLE_LICENSE_DENIED TDOLE_LICENSE_OVERFLOW_ ALERT TDOLE_LICENSE_NOT_ INITILIZED TDOLE_LICENSE_GENERROR TDOLE_LICENSE_KEY_EXPIRED TDOLE_LICENSE_DOMAIN_NOT_ FOUND TDOLE_LICENSE_MUID_NOT_ FOUND TDOLE_VCS_VERSIONEXISTS TDOLE_VCS_VERSIONNOTEXISTS TDOLE_BAD_REQUEST TDOLE_BAD_ATT_STREAM TDOLE_RECCOVER_EXISTS TDOLE_ERROR_FILESYSTEM TDOLE_ERROR_PATH_NOT_ FOUND TDAPI_ERROR_PATH_PERMISSION TDOLE_CAN_UPDATE_UDFS TDAPI_DISCONNECTED_BY_ ADMIN
1053 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1068 1069 1070 1071 1076 1077
456
Error Name TDAPI_FAILED_TO_RECONNECT TDOLE_DUPLICATENODENAME TDOLE_MAIL_ERROR_BAD_ ENTITY TDOLE_CYCLE_EXISTS TDOLE_BAD_FILTER_START TDOLE_BAD_FILTER_1 TDOLE_BAD_FILTER_2 TDOLE_BAD_FILTER_3 TDOLE_BAD_FILTER_4 TDOLE_BAD_FILTER_5 TDOLE_BAD_FILTER_6 TDOLE_BAD_FILTER_7 TDOLE_BAD_FILTER_END TDOLE_TESTS_ALREADY_RUN TDOLE_E_CREATE_LOG_FILE TDOLE_E_START_RUNS PARAM_E_WRONG_NUM PARAM_E_NOT_FOUND PARAM_E_EMPTY LIST_E_EMPTY LIST_E_FILTER COL_E_NOT_FOUND BUG_E_NOT_FOUND
ID 1078 1080 1081 1082 1100 1101 1102 1103 1104 1105 1106 1107 1110 1111 1112 1113 1200 1201 1202 1220 1221 1240 1260
Description Cannot connect to the project. Duplicate SysTreeNode name. Cannot find entity by e-mail. Duplicate TestSet name. Invalid filter. Invalid filter. Invalid filter. Invalid filter. Invalid filter. Invalid filter. Invalid filter. Invalid filter. Invalid filter. The test has been executed by another user. Cannot create log file. Cannot execute test. The wrong number of parameters for the defined SWL statement. The necessary parameter was not found. Invalid parameter value. The created list is empty. Bad list filter. The specified column does not exist. The specified bug does not exist.
457
Error Name BUG_E_DELETE BUG_E_CREATE TEST_E_NOT_FOUND TEST_E_CREATE TEST_E_DELETE TEST_E_COV_DELETE TEST_E_REPOSITORY TEST_E_TEMPLATE_TYPE TDAPI_E_LINK_TEST_ CIRCLUATION FIELD_E_NO_PERMISSION FIELD_E_SYS_FIELD FIELD_E_NOT_ACTIVE FIELD_E_IS_KEY FIELD_E_NO_EDIT FIELD_E_VERIFIED FIELD_E_TRANSITION FIELD_E_REQUIRED FIELD_INVALID USER_E_NOT_FOUND USER_E_CREATE USER_E_DELETE USER_E_IN_GROUP USER_E_NOT_IN_GROUP
ID 1261 1262 1280 1281 1282 1283 1284 1285 1287 1300 1301 1302 1303 1304 1305 1306 1307 1308 1320 1321 1322 1323 1324
Description Failure to delete bug. Failure to create log. The specified test does not exist. Failure to create a new test. Failure to delete test. Failed to delete requirement coverage by test. Invalid test path. Cannot change test type. Cannot link to test since specific test is in circulation. No permission to modify the field. The field is a system field. The field is not an active field. The field is a database key field. The field is a read-only field. Field verification failure. Error in field defined transition logic. The field is a required field. Invalid field value. The specified user does not exist. Failure to create user. Failure to delete user. Failure to add user into group. User does not exist in the group.
458
Error Name FILTER_E_NOVALUE FILTER_E_INVALIDVALUE FILTER_E_INVALIDNAME FILTER_S_DATE_COMPLEX FILTER_S_LIST_BY_CODE REQ_E_NOT_FOUND REQ_E_INVALIDORDER REQ_E_INVALIDFATHERID REQ_E_INVALIDTYPE REQ_E_CREATE REQ_E_INVALIDMODE
ID 1340 1341 1342 1343 1344 1360 1361 1362 1363 1364 1365
Description No filter value is defined. The defined filter value is invalid. The filter condition name is invalid. Invalid date. Invalid system node path. The specified requirement does not exist. The requirement order is invalid. The father ID is invalid. The requirement type is invalid. Failed to create a new requirement. The mode flag is invalid for the requirement options: copy, remove and find. Failed to remove the specified requirement. The test set does not exist. Failure to create TestSet. Failure to delete TestSet. Failure to delete default TestSet. The execution test does not exist. Failed to remove the specified execution test. Failure to create test in TestSet. The item does not exist. No permission to create a new item. No permission to remove an item.
REQ_E_DELETE TESTSET_E_NOT_FOUND TESTSET_E_CREATE TESTSET_E_DELETE TESTSET_E_DELETE_DEFAULT TSTEST_E_NOT_FOUND TSTEST_E_DELETE TSTEST_E_CREATE ITEM_E_NOT_FOUND ITEM_E_NO_ADD ITEM_E_NO_REMOVE
1366 1380 1381 1382 1383 1400 1401 1402 1420 1421 1422
459
Error Name COND_E_NOT_FOUND COND_E_CREATE COND_E_INVALIDTYPE ATT_E_NOT_FOUND ATT_E_CREATE ATT_E_INVALID_REQUEST ATT_E_RENAME ATT_E_OBJECT_HAS_ ATTACHMENT USERGROUP_E_NOT_FOUND USERSGROUP_E_CREATE DESSTEP_E_NOT_FOUND DESSTEP_E_CREATE DESSTEP_E_DELETE TREE_E_NOT_FOUND TREE_E_CREATE TREE_E_DELETE TREE_E_RENAME RUN_E_NOT_FOUND RUN_E_CREATE RUN_E_DELETE STEP_E_NOT_FOUND STEP_E_CREATE STEP_E_DELETE
ID 1440 1441 1442 1460 1461 1463 1464 1465 1480 1482 1500 1501 1502 1520 1521 1522 1523 1540 1541 1542 1560 1561 1580
Description The condition does not exist. Failed to create a new condition. The condition type is invalid. The attachment does not exist. Failed to create attachment. Invalid request for attachment. Failed to rename attachment. Object cannot have an attachment. The specified user group does not exist. Failed to create user group. The specified design step does not exist. Failed to create design step. Failed to remove the specified design step. Tree node not found. Cannot create Tree node. Cannot remove Tree node. Cannot rename Tree node. Run does not exist. Failed to create Run. Failed to delete Run. Step does not exist. Failed to create Step. Failed to delete Step.
460
Description ExStorage is currently busy. Filter is invalid. The ExtendedStorage path is not valid. Cannot create one of the following objects: path, file or ES object itself. Internet connection specific error. Server path is empty. Client path is empty. Server path does not exist. Server is not connected. Failed to delete host. Host does not exist. Host group does not exist. Cannot paste subject to itself. Duplicate Tree node name. No graph data exists. Mail condition does not exist. No TD param exists. Method is disabled y the event handler. No table exists by the specific name. Duplicate requirement name. Duplicate TestSet folder name. An unexpected error has occurred.
EXSTORAGE_EMPTY_ClIENT_ PATH 1589 EXSTORAGE_ERROR_SERVER_ PATH SERVER_NOT_CONNECTED HOST_E_DELETE HOST_E_NOT_FOUND HOSTGROUP_E_NOT_FOUND COPY_SUBJECT_E_TO_ITSELF TDOLE_NODE_EXISTS GRAPH_DATA_EMPTY 1590 1600 1620 1621 1640 1660 1661 1700
MAILCONDITION_E_NOT_ FOUND 1850 TDPARAM_NOT_FOUND TDOLE_DIFFERENT_UDFS TDOLE_DB_TABLE_NAME TDOLE_REQ_EXISTS TDOLE_TESTSET_FOLDER_EXISTS TDOLE_UNEXPECTED 1900 1950 2000 2055 3055 5000
461
Description An Internal error has occurred. Data is corrupted. Cannot update Step parameter value. Invalid TD parameter. Invalid TD parameter type. Invalid TD parameter range. Invalid TD parameter number. Invalid TD parameter format. Invalid TD parameter list. Customization objects not initialized. Invalid request. Statistic object is not initialized. Invalid object has been passed. No object exists. Object was deleted by another user. Object is not initialized. No post allowed for object that has a virtual parent. Cannot get RunFactory for virtual TSTest. Field exists in the virtual object only. The field is read-only. There is no permission to proceed with this action.
TDOLE_INVALID_PARAM_ FORMAT 5104 TDOLE_INVALID_PARAM_ENUM TDOLE_E_INITIALIZE TDOLE_INVALID_REQUEST TDOLE_INVALID_INPROCESS TDOLE_INVALID_OBJECT TDOLE_INVALID_OBJECT_KEY TDOLE_OBJECT_DELETED TDOLE_OBJECT_NOT_ INITIALIZED TDOLE_VIRTUAL_FATHER TDOLE_VIRTUAL TDOLE_FIELD_ONLY_FOR_ VIRTUAL TDOLE_VIRTUAL_FIELD TDOLE_E_PERMISSION 5105 5200 5210 5220 6000 6001 6002 6003 6010 6020 6032 6040 6100
462
ID 6700
10710 Failed to unlock object. 10720 Object locked by another user. 10730 Wrong administrator password. 10740 User is not connected as an administrator. 10750 No object exists.
463
464
Index
Symbols
_NewEnum method 176 List object 176 Add method List object 177 AddActiveField method CustomizationFields object 417 AddActiveMemoField method CustomizationFields object 417 AddChild method CustomizationListNode object 430 AddCoverage method 226 Req object 226 AddCoverageEx method Req object 227 AddGroup method CustomizationAction object 414 CustomizationUsersGroups object 441 AddHost method HostGroup object 362 AddItem method HostFactory object 354 HostGroupFactory object 360 IBaseFactory interface 127 AddList method CustomizationLists object 425 AddNode method SysTreeNode object 379 AddNodeDisp method TestSetFolder object 271 AddObjectToVcs method VCS object 366 AddParam method Command object 155 StepParams object 325 AddSiteUser method CustomizationUsers object 446 AddToGroup method CustomizationUser object 449
A
action permissions 404 action name 93 action types 412 Actions table 93 adding records 95 adding to user group 414 customization 412 defining 432 deleting records 95 granting 94 list of user groups 412 listing 411 mask 94 modifying fields 94 modifying records 95 owner 95 removing from user group 415 table 94 table name 94 transition rules 90 user groups 94 action privileges. See action permissions ActionPermission object 404 description 404 example 405 Actions table 93 ActiveX controls ExecConfiguration 14, 33 ResultViewer 15, 31 ScriptViewer 15, 28
465
TestDirector Open Test Architecture Guide AddTransitionRule method CustomizationTransitionRules object 437 AddUser method CustomizationUsers object 447 CustomizationUsersGroup object 443 Administrators Guide vi, vii Adobe Acrobat Reader vii AlertManager object 193 CancelAllAlert method 194 DeleteAlert method 193 Alerts table 78 All_Lists table 75 alphabetical object reference 114 API, SeeTestDirector API applications, integrating with TestDirector 46 Attachment object 198 example 202 Load method 200 Rename method 200 Save method 202 AttachmentFactory object 195 creating 123 example 196 FactoryProperties method 195 subject folder 384 attachments adding to fields 123 attachment ID 73 attachment index 73 Cros_Ref table 72 data 198 description 73, 198 directory path 73 entity 73 file reference 198 host groups 86 host servers 86 in defects 70 in design steps 61 in test runs 66 in test sets 62, 64 in test steps 68 requirements 57 subject folder 384 attachments (cont) tests 59 type 73, 199 automatic fetching 108
B
Base interfaces 100, 120 IBaseFactory 126 IBaseField 120 IBaseFieldEx 123 IBaseFieldExMail 124 BLOB fields, fetching 107 Books Online vii Bug object 338 example 341 FindSimilarBugs method 340 Bug table 68 Bug_Tokens table 71 BugFactory object 328 BuildAgeGraph method 329 BuildPerfGraph method 330 BuildProgressGraph method 331 BuildSummaryGraph method 333 BuildTrendGraph method 335 example 337 FindSimilarBugs method 336 BuildAgeGraph method BugFactory object 329 BuildPerfGraph method BugFactory object 330 ReqFactory object 205 TestFactory object 236 TestSet object 277 TestSetFactory object 261 BuildPerfGraphEx method ReqFactory object 206 BuildProgressGraph method BugFactory object 331 ReqFactory object 208 TestFactory object 239 TestSet object 278 TestSetFactory object 262 BuildProgressGraphEx method ReqFactory object 210, 241 TestSet object 285
466
Index BuildSummaryGraph method BugFactory object 333 ReqFactory object 208, 213 TestFactory object 237 TestSet object 280 BuildSummaryGraphEx method ReqFactory object 215 BuildTrendGraph method BugFactory object 335 ReqFactory object 217 TestSet object 282 TestSetFactory object 267 BuildTrendGraphEx method ReqFactory object 219 Clone method Recordset object 160 Close method Settings object 391 Columns dialog box 94 COM classes performance issues 107 TestDirector API object model 97 Command object 153 AddParam method 155 DeleteParam method 156 DeleteParams method 156 example 157 Execute method 155 commands 153 executing 155 index fields 153 text of 153 Commit method Customization object 400, 401, 402, 408 Condition object 302 example 303 ConditionFactory object 298 example 300 Save method 300 conditions 302 description 302 execution test 298 removing 298 saving 300 type 303 connection to project checking 138 establishing 141 terminating 142 connection to server, checking 137 ConnectProject method TDConnection object 139 ConnectProjectEx method TDConnection object 141 ConnectToVcsAs method TDConnection object 142 conventions. See typographical conventions CopyDesignSteps method Run object 315
C
cache 108 CacheMgr object Run method 402 SetFileTime method 402 Cancel method ExtendedStorage object 183 CancelAllAlertAlert method AlertManager object 194 CancelFollowUp method FollowUpManager object 192 CheckIn method VCS object 367 CheckOut method VCS object 367 CheckTestInstances method TestSet object 284 class factory objects 97 class ID 12 CleanAllAlerts method IAlertable object 132 Clear method TDFilter object 167 ClearHistory method History object 347 ClearParam method StepParams object 326 ClearView method VCS object 368
467
TestDirector Open Test Architecture Guide CopyStepsToTest method Run object 315 coverage requirements 248 listing 249 CoverRequirement method Test object 248 CreateScriptTemplate method TestType object 17 creating objects. See objects, creating Cros_Ref (cross reference) table 72 custom controls 6 custom test types 12 creating 13 registering 38 custom testing tools. See testing tools customization 84 action permissions 412, 432 actions 411 adding user-defined fields 417 field types 422 fields 416, 419 lists 424, 426 loading data 407, 409 overview 407 saving changes 407, 408 tasks 105 transition rules 435, 439 user groups 440, 442 users 445, 448 Customization object 407 Commit method 400, 401, 402, 408 description 407 example 409 Load method 409 Customization objects 105, 407 Customization object 407 CustomizationAction object 412 CustomizationActions object 411 CustomizationField object 419 CustomizationFields object 416 CustomizationList object 426 CustomizationListNode object 428 CustomizationLists object 424 CustomizationModules object 451 CustomizationPermissions object 432 Customization objects (cont) CustomizationTransitionRule object 439 CustomizationTransitionRules object 435 CustomizationUser object 448 CustomizationUsers object 445 CustomizationUsersGroup object 442 CustomizationUsersGroups object 440 CustomizationAction object 412 AddGroup method 414 description 412 RemoveGroup method 415 CustomizationActions object 411 description 411 CustomizationField object 419 description 419 CustomizationFields object 416 AddActiveField method 417 AddActiveMemoField method 417 description 416 CustomizationList object 426 description 426 Find method 427 CustomizationListNode object 428 AddChild method 430 description 428 RemoveChild method 431 CustomizationLists object 424 AddList method 425 description 424 RemoveList method 425 CustomizationModules object 451 description 451 CustomizationPermissions object 432 description 432 CustomizationTransitionRule object 435, 439 description 439 CustomizationTransitionRules object 435 AddTransitionRule method 437 description 435 RemoveTransitionRule method 438
468
Index CustomizationUser object 448 AddToGroup method 449 description 448 GroupsList method 450 RemoveFromGroup method 450 CustomizationUsers object 445 AddSiteUser method 446 AddUser method 447 description 445 RemoveUser method 447 CustomizationUsersGroup object 442 AddUser method 443 description 442 RemoveUser method 444 UsersList method 444 CustomizationUsersGroups object 440 AddGroup method 441 description 440 RemoveGroup method 441 Cycl_Fold table 80 Cycle (test sets) table 62 Data objects (cont) TestSet object 270 TestSetFactory object 259 TSTestFactory object 304 data tables 54 Alerts 78 All_Lists 75 Bug 68 Bug_Tokens 71 Cros_Ref (cross reference) 72 Cycl_Fold 80 Cycle (test sets) 62 Dessteps 60 History 74 Req (requirements) 56 Req_Cover (requirements coverage) 58 Rules 80 Run 65 Step 67 Step_Params 76 Test 59 Testcycl (test set per test) 63 Tokens 71 database clients 48 commands. See commands fields. See fields management 104 query 153 server. See database servers structure 153 tables. See project database tables type 137 database servers Microsoft SQL server 48 Oracle 48 Sybase 48 database_name parameter. See set_value function Dataconst table 89 DCOM protocol 7, 20, 48 DCOM server 11 defect progress graph 331 defect records. See defects defect summary graph 213, 215, 333
D
data analysis 46 Data objects 102, 195, 307 Attachment object 198 AttachmentFactory object 195 Bug object 338 BugFactory object 328 Condition object 302 ConditionFactory object 298 DesignStep object 256 DesignStepFactory object 253 Graph object 342 History object 347 HistoryRecord object 350 Req object 224 ReqFactory object 203 Run object 314 RunFactory object 310 Step object 322 StepFactory object 318 StepParams object 325 Test object 246 TestFactory object 233
469
TestDirector Open Test Architecture Guide defects attachments 70 Bug table 68 Bug_Tokens table 71 changes 70 closed in version 69 closing 69 closing date 69 date found 69 defect summary graph 213, 215, 333 description 68 developer comments 69 fix time, actual 69 fix time, estimated 69 ID 68, 71 mailing 70 mailing reports. See mailing change notification priority level 69, 338 progress graph 331 project name 68 reproducible 69 revision number of a record 70 search 336, 340 severity level 69 status 68 subject folder 68 summary 68 test found 69 test run found 69 test set found 68, 69 test step found 69 token ID 71 user reporting 69 user responsible for 68 user-defined 70 version found 69 version time stamp 70 Delete method ExtendedStorage object 186 DeleteAlert method AlertManager object 193 IAlertable object 132 DeleteCategory method Settings object 391 DeleteDuplicateRuns method RunFactory object 311 DeleteObjectFromVCS method VCS object 369 DeleteParam method Command object 156 StepParams object 326 DeleteParams method Command object 156 DeleteValue method Settings object 391 description fields IgnoreHtmlFormat 138 design steps adding 246, 254 attachments 61 description 60, 256, 257 Dessteps table 60 expected result 60 ID 61 name 60 number of 59 order 60 parameters 61 removing 254 step ID 60 test ID 60 user-defined 61 DesignStep object 256 example 257 DesignStepFactory object 253 example 254 Dessteps (design steps) table 60 DisconnectProject method TDConnection object 142 documentation set vi documentation updates viii, ix domain_name parameter. See set_value function domains 137 DrillDown method 344 Graph object 344 drill-down operation 342, 344
470
Index
E
error handling description 453 examples 464 list of errors 453 returning most recent error message 14 EventsList method ExecutionStatus object 398 examples ActionPermission object 405 Attachment object 202 AttachmentFactory object 196 Bug object 341 BugFactory object 337 Command object 157 Condition object 303 ConditionFactory object 300 Customization object 409 DesignStep object 257 DesignStepFactory object 254 ExtendedStorage object 189 FieldProperty obejct 175 Graph object 345 History object 349 HistoryRecord object 350 Host object 357 HostFactory object 354 HostGroup object 364 HostGroupFactory object 361 Recordset object 163 registering custom test types 38 RemoteAgent 25 Req object 231 RunFactory object 312 ScriptViewer 29 Settings object 393 Step object 323 StepFactory object 320 SubjectNode object 387, 388 SysTreeNode object 382 TDConnection object 149 TDField object 171 TDFilter object 169 Test object 249 TestFactory object 245
examples (cont) TestSet object 287 TestSetFactory object 269 TestType COM class 18 TreeManager object 376 TSTest object 309 TSTestFactory object 305 VCS object 371 Visual Basic 112 Visual C++ 112 ExecConfiguration ActiveX control 3335 Init method 34 ShowExecConfiguration method 35 ShowExecConfigurationEX method 34 ExecConfiguration class 14 Execute method Command object 155 execution tests 304 conditions 298, 302 TSTest object 307 ExecutionStatus object 397 description 397, 399 EventsList method 398 RefreshExecStatusInfo method 398 ExtendedStorage object 182 Cancel method 183 Delete method 186 example 189 GetLastError method 183 Load method 183 LoadEx method 187 Progress method 184 Save method 185 SaveEx method 188
F
factory objects 97 freeing objects 110 FactoryList object 180 Post method 181 Refresh method 181 FactoryProperties method AttachmentFactory object 195
471
TestDirector Open Test Architecture Guide fetching from cache 108 neighboring items 108 objects 107 FieldProperty object 172 fields actions 120 active status 84 adding 417 adding a history record 123 adding attachments 123 applying transition rules 435 BLOB 107 changing permission status 85 column name 84 column type 84 customizable or not 85 customization 416, 419 customization information 84 database key 84 database key order 84 edit mask 84 edit style 84 fetching 107 filter-enabled 84 history records 84, 347 labels 84 linked values 84 listing 126, 416 mailing change notification. See mailing change notification modification privileges 85 owner 85 posting new values 121 properties 84, 170, 172 refreshing 120, 121, 273, 287 required or not 84 saving tree node ID 84 setting values 120 size 85 storing last value 85 sum 85 system 84 table 84 transition logic 85 tree root 172 fields (cont) type 84 types 170 undoing changes to values 122 updating values 121 user column type 85 user-defined 58, 419 verification required 84 version control 85 FileData object 164 files 164 attachments 198 deleting 186 loading 183, 187 saving 185, 188 storing 182 filter object. See TDFilter object filters clearing 167, 171 filtered lists 126, 166, 168 history item 347 listing 167 search 385 search nodes 380 Find method CustomizationList object 427 ReqFactory object 220 FindChildNode method SysTreeNode object 379 FindChildren method SysTreeNode object 380 FindSimilarBugs method Bug object 340 BugFactory object 336 FindTests method SubjectNode object 385 FindTestSets method TestSetFolder object 273 First method Recordset object 160 folders adding 379 depth type 378 directory path 375 listing 380 properties 164
472
Index folders (cont) removing 381 search 379, 380 subject folder 384 system folder 377 tree path 375, 378 type 378 FollowUpManager object 190 CancelFollowUp method 192 GetFollowUp method 190 SetFollowUp method 191 graphs (cont) refreshing data 336 test progress graph 239 test set progress graph 262, 264, 278 test set summary graph 280 test summary graph 237 Groups table 88 GroupsList method CustomizationUser object 450
H
HasAlerts method IAlertable object 134 HasNewAlerts method IAlertable object 134 history filtering 347 listing 348 management 74 History object 347 ClearHistory method 347 example 349 NewList method 348 history records 350, 351 change date 75 change time 75 column name 75 index 75 new value 75 retrieving 347 storing 84 table 74 table name 75 user 75 History table 74 HistoryRecord object 350 example 350 host groups 359, 362 adding 360 attachments 86 description 86 Host_Group table 86 Host_In_Group table 87 list of 86 member hosts 87
G
get_status method RemoteAgent DCOM server 23 GetAlertList method IAlertable object 133 GetAlerts method IAlertable object 133 GetChildrenList method ReqFactory object 221 GetCoverList method Req object 228 Test object 249 GetFollowUp method FollowUpManager object 190 GetLastError method ExtendedStorage object 183 GetLicense method TDConnection object 143 GetLicenses method TDConnection object 145 GetLicenseStatus method TDConnection object 145 Graph object 342 description 342 DrillDown method 344 examples 345 MultiDrillDown method 344 graphs 4, 46 defect progress graph 331 defect summary graph 213, 215, 333 description 342 detailed cell information 342, 344 drill-down operation 344
473
TestDirector Open Test Architecture Guide host groups (cont) name 86, 87 removing 360 Host object 356 description 356 example 357 host servers 48, 356 adding 354 attachments 86 creating 353 description 86, 356 groups. See host groups Hosts table 86 Locking the Host object 356 management 86 name 86, 138 remote execution server 86 removing 354, 360 test execution host 64 time 138 Unlocking the Host object 356 Host_Group table 86 Host_In_Group table 87 HostFactory object 353 AddItem method 354 description 353 example 354 RemoveItem method 354 HostGroup object 362 AddHost method 362 description 362 example 364 NewList method 363 RemoveHost method 363 HostGroupFactory object 359 AddItem method 360 description 359 example 361 RemoveHost method 356, 360 RemoveItem method 360 Hosts table 86 HTML format 138
I
IActionPermission interface 404 IAlert interface Alert object 351 IAlertable object 132 CleanAllAlerts method 132 DeleteAlert method 132 GetAlert method 133 GetAlertList method 133 HasAlerts method 134 HasNewAlerts method 134 IAttachment interface 198 IAttachmentFactory interface 195 IBaseFactory interface 126 AddItem method 127 AttachmentFactory object 195 BugFactory object 328 ConditionFactory object 298 DesignStepFactory object 253 HostFactory object 353 HostGroupFactory object 359 IBaseFactoryEx interface 130, 132 NewList method 128 RemoveItem method 128 ReqFactory object 203 RunFactory object 310 StepFactory object 318 TestFactory object 233 TestSetFactory object 259 TSTestFactory object 304 IBaseFactoryEx interface BugFactory object 328 Mail method 130, 132 ReqFactory object 203 TestSetFactory object 259 IBaseField interface 120 Bug object 338 DesignStep object 256 Host object 356 HostGroup object 362 IBaseFieldEx interface 123 Post method 121 Refresh method 121 Run object 314 Step object 322 Test object 246
474
Index IBaseField interface (cont) TestSet object 275 TSTest object 307 Undo method 122 IBaseFieldEx interface 123 Bug object 338 DesignStep object 256 HostGroup object 362 IBaseFieldExMail interface 124 Run object 314 Step object 322 Test object 246 TestSet object 275, 289, 291 TSTest object 307 IBaseFieldExMail interface 124 Bug object 338 Mail method 124 Req object 224 Test object 246 TestSet object 275 IBug interface 338 IBugFactory interface BugFactory object 328 ICommand interface 153 ICondition interface 302 IConditionFactory interface 298 ICustomization interface 407 ICustomizationAction interface 412 ICustomizationActions interface 411 ICustomizationField interface 419 ICustomizationFields interface 416 ICustomizationList interface 426 ICustomizationListNode interface 428 ICustomizationLists interface 424 ICustomizationModules interface 451 ICustomizationPermissions interface 432 ICustomizationTransitionRule interface 439 ICustomizationTransitionRules interface 435 ICustomizationUser interface 448 ICustomizationUsers interface 445 ICustomizationUsersGroup interface 442 ICustomizationUsersGroups interface 440 IDesignStep interface 256 IDispatch ExecEventNotifyByMailSettings object 289 IDispatch interface 20, 126 IExecEventActionParams interface 293, 297 ExecEventActionParams object 293, 297 IExecEventNotifyByMailSettings interface 289, 291 IExecutionStatus interface 397 IExtendedStorage interface 182 IFactoryList interface 180 IFieldProperty interface 172 IFileData interface 164 IgnoreHtmlFormat 138 IGraph interface 342 IHistory interface 347 IHistoryRecord interface 350 IHost interface 356 IHostGroup interface 362 IHostGroupFactory interface 359 IList interface 176, 180 In 155 inherited interfaces 113 Init method ExecConfiguration ActiveX control 34 ResultViewer ActiveX control 31 ScriptViewer ActiveX control 28 TestType object 16 InitConnection method TDConnection object 139 InitConnectionEx method TDConnection object 140, 146 Insert method List object 177 Installation Guide vi IObjectLockingSupport interface 120 IParam interface 153 IReq interface 224 IReqCoverageStatus Req object 224 IReqCoverageStatus Methods 230 IReqFactory interface ReqFactory object 203 IReqSummaryStatus Req object 224 IRule interface 400 IRuleManager interface 400
475
TestDirector Open Test Architecture Guide IRun interface 314 IRunFactory interface 310 is_host_ready method RemoteAgent DCOM server 20 ISettings interface 390 IStep interface 322 IStepParams interface 325 ISubjectNode interface 384 IsValidValue method TDField object 171 ISysTreeNode interface 377 SubjectNode object 384 ITDConnection interface 135 ITDField interface 170 ITDFilter interface 166 ITest interface 246 ITestExecStatus interface 252 ITestFactory interface 233 ITestSet interface 275 ITestSetFactory interface 259 ITreeManager interface 374 ITSScheduler interface 395 ITSTest interface 307 IVCS interface 365 IVersionItem interface 373 lists (cont) child 75 comments 76 customization 424, 426 customized nodes 428 Cycl_Fold table 80 description 75 enumerator 176 factories 180 father ID 75 fields 416 filtering 166 folders 380 history 348 in user-defined field 419 item information 75 items 176 list type 76 path 76 projects 135 properties 176 refreshing 181 removing 178 requirement test coverage 228 root node 426 Rules table 80 Step_Params table 76 test coverage requirements 249 tree nodes 380 tree roots 374 updating data 181 user groups 440 user groups with action permissions 412 user-defined 426 user-defined fields 416 users 445 view order 76 Load method Attachment object 200 Customization object 409 ExtendedStorage object 183 LoadEx method ExtendedStorage object 187
L
Last method Recordset object 161 license retrieving 143, 145 status 145 List object 176 _NewEnum method 176 Add method 177 Insert method 177 Remove method 178 Swap method 178 lists action permissions 411 actions 411 adding 177 Alerts table 78 All_Lists table 75 attachments 76
476
Index locks client machine 90 entity key 90 entity type 90 IP address 90 server machine 90 session ID 90 time 90 user 90 Locks table 90 LockVcsObject method VCS object 369
N
new session 135 NewList method History object 348 HostGroup object 363 IBaseFactory interface 128 SysTreeNode object 380 TDFilter object 168 Next method -Recordset object 161
O
object TestSetTreeManager 274 object reference array indexes 114 inherited interfaces 113 integer values 114 methods notation 111 object model 97108, 109 parameters notation 111, 114 syntax notation 111 objects adding child objects 97 alphabetical reference 114 cache 108 categories 100 class factory 97 creating 97 customization 105 database management 104 fetching 107 mailing 130, 132 object model 97108, 109 performance issues 107 project management 102 Online Help vii online resources vii Open method Settings object 392 Oracle 48 OTAClient.dll 47 communicating with the TestDirector server 48 downloading 48 installing 47
M
mail customization field 421 mailing objects 130, 132 sending 147 mail conditions. See Mailcond table Mail method IBaseFactoryEx interface 130, 132 IBaseFieldExMail interface 124 Mailcond table 87 mailing change notification 70, 84, 87 memo fields IgnoreHtmlFormat 138 Mercury Interactive on the Web vii Microsoft SQL 48 modules description 95 GUID 95 ID number 95 module access 95 name 95 Modules table 95 Move method Req object 229 SubjectNode object 385 TestSetFolder object 272 MultiDrillDown method Graph object 344
477
P
parameter connection parameter 138 entity 76 name 76 notation 111 number of steps 77 primary key 76 test ID 77 value 76 password parameter. See set_value function plan_status parameter. See set_value function Post method FactoryList object 181 IBaseField interface 121 Settings object 392 SysTreeNode object 381 pre-defined test types 12 Prev method Recordset object 162 privileges. See action permissions progress bar 139 progress graphs 262, 264 defects 331 Progress method ExtendedStorage object 184 project database tables 5195 Actions 93 Alerts 78 All_Lists 75 Bug (defects) 68 Bug_Tokens 71 Cros_Ref (cross reference) 72 Cycl_Fold 80 Cycle (test sets) 62 data 54 Dataconst 89 Dessteps (design steps) 60 Groups 88 History 74 Host_Group 86 Host_In_Group table 87 Hosts 86 Locks 90 Mailcond (mail conditions) 87 Modules 95 478
project database tables (cont) Req (requirements) 56 Req_Cover (requirements coverage) 58 Rules 80 Run 65 security 52, 83 Sequence 87 Step 67 Step_Params 76 system 82 System Field 84 table relationships diagram 52 Tables 94 Test 59 TestCycl (tests assigned to test sets) 63 Tokens 71 Tran_Rules (transition rules) 90 Users 88 VC_...(shadow version control) 92 Ver_Ctrl (version control) 91 project name 138 project_name parameter. See set_value function projects accessing database 47 checking connection 138 data tables 54 establishing a connection 141 exporting information 45 importing information 45 listing 135 location 138 managing 102 security tables 52, 83 system tables 82 table relationships 52 terminating connection 142 terminating session 135 test sets 62 properties notation 110 PurgeExecutions method TestSet object 283
Index
R
Readme vii record sets 158 cloning 160 first record 160 last record 161 next record 161 number of records 158 order of records 158 previous record 162 refreshing 162 Recordset object 158 Clone method 160 example 163 First method 160 Last method 161 Next method 161 Prev method 162 Refresh method 162 Refresh method FactoryList object 181 IBaseField interface 121 Recordset object 162 StepParams object 327 SysTreeNode object 381 TDFilter object 168 TestSetFolder object 273, 287 VCS object 369 RefreshExecStatusInfo method ExecutionStatus object 398 registering custom test types 38 ReleaseConnection method TDConnection object 140, 148 releasing a server connection 140 remote agent 6 class ID 14 creating 2027 example 25 IDispatch interface 20 remote execution server 86 remote hosts 12 remote test execution 4, 12 RemoteAgent DCOM server 2027 get_status method 23 is_host_ready method 20 run method 23
RemoteAgent DCOM server (cont) set_value method 21 stop method 23 Remove method List object 178 RemoveChild method CustomizationListNode object 431 RemoveCoverage method Req object 230 RemoveFromGroup method CustomizationUser object 450 RemoveGroup method CustomizationAction object 415 CustomizationUsersGroups object 441 RemoveHost method HostGroup object 363 HostGroupFactory object 356, 360 RemoveItem method HostFactory object 354 HostGroupFactory object 360 IBaseFactory interface 128 RemoveList method CustomizationLists object 425 RemoveNode method SysTreeNode object 381 RemoveNodeEx method TestSetFolder object 271 RemoveSubjectNode method SubjectNode object 386 RemoveTransitionRule method CustomizationTransitionRules object 438 RemoveUser method CustomizationUsers object 447 CustomizationUsersGroup object 444 Rename method Attachment object 200 reports 4, 46 Req (requirements) table 56 Req object 224 AddCoverage method 226 AddCoverageEx method 227 example 231 GetCoverList method 228 Move method 229
479
TestDirector Open Test Architecture Guide Req object (cont) RemoveCoverage method 230 Req_Cover (requirements coverage) table 58 ReqFactory object 203 BuildPerfGraph method 205 BuildPerfGraphEx method 206 BuildProgressGraph method 208 BuildProgressGraphEx method 210, 241 BuildSummaryGraph method 208, 213 BuildSummaryGraphEx method 215 BuildTrendGraph method 217 BuildTrendGraphEx method 219 Find method 220 GetChildrenList method 221 requirements 224 attachment 57 author 57 comment 56 date 57 directory path 57 father 56 folder 57 ID 56, 58 listing test coverage 228 moving 229 name 57 order 56 priority 57, 225 product 57 Req table 56, 58 Req_Cover table 58 requirement coverage 58 review status 57 revision number 57 sons 57 status 57, 226 steps 58, 226, 227 task status 58 templates 56 test coverage 58, 248 tests 226, 227, 230, 249 time 57 type 57 version time stamp 57 ResolveStepsParameters method Run object 316 responsible parameter. See set_value function ResultViewer ActiveX control 3132 class ID 15 displaying test results 31, 32 Init method 31 ShowResult method 32 ShowResultEx method 31 Returns 126, 136, 137, 275, 276, 307, 314, 375, 407, 408, 411, 416 RQ 58 Rules table 80 run conditions 303 Run method CacheMgr object 402 TSScheduler object 396 run method RemoteAgent DCOM server 23 Run object 314 CopyDesignSteps method 315 CopyStepsToTest method 315 ResolveStepsParameters method 316 Run table 65 RunFactory object 310 DeleteDuplicateRuns method 311 example 312 runner_result_dir parameter. See set_value function runs. See test runs
S
sample object description 110 Save method Attachment object 202 ConditionFactory object 300 ExtendedStorage object 185 StepParams object 327 SaveEx method ExtendedStorage object 188 scheduler_version parameter. See set_value function ScriptViewer ActiveX control 2830 class ID 15 displaying test scripts 28
480
Index ScriptViewer ActiveX control (cont) example 29 Init method 28 ShowTest method 28 search cache 108 customized list node 427 defects 340 folders 379 similar defects 71, 336, 340 subject folders 385 Security objects 104 security tables 52, 83 Actions 93 Modules 95 System Field 84 Tables 94 SendMail method TDConnection object 147 sequence name 87 value 87 sequence generation diagram 87 Sequence table 87 server connection 48, 135 checking 137 establishing 135, 139, 140 terminating 135, 140 servers. See host servers sessions initiating 13, 33 terminating 33, 140, 142 set_value function 33 set_value method RemoteAgent DCOM server 21 SetCurrentVersion method VCS object 369 SetFileTime method CacheMgr object 402 SetFollowUp method FollowUpManager object 191 Settings object Close method 391 DeleteCategory method 391 DeleteValue method 391 description 390 Settings object (cont) example 393 Open method 392 Post method 392 ShowExecConfiguration method ExecConfiguration ActiveX control 35 ShowExecConfigurationEX method ExecConfiguration ActiveX control 34 ShowResult method ResultViewer ActiveX control 32 ShowResultEx method ResultViewer ActiveX control 31 ShowTest method ScriptViewer ActiveX control 28 Site Administrator, viewing project tables 51 StartExecution method TestSet object 283 Step object 322 example 323 step parameters 316, 325 Step table 67 Step_Params table 76 StepFactory object 318 description 318 example 320 StepParams object 325 AddParam method 325 ClearParam method 326 DeleteParam method 326 description 325 Refresh method 327 Save method 327 Stop method TSScheduler object 396 stop method RemoteAgent DCOM server 23 storing tests 46 subject folders 384 listing 374 search 385 subject parameter. See set_value function subject tree 374, 384
481
TestDirector Open Test Architecture Guide SubjectNode object 384 example 387, 388 FindTests method 385 Move method 385 RemoveSubjectNode method 386 summary graphs defects 333 test set 280 Swap method List object 178 Sybase 48 SynchronizeFollowUps method TDConnection object 148 syntax notation 111 sys_computer_name parameter. See set_value function sys_user_name parameter. See set_value function System Field table 84 system folders 377 System objects 104 system tables 82 Dataconst 89 Groups 88 Host_Group 86 Host_In_Group 87 Hosts 86 Locks 90 Mailcond (mail conditions) 87 Sequence 87 System Field 84 Tran_Rules (transition rules) 90 Users 88 VC_...(shadow version control) 92 Ver_Ctrl (version control) 91 system trees 374 System/Security objects 353 ActionPermission object 404 ExecutionStatus object 397 Host object 356 HostFactory object 353 HostGroup object 362 HostGroupFactory object 359 SubjectNode object 384 SysTreeNode object 377 TreeManager object 374 System/Security objects(cont) TSScheduler object 395 VCS object 365 VersionItem object 373 SysTreeNode object 377 AddNode method 379 description 377 example 382 FindChildNode method 379 FindChildren method 380 NewList method 380 Post method 381 reference from FieldProperty object 172 Refresh method 381 RemoveNode method 381
T
table relationships 52 tables data 54 security 83 system 82 Tables table 94 task status requirements 58 test sets 63 tests 60 TDAPI_host_name parameter. See set_value function TDConnection object 13, 97 ConnectProject method 139 ConnectProjectEx method 141 ConnectToVcsAs method 142 DisconnectProject method 142 examples 149 GetLicense method 143 GetLicenses method 145 GetLicenseStatus method 145 IgnoreHtmlFormat 138 InitConnection method 139 InitConnectionEx method 140, 146 ReleaseConnection method 140, 148 SendMail method 147 SynchronizeFollowUps method 148
482
Index TDField object 170 IsValidValue method 171 TDFilter object 166 Clear method 167 example 169 NewList method 168 Refresh method 168 technical support online vii templates, test requirements 56 Test Lab module 3 Test object 246 CoverRequirement method 248 example 249 GetCoverList method 249 test parameters 325 test requirements 203, 226, 227 test run scheduler 12 test runs 310, 314 attachments 66 current status 65 details 322 directory path 66 duration 65 execution date 65 execution time 65 host name 64 host server 65 locked tests (version control) 66 name 65 operating system 66 operating system build number 66 revision number of record 66 Run table 65 service pack 66 status of last run 63 steps 314 test ID 65 test instance during execution (version control) 66 test instances 66 test instances (version control) 66 test set index 65 test version 66 user responsible for 65 user-defined 66 version time stamp 66 test sets 3, 275 actual tester 64 attachments 62, 64 close date 62 comments 62 configuration 64 current version of test 64 Cycle table 62 date of next test run 64 description 62 events 62 execution events 64 folder ID 63 ID 62 mail 62 name 62 open date 62 order of tests 63 progress graph 262, 264, 278 revision number 62 revision number of a record 64 status 62 summary graph 280 task status 63 test ID 63 test instances 63 test set ID 63 TestCycl table 63 tester name 63 time of next test run 64 user-defined 62, 64 version time stamp 62, 64 test steps 322 actual results 67 adding 319 attachments 68 description 67 design step ID 67, 68 directory path 67 execution date 67 execution time 67 expected results 67 ID 67 line number 67 name 67 order 67
483
TestDirector Open Test Architecture Guide test steps (cont) removing 319 removing from requirements 230, 249 requirements 226, 227 status 67, 319 Step table 67 test ID 68 test run ID 67 test summary graph 237 Test table 59 test types 235, 247 creating 13 custom 12, 13 ExecConfiguration ActiveX control 14, 33 overview 12 pre-defined 12 registering 35 ResultViewer ActiveX control 15, 31 ScriptViewer ActiveX control 15, 28 table entry 59 test_id parameter. See set_value function test_instance parameter. See set_value function test_name parameter. See set_value function test_path parameter. See set_value function test_set_id parameter. See set_value function test_set_user1-6 parameter. See set_value function test_type.ini file 9, 35 test_user1-6 parameter. See set_value function Testcycl table 63 testcycle_id parameter. See set_value function TestDirector API accessing TestDirector API functions 47 errors 453464 integrating applications with TestDirector 6, 46 object model 97108 overview 4550 performance issues 107 terminology 50 TestDirector client 6 TestDirector documentation set vi TestDirector Installation Guide vi TestDirector online resources vii TestDirector project terminology 50 TestDirector server 48 TestDirector server, See also server connection 6 TestDirector Tutorial vi TestDirector Users Guide vi tester_name parameter. See set_value function TestFactory object 233 BuildPerfGraph method 236 BuildProgressGraph method 239 BuildSummaryGraph method 237 example 245 subject folder 384 testing tools communicating with TestDirector 5 configuration settings 33 integrating with TestDirector 310, 1142 retrieving information from the TestDirector database 21 running tests 23 tests 246 adding to VCS 366 analysis 4, 46 attachments 59 conditions 298, 302 configuration 33 coverage listing 228 coverage requirements 224, 248 creation date 59 description 59 design steps 59, 256 details 322 directory path 59 displaying results 31, 32 displaying scripts 28 entering version comments 366, 367, 368 estimated development time 59 execution date 64 execution status 60
484
Index tests (cont) execution time 64 ID 59 name 59 removing 234 removing from requirements 230, 249 repository 46 requirements 203, 226, 227 responsible user 59 results 4 revision number 59 running 23 runs. See test runs script template 17 search 385 sets. See test sets status 59 steps. See test steps stopping 23 storing 46 subject folder 59, 384 task status 60 template 60 Test table 59 types. See test types user-defined 59 version control 60 version number 366, 367, 368 version time stamp 60 TestSet object 270 BuildPerfGraph method 277 BuildProgressGraph method 278 BuildProgressGraphEx method 285 BuildSummaryGraph method 280 BuildTrendGraph method 282 CheckTestInstances method 284 example 287 PurgeExecutions method 283 StartExecution method 283 TestSetFactory object 259 BuildPerfGraph method 261 BuildProgressGraph method 262 BuildTrendGraph method 267 example 269 TestSetFolder object AddNodeDisp method 271 FindTestSets method 273 Move method 272 Refresh method 273, 287 RemoveNodeEx method 271 TestSetTreeManger object 274 TestType COM class 10 example 18 TestType object 13 TestType mechanism 8 TestType object 13 CreateScriptTemplate method 17 Init method 16 The 195, 233, 253, 259, 328 third-party testing tools. See testing tools time conditions 303 Tokens table 71 Tran_rules (transition rules) table 90 transition logic 85, 90 transition rules adding 437 applying to field 435 applying to user groups 435 assigning 432 collection of 435 defining 437, 439 removing 438 tree nodes 172, 377, 384 adding 379 depth type 378 directory path 375 finding 379 listing 380 removing 381 search 380 tree path 378 type 378 tree roots 374 TreeManager object 374 description 374 example 376 TSScheduler object 395 description 395 Run method 396 Stop method 396
485
TestDirector Open Test Architecture Guide TSTest object 307 example 309 tstest_name parameter. See set_value function TSTestFactory object 304 example 305 Tutorial vi typographical conventions in this guide ix user-defined lists adding 425 removing 425 users action permissions. See action permissions adding 446, 447 adding to user group 449 adding to user groups 443 address 89 contact information 88, 448449 customization 84, 448 listing 445 management 88 name 88, 89, 139 password 88 phone 89 removing from user group 444, 450 user groups 88 Users table 88 UsersList method CustomizationUsersGroup object 444 Utility classes 101, 135 Command object 153 ExtendedStorage object 182 FactoryList object 180 FieldProperty object 172 FileData object 164 List object 176 Recordset object 158 TDConnection object 135 TDField object 170 TDFilter object 166
U
Undo method IBaseField interface 122 UndoCheckout method VCS object 370 updates, documentation viii user actions 412 user groups action owned by 412 action permissions 94 action privileges 412 adding 441 adding action permissions 414 adding users 443, 449 applying transition rules 435 customization 440, 442 field name 91 filter 88 ID 88, 91 listing 412, 440 name 88 removing 441 removing action permissions 415 removing users 444, 450 system 88 table 88, 91 transition rule 91 user password 138 change 143 user_name parameter. See set_value function Users Guide vi user-defined fields adding 417 customizing 419 listing 416 lists 419
486
Index
V
VC_... table 92 VCS establishing a connection to 137 information 16 location 139 VCS object 365 AddObjectToVcs method 366 CheckIn method 367 CheckOut method 367 ClearView method 368 DeleteObjectFromVCS method 369 description 365 example 371 LockVcsObject method 369 Refresh method 369 SetCurrentVersion method 369 UndoCheckout method 370 ViewVersion method 370 Ver_Ctrl table 91 version control comments 91 date 91 entering version comments 366, 367, 368 entity type 91 objects version 91 primary key 91 reference ID 92 status 91 table 91 time 91 user name 91 user-defined 92 version number 366, 367, 368 Version Control System. See VCS VersionItem object 373 description 373 ViewVersion method VCS object 370 Visual Basic examples 112 Visual C++ examples 112
W
WinRunner class ID 12 ini file(wrun.ini) 12
487
488