User Forms in TestComplete
Test and Monitor | Posted January 16, 2007

TestComplete 5 includes the User Forms feature that allows testers to create custom forms and display them during their tests. In my previous post, I explained that User Forms can be used to select a test to be run. In this post I’ll illustrate this using an example.

Creating a TestComplete Project with a Form

To begin, start TestComplete and create a new project. In order to use custom forms in our project, we have to add the User Forms project item:

  • Right-click the project node in the Project Explorer and select Add | New Item in the context menu;
  • Choose the User Forms item in the ensuing dialog box.

After we have added the User Forms project item, we can add a form to our project:

  • Right-click the User Forms node in the Project Explorer, and select Add | New Item in the context menu.
  • TestComplete will ask for the form name. Leave the default name, UserForm1.

After closing the dialog, TestComplete opens the forms designer and displays the newly created empty form.

First, let’s specify the form title text. In the Properties pane on the right you can see a list of properties for the form. Find the Caption property and type “Select Test” (without quotes) in the property value cell. Then click the form and the caption will update:

Placing Controls onto the Form

We need a group several (say, three) radio buttons in our form. These will be used to select one out of three tests to be run, and will also include OK and Cancel buttons that will be used to close the form and start or cancel the test run.

To place a control onto the form, you have to select the desired control in the Components palette and click the form in the location where you want to place the control. To position the control on the form, you can drag it to the desired location using the mouse or specify the desired coordinates for the top left corner of the control in the Top and Left properties.

First, let’s add a group of three radio buttons to the form:

  • Click the TcxRadioGroup control in the palette (it is situated on the Extra tab).
  • Place the control on the top of the form.

As you can see in the designer, the group caption is “cxRadioGroup1”. Let’s change it to something that makes more sense and is more descriptive:

  • Click the radio group control on the form.
  • In the Properties window, find the Caption property and specify “Select test to run:” (without quotes) in the property value cell.

Now let’s add radio buttons to the group:

  1. Expand the Properties node in the Properties window and select the Items property.
  2. Click the ellipsis button within the property cell. This will evolve the radio buttons editor.
  3. Press the New Item button. This will add a new button to the group.
  4. In the Properties window, enter “Test 1” (without quotes) in the Caption property value cell.

Repeat steps 3 and 4 to add two more radio buttons with captions “Test 2” and “Test 3”. After that, close the radio buttons editor window. Now our form looks like:


Finally, we only need to add OK and Cancel buttons to our form. To add the OK button:

  • Place a TcxButton control (from the Buttons category) on the form.
  • In the Properties window, specify “OK” (without quotes) in the Caption property.
  • Specify mrOk in the ModalResult property (this property designates the button’s result – OK, Cancel, Yes, No or other).
  • Set the Default property to True (this will mark the button with a thick border and make this button be clicked upon the Enter key press.

Steps to add the Cancel button:

  • Place another TcxButton control on the form.
  • In the Properties window, specify “Cancel” in the Caption property.
  • Specify mrCancel in the ModalResult property.
  • Set the Cancel property to True (this makes the button be clicked when the user presses Esc).

After we have placed and arranged all controls, our form should look like the image below:

Displaying the Form and Obtaining Form Result

The script below displays our form and checks the form’s dialog result. When the tester pressed the OK button on the form, it runs the routine that corresponds to the radio button selected in the form, or posts the error message to the test log if an option was not selected. To display the form, we use the UserForms.UserForm1.ShowModal method. It returns the value that indicates which form button was pressed. To determine which radio button was selected, we use the control’s ItemIndex property, which holds the zero-based index of the selected button. If no button is selected, the ItemIndex property holds -1.