Script Extensions: Creating a Custom Zip Code Checkpoint By Nick Olivo @ 11:11 AM

Have you ever wished that there was a checkpoint in TestComplete that performed an action specific to your unique testing needs? Well, with script extensions, now you can create your own custom checkpoints. In this article, I'll demonstrate how to create a custom checkpoint that verifies US Zip Codes are in the correct format.

Planning the Zip Code Checkpoint

Here are the criteria I used when outlining my checkpoint:

1. Users should be able to easily select the zip code field they are working with
2. Zip codes should be formatted as 5 digits (e.g., 12345) or as 5 digits followed by a dash and 4 more digits (e.g., 12345-6789).
3. A message should be written to the TestComplete log stating whether or not the indicated field had a properly formatted zip code.

With that information, we can begin writing the checkpoint.

Creating the Checkpoint

To create the zip code checkpoint, I'll start out by creating a form so I can easily select the zip code fields I want to work with. To do that, I'll add the User Forms item to my TestComplete project. Then I'll create the form as shown in this screenshot.

The following table lists the controls I placed on the form, what I named each control, and the relevant properties I set.

Object	Name	Properties
TcxLabel	lblMessage	Caption: Select the Zip code field you wish to validate
TcxTextEdit	txtZipCodeField	Text: [set to blank] Read Only: True
TcxButton	cmdOK	Caption: OK Modal Result: mrOK
TcxButton	cmdCancel	Caption: Cancel Modal Result: mrCancel
TObjectPicker	zipPicker

For the zipPicker control, I added an event called zipCodeForm_zipPicker_OnObjectPicked. Don’t worry about writing code for that yet; we’ll handle that in the next section.
With the form created, we make the form usable in an extension by right clicking on it and selecting Export to File. I exported my form as c:\zipcodeCheckpoint\zipCodeForm.aqfrm.

Next, we need to write the code for our extension. Below is the complete JScript source (including comments) for the zip code checkpoint.

//This function inserts the zip code checkpoint during design time function DesignTimeExecute() { if (showDialog()) { selectedControl = UserForms.zipCodeForm.txtZipCodeField.Text; checkTextObj = buildSyntax(selectedControl) checkText = Syntax.GenerateSource(checkTextObj) + "\r\n"; if (CodeEditor.IsEditorActive) { if (CodeEditor.CursorPos == CodeEditor.Text.length) CodeEditor.Text += checkText; else CodeEditor.Text = aqString.Insert(CodeEditor.Text, checkText, CodeEditor.CursorPos); } } } //This function inserts the zip code checkpoint while you're recording a script function RecordExecute() { if (showDialog()) { selectedControl = UserForms.zipCodeForm.zipPicker.PickedObjectName; checkTextObj = buildSyntax(selectedControl); Recorder.AddSyntaxToScript(checkTextObj); } } //This function creates the syntax object for the checkpoint. This syntax will be converted into whatever scripting language you're running, //and will then be inserted into your script. //Sample output ZipCodeCheckpoint.Validate(zipCodeField,"wText") function buildSyntax(obj) { call = Syntax.CreateInvoke(); call.ClassValue = "ZipCodeCheckpoint"; call.InvokeName = "Validate"; call.AddParameter(eval(obj)); call.AddParameter("wText"); return call; } //This function shows the zip code checkpoint form and lets users select the control they wish to validate. //If no control is selected, a warning message is displayed & prompts the user to select a control. function showDialog() { var zipDlg; zipDlg = UserForms.zipCodeForm; zipDlg.ResetForm();//Clear the form of any previously selected values if (zipDlg.ShowModal()==1) { if (UserForms.zipCodeForm.txtZipCodeField.Text == "") { //if no control is selected, display a warning message with an OK button. aqDlg.MessageDlg("Please select a control to validate.",2,4); //Once the user acknowledges the warning, redisplay the checkpoint form. showDialog(); } return true; } else return false; } //When a user selects a control with the zipPicker, the name of that control is displayed in txtZipCodeField function zipCodeForm_zipPicker_OnObjectPicked(Sender) { UserForms.zipCodeForm.txtZipCodeField.Text = UserForms.zipCodeForm.zipPicker.PickedObjectName; } //This function looks at the specified property for the given object and uses a regular expression //to confirm that it is formatted as 5 digits or 5 digits a dash and then 4 more digits function Validate(obj,property) { var re,s,target; target = obj.FullName + "." + property s= eval(target); re = /^\d{5}([\-]\d{4})?$/; r = s.match(re); if (r) Log.Message(s + " is a properly formatted zip code",obj.FullName); else Log.Error(s + " is not a properly formatted zip code",obj.FullName); }

