Phantom Documentation

[Help Home] [Phantom Home]
Simple Automation Tutorial

This tutorial performs a simple automation 'test'. The test will emulate an input validation test using the Phantom Target application. While there is no processing of the input by Phantom Target, this illustrates, in a simple way, how Phantom can be used to perform automated testing.

The tutorial does some simple inputs into an edit field. Those inputs are then inserted into a ComboBox through interaction with the PhantomTarget user interface. The inputs are then validated using some ComboBox member functions. If the validations fail, exceptions are thrown to indicate an error has occurred.

The PhantomTarget declarations file (PhantomTarget.dec) included with Phantom should be used for this tutorial. If a separate declarations file was created in the Hello Phantom tutorial, the ComboBox controls window needs to be added to the declarations file. To do this, follow steps 7-10 where the declarations file is made (after opening the declarations file in WinDR by clicking 'Open File' and navigating to the location of the .dec file). Instead of selecting 'EditBox' from the 'Controls' menu, select 'ComboBox'.

This tutorial assumes the Hello World, Hello Phantom, and Exceptions tutorials have been reviewed.


The tutorial begins by including the declarations file with the 'use' statement. Now the PhantomTarget window variable and the ComboBox window variable will be available to the script. An exception variable is also declared so exceptions can be thrown later.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;


In the next part, the PhantomTarget application is launched using the System command.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");


Now, the Exists function is used to verify that the PhantomTarget was launched successfully. The Exists function looks for the window 'PhantomTarget', and if it exists it returns true. If the window does not exist, it returns false. In this case, if it returns false, an exception is generated and thrown, indicating there was a problem starting the application.

Note that a Sleep statement is placed prior to using the Exists function. This is because the Exists function checks immediately for the existence of the PhantomTarget window. However, the PhantomTarget application takes a small amount of time to actually create and display the window. Therefore, without the Sleep function, the Exists function may return false because the PhantomTarget is not displayed fast enough. In this case, Sleep pauses the script execution for 1/2 a second before continuing. The WaitForWindow function can also be used in place of Exists, removing the need for a Sleep statement.

Not waiting long enough for windows to appear is a common cause of Phantom generated errors. If Phantom cannot find a window, it will produce an error after trying for several seconds. Using Sleep statements or WaitForWindow statements can alleviate some of these errors.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}


The next section opens the ComboBox controls dialog by selecting the 'ComboBox' menu item from 'Controls' in the main window. It also uses Sleep to wait 1/2 a second for the window to appear and then verifies its existence similarly to the previous section.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}


Now a bitmap of the ComboBox control in the dialog will be captured using the CaptureBitmap function. Only the contents of the ComboBox will be captured. The result will be stored in a bitmap variable. This will be used later as part of the verification that the ComboBox contents have been updated.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();


A new element will now be added to the ComboBox. This will be done by interacting with controls in the ComboBox dialog box. First, the text name of the new element will be set in the edit field (using SetText) in the dialog. Then the new element will be added by clicking the 'Insert' button (using Click).

Two additional elements are added in the same way. As each item is inserted, it will appear in the ComboBox list. The script will later verify that these items were added to the ComboBox successfully.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();


Now the script will begin verifying the contents of the ComboBox to 'test' that the ComboBox elements were inserted correctly. In this tutorial, no special processing was done by PhantomTarget with the elements before they were inserted into the ComboBox. However, for a real target application, some processing may have been done by the application. Phantom code similar to the following can be used to verify the processing was done correctly by comparing what the ComboBox holds to what the expected values are. In this case, no processing was done, so the expected values are simply the values that were entered.

The verification starts by capturing the bitmap of the ComboBox again. This bitmap is compared to the previously capture bitmap. If the bitmaps are the same, then the insertion of the elements failed (because the contents of the ComboBox did not change). If they are different, then the ComboBox changed as expected. This will not verify the values, but will verify that the ComboBox visually updated properly. The two bitmaps are compared using the equality (==) comparison. If they are the same, an exception is thrown.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Capture the bitmap again to verify
# the combobox contents changed
bitmap b2 = Combo.ComboBox1.CaptureBitmap();

# Compare the bitmaps, and if they are the
# same, then error out (they should have
# changed).
if(b1 == b2){
  ex.SetError("ComboBox did not work");
  ex.throw();
}


The next section of the script verifies the number of values in the ComboBox matches the expected number of values (3). It does this by using the GetCount method. If the count does not match the expected count (using the inequality, !=), an exception is thrown.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Capture the bitmap again to verify
# the combobox contents changed
bitmap b2 = Combo.ComboBox1.CaptureBitmap();

# Compare the bitmaps, and if they are the
# same, then error out (they should have
# changed).
if(b1 == b2){
  ex.SetError("ComboBox did not work");
  ex.throw();
}

