Cool Tool Guide for Attachmate API Testing

The Cool Tool records the sequence of API calls and function arguments the user -- a customer or tester -- specifies. The resulting script can be attached to a bug report so someone in Product Management or Development can duplicate interesting behavior. The script can also be used to generate a test script, which is nearly identical to the recording except that when it is generated as the test script plays, the return code is added. The new test script can then be played back later as a regression test and, as each line is executed the return code is checked with the value returned when it was originally recorded. The Cool Tool can open an Extra! API trace and convert it to the Cool Tool's standard scripting format so that it can be replayed, which is another way to capture the user's or tester's observation that can be played back in a debugging session. The Cool Tool playback and test dialog.

The Cool Tool script recording dialog.

The Cool Tool script editor dialog.

The Cool Tool script playback scheduler dialog.

One more important Cool Tool feature is its recording scripts can also be translated to C++, JavaScript, or VBScript source code. Cool Tool users can generate programs based on scripts recorded in the Cool Tool recorder or from Extra! API traces. With that, a user can regenerate lost code, translate an API client from one programming language to another, and translate for use on a different Attachmate product. The Cool Tool script playback scheduler dialog.

File\Open recording

Open a recording file that was created by the Function Runner, the Script Editor, or with a text editor.

Recording files are intended to do no more than to replay a sequence of API calls and so no return values are checked during each API call.

Example:
An example of the file format used in recordings:

	Function: Connect
	FuncNumber: 1
	String: a
	Length: 1
	RetCode: 

	Function: SendKeys
	FuncNumber: 3
	String: disconnect@E
	Length: 12
	RetCode: 

	Function: Disconnect
	FuncNumber: 2
	String: a
	Length: 1
	RetCode: 
 

File\Append recording

Add a file to the end of the one present in the view.

File\Open test

Open a test file created in the test generator, test editor, or any text editor.

Test files are used in running regression, functional, repetition, and stress tests. They include the input parameters as seen above in the recording files together with the expected string, string length, and return code values.
When the API call completes using the test file input parameters, the return values are compared with the expected values listed in the even numbered row in the test file. If a difference is found a failure is signaled.

Example:
An example of the file format used in test files:

	Function: Connect
	FuncNumber: 1
	String: a
	Length: 1
	RetCode: 0

	StringExp: a
	LengthExp: 1
	RetCodeExp: 1



	Function: SendKeys
	FuncNumber: 3
	String: disconnect@E
	Length: 12
	RetCode: 0

	StringExp: disconnect@E
	LengthExp: 12
	RetCodeExp: 1


	Function: Disconnect
	FuncNumber: 2
	String: a
	Length: 1
	RetCode: 0

	StringExp: a
	LengthExp: 1
	RetCodeExp: 1
 

File\Open results file

Open a test file error incidence report. When a test has been run and the results saved, the incidence file will contain a list of all function calls that returned different values than were expected. The CooHLL TooHLL system can be configured to append all test results to one file or to create a new file for each test.
A test results file is an HTML file so it can be read in a web browser from a machine apart from where the results file is stored.

File\Open API trace file

Read the inward/outward bound API calls that were saved into a myExtra! API trace file and list them in the CooHLL TooHLL view.

An API trace read into the view can be sorted, searched, and filtered. It can also be played back as a recording, run as a test, or edited in the test editor.

Edit\Options

Set the values for options that control various tests.

Thread count -- specify the number of concurrent threads to run in a stress test. The open test file will be run on each new thread.
Thread spacing -- specify the time, in seconds, between the spawning of each new thread in the stress test.
Iterations -- specify the number of consecutive times that the open test will be run.
Clear settings -- Remove all CooHLL TooHLL settings from the registry

View\Filter view

Filter all functions from the view window except for the one you specify.

View\Clear view

Clear all entries from the view window.

View\Find string

Find a string that you specify in the view.

Tools\Recording editor

Open an existing recording and change or add values as desired.

Dialog controls:
Specify function -- double click a function entry to insert it into the edit field.

Select edit, insertion, or deletion line -- choose the line that you choose to edit, double click on it to place it in the edit fields. Edit it and then clickthe Apply changes button to reinsert it in the recording.

Apply changes -- move the changes to the edited API command back to the list.

Append entry -- add a copy of the currently edited API command to the end of the list.

Browse for script -- open the recording file that you want to edit. It will be loaded into the list control.

Tools\Test editor

As currently written, provides the user with a means to specify expected return values for the API calls in an existing recording. Assign and insert a line that contains a set of string, string length, and return code values that will be compared with the actual values when a test is run. You must open an existing recording file and insert expected value lines as desired.

Tools\Translator

Open a recording file and translate its sequence of commands to a source file in a different language. Language options include C++, JavaScript, and VBScript. Output application targets include EHLLAPI, WHLLAPI, OLE Automation, and MCS headers and footers.

Tools\Scheduler

Specify the time and date that the loaded test is to be run. You may also specify that the same test be run repeatedly on several different days of the week.

Run\Recording generator

Generate a recording file that contains a pre-programmed set of calls. This resulting recording file will contain an example of each call so you can use it as an example for manual editing of recording files or as a basic regression/functionality test.

Run\Playback recording

Playback the currently loaded recording. No return values will be compared, and no regression analysis will be performed on the results.

Normally, the recording file that contains a call sequence that can duplicate a customer issue will be attached to a case document and linked PDA. Using that file, others in Customer Support, Development, or QA have a quick and simple way to see the issue as reported and then to see that the issue no longer exists after a code or configuration fix has been applied.

Run\Test generator

Convert the now-open recording to a test file by replaying the recording. As the recording runs, the results will be saved as the expected return values that distinguish the structure of a test file from that of a recording file.

Run\Functions

Enter and perform a sequence of API calls. Choose whether or not you want to record the session to a recording or test file.

This can be used to simply perform a simple test of API calls or to duplicate and record a call sequence, such as those necessary to duplicate a customer issue described in a Customer Support Vantive case. A customer issue duplicated in this way can be attached to the case and PDA for use by the developer assigned to fix the case and for the QA engineer assigned responsibility for the fix's validation.

Run\Regression test

Playback a recording file and perform a checksum comparison of the results to see if any differences exist between an earlier run of the same recording and this run.

It is common to compare the results of a regression run with those from another test that used a previous product build or version. Also, a regression test can be run against a different product, to determine cross-vendor compatibility or competetive analysis.

Run\Functional test

Run the currently open test file. The expected return values will be compared to the actual generated as the test runs. Any differences will be noted in the view's Result column and written to an HTML error incidence file.

Run\Repetition test

Run the currently opened recording the number of times specified within the Edit\Options dialog.

This test is intended to reveal memory leaks by running a suspect API method a large number of times.

Run\Stress test

Run the currently opened recording concurrently on several different threads to test the load capabilities of the myExtra! terminal and connection tools, as well as the API's remote process call mechanisms.

The number of different threads the test will run on and the time delay between thread start times is set in the Edit\Options dialog.

Run\Performance test

The currently opened recording will be run and the start and return times will be logged.

This test can demonstrate the performance effect of changes made from one build to another, one version to another, or one product to another.

Run\File transfer test

Perform an exhaustive set of file transfers that involve all combinations of file transfer options. The results of each transfer will be compared with a previous run of the test.

The benefits of this test are the regression of file transfer within a product, emulation validation (e.g. same results as in PComm ), and competitive analysis with other vendors' products.

Run\Event handler test

Interactive test of status, screen, and keyboard events.

Help\About CooHLL TooHLL

Read about the product language, version, and copyright.