Creating an Icon

Now, I want to be able to just click a button on a toolbar to display my zipcode form. To do that, I need an icon for my button. I’ll be the first to admit that art isn’t my strong suit, so the icon I created is very simple. I just fired up Paint .NET and created a 16x16 bmp file. Inside that file, I’m going to type the word ZIP in 6pt font, and save it as c:\zipcodecheckpoint\zipicon.bmp. Here’s the icon I created:

Gorgeous, no? :)

Creating the Description File

We also need to create a description file for our checkpoint, as shown below:
<?xml version="1.0" encoding="UTF-8"?> <ScriptExtensionGroup Name = "Custom Checkpoints"> <ScriptExtension Name = "Zip Code Checkpoint" Author = "Nick Olivo" Version = "1.0" HomePage = "www.automatedqa.com"> <Script Name = "zipCode.js"> <RecordAction Name = "Zip Code Checkpoint" Icon = "zipicon.bmp" Routine = "RecordExecute"/> <DesignTimeAction Name = "Zip Code Checkpoint" Icon = "zipicon.bmp" Routine = "DesignTimeExecute"/> <RuntimeObject Name = "ZipCodeCheckpoint"> <Method Name = "Validate" Routine = "Validate"> Verifies a text field contains a properly formatted zip code. </Method> <Description> Zip code checkpoint </Description> </RuntimeObject> </Script> <Description> Validates Zip Codes are in the correct format. </Description> </ScriptExtension> </ScriptExtensionGroup>

There are a couple of tags worth explaining here:

RecordAction – Information used when this extension is invoked during recording

DesignTimeAction – Information used when this extension is invoked during design time.

RuntimeObject – this tag puts the ZipCodeCheckpoint option in TestComplete’s code completion list.

 

These tags have some common attributes:

Name - the tooltip that will be displayed for the extension

Icon – the icon that will be shown on the toolbar for this extension

Routine - the script routine that will be called for this action.

Packaging the Extension

Unlike “traditional” plug-ins that need to be compiled, the extension’s source files just need to be packed into a ZIP archive. The archive extension should then be changed to tcx (TestComplete extension). That’s all, no other installation preparations are needed.

You can download the package here.

Installing the Extension

To install our newly created zipcode checkpoint, just copy the tcx file you just created to the ScriptExtensions directory in your TestComplete installation folder. ([TestComplete]\Bin\Extensions\ScriptExtensions)

 

Using the Extension

Once the Extension is installed, you can create zip code checkpoints while you’re recording or during design time. Just click the button on the Extension toolbar to display our zip code checkpoint form.

Then pick the control you want to work with and click OK. The zip code checkpoint will be added to your script.

You can also just type the following command into the editor:

ZipCodeCheckpoint.Validate([objectName],[property])

Where objectName is the object you wish to verify, and property is the property on that object that contains the text.

A Note

You’ll notice that by default I’m validating the wText property. In some cases, this property may not be relevant – you may want to use the value property on an HTML control, or the WndCaption on a C++ based control.  In that case, you just need to change “wText” to “value” or “WndCaption”.

Conclusion

So that’s how easy it is to create your own custom checkpoint in TestComplete. There are many other variants on what I’ve done here. You could adapt this checkpoint so it could be used to verify credit card numbers are in the correct format, or to verify social security numbers are correctly formatted. My next article will show how to create a checkpoint that verifies a list of files are present in a given directory. Until then – onward automation!