# Get the number of elements in the
# combo box and verify there are 3
int iCount = Combo.ComboBox1.GetCount();
if(iCount != 3){
  ex.SetError("Count should be 3");
  ex.throw();
}


Now the actual values of the ComboBox are compared against the expected values. This will be done by cycling through the elements using a 'for' statement. The 'for' statement will start at element 0 (int i = 0) and go to element 'count - 1' (i < iCount). It will increment i by 1 after each cycle (i++). The counter starts at 0 because element indices in a ComboBox are zero-based. In other words, to retrieve the first element, use index 0, for the second element, use index 1, for the third, use 2, and so on. Once the counter 'i' is greater than or equal to iCount (the number of elements), the loop will stop.

Each element is retrieved using the GetElement member function. For a ComboBox, this function returns a string containing the text value of the specified ComboBox element.

The comparison part uses a little trick. Since the expected value for each element is "Item " followed by a number representing its position in the list, the expected value can be generated automatically using the for loop counter. This is done by creating a string from 'i+1' (+1 because i is zero based) using the string function and concatenating it with"Item ". The result is compared against the value obtained from the ComboBox using the inequality operator. If the expected value does not match the actual value, an exception is thrown.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Capture the bitmap again to verify
# the combobox contents changed
bitmap b2 = Combo.ComboBox1.CaptureBitmap();

# Compare the bitmaps, and if they are the
# same, then error out (they should have
# changed).
if(b1 == b2){
  ex.SetError("ComboBox did not work");
  ex.throw();
}

# Get the number of elements in the
# combo box and verify there are 3
int iCount = Combo.ComboBox1.GetCount();
if(iCount != 3){
  ex.SetError("Count should be 3");
  ex.throw();
}

# Declare a variable to hold the
# combobox values
string sValue;

# Cycle through each element in the
# combobox and retrieve its value.
for(int i = 0; i < iCount; i++){
  # Retrieve the element and display it
  sValue = Combo.ComboBox1.GetElement(i);
  disp(sValue);

  # Compare the element to the expected
  # value.
  if(sValue != "Item " + string(i+1)){
    ex.SetError("Value does not match");
    ex.throw();
  }
}


All of the verifications of the data have now been made. If no exceptions were thrown, it is time to exit gracefully by closing the ComboBox dialog and the PhantomTarget application. The ComboBox dialog will be closed by clicking the OK button. The script will then wait for 1/2 of a second for the ComboBox dialog to close, and then verify that it closed using the Exists function. However, in this case, an error will be generated if the Exists function returns true (indicating the ComboBox window did not close).

The Phantom Target application will then exit using the Close member function. Finally, a message will be displayed indicating the script ran successfully.

Example Code

Line

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";


# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Capture the bitmap again to verify
# the combobox contents changed
bitmap b2 = Combo.ComboBox1.CaptureBitmap();

# Compare the bitmaps, and if they are the
# same, then error out (they should have
# changed).
if(b1 == b2){
  ex.SetError("ComboBox did not work");
  ex.throw();
}

# Get the number of elements in the
# combo box and verify there are 3
int iCount = Combo.ComboBox1.GetCount();
if(iCount != 3){
  ex.SetError("Count should be 3");
  ex.throw();
}

# Declare a variable to hold the
# combobox values
string sValue;

# Cycle through each element in the
# combobox and retrieve its value.
for(int i = 0; i < iCount; i++){
  # Retrieve the element and display it
  sValue = Combo.ComboBox1.GetElement(i);
  disp(sValue);

  # Compare the element to the expected
  # value.
  if(sValue != "Item " + string(i+1)){
    ex.SetError("Value does not match");
    ex.throw();
  }
}

# Close the window by clicking its
# OK button.
Combo.OK.Click();

# Give time for OK to close the window
Sleep(0.5);

# Check to make sure the OK worked
if(Exists(Combo)){
ex.SetError("OK did not work");
ex.throw();
}

# Exit out of PhantomTarget by using
# the Close function.
PhantomTarget.Close();

# Display a message indicating the
# script succeeded.
disp("Script completed successfully");


Save and run the script as described in the Hello World tutorial. The PhantomTarget application should start and the ComboBox dialog should open. Each element, "Item 1", "Item 2", and "Item 3" will be entered into the ComboBox. Each element will then be displayed in the output and the ComboBox window will be closed. Finally, the success message should be displayed. If any errors occur, they will be displayed in the output and the script execution will terminate. The output should look like the following if no errors occur:

Output
Item 1
Item 2
Item 3
Script completed successfully


This concludes the tutorial. This illustrated a very simple automation case. There are many additional functions and features in Phantom. For more information, see the following sections of the documentation:

    Functions
    Flow Control
    Variables
    Keywords
    The window data type
    Window Types
    Arrays
    String Operations
    Math Operations


Copyright 2000-2011 Phantom Automated Solutions