Win32::IEAutomation - Web application automation using Internet Explorer
use Win32::IEAutomation; # Creating new instance of Internet Explorer my $ie = Win32::IEAutomation->new( visible => 1, maximize => 1); # Site navigation $ie->gotoURL('http://www.google.com'); # Finding hyperlinks and clicking them # Using 'linktext:' option (text of the link shown on web page) $ie->getLink('linktext:', "About Google")->Click; # Or using 'linktext:' option with pattern matching $ie->getLink('linktext:', qr/About Google/)->Click; # Or using 'id:' option ( <a id=1a class=q href=......>) $ie->getLink('id:', "1a")->Click; # Finding checkbox and selecting it # Using 'name:' option ( <input type = "checkbox" name = "checkme" value = "1"> ) $ie->getCheckbox('name:', "checkme")->Select; # Or using 'aftertext:' option (for checkbox after some text on the web page) $ie->getCheckbox('aftertext:', "some text here")->Select; # Finding text field and entering data into it # Using 'name:' option ( <input type="text" name="username" .......> ) $ie->getTextBox('name:', "username")->SetValue($user); # Finding button and clicking it # using 'caption:' option $ie->getButton('caption:', "Google Search")->Click; # Accessing controls under frame $ie->getFrame("name:", "content")->getLink("linktext:", "All Documents")->Click; # Nested frames $ie->getFrame("name:", "first_frame")->getFrame("name:", "nested_frame"); # Catching the popup as new window and accessing controls in it my $popup = $ie->getPopupWindow("title of popup window"); $popup->getButton('value:', "button_value")->Click;
Additionally it provides methods to interact with security alert dialog, conformation dialog, logon dialog etc.
# To navigate to some secure site and pushing 'Yes' button of security alert dialog box use Win32::IEAutomation; use Win32::IEAutomation::WinClicker; # this will provide methods to interact with dialog box my $ie = Win32::IEAutomation->new(); $ie->gotoURL("https://some_secure_site.com", 1); # second argument says that don't wait for complete document loading and allow code to go to next line. my $clicker = Win32::IEAutomation::WinClicker->new(); $clicker->push_security_alert_yes(); $ie->WaitforDone; # we will wait here for complete loading of navigated site
This module tries to give web application automation using internet explorer on windows platform. It internally uses Win32::OLE to create automation object for IE. It drives internet explorer using its DOM properties and methods. The module allows user to interact with web page controls like links, buttons, radios, checkbox, text fields etc. It also supports frames, popup window and interaction with javascript dialogs like security alert, confirmation, warning dialog etc.
Win32::IEAutomation->new( visible => 1, maximize => 1, warnings => 1 )
This is the constructor for new Internet Explorer instance through Win32::OLE. Calling this function will create a perl object which internally contains a automation object for internet explorer. Three options are supported to this method in hash format. All of these are optional.
visible
It sets the visibility of Internet Explorer window. The default value is 1, means by default it will be visible if you don't provide this option. You can set it to 0 to run it in invisible mode.
maximize
Default value of this is 0, means it runs IE in the size of last run. Setting this to 1 will maximize the window.
warnings
Default value of this is 0. If you want to print warning messages for any object not found, then set it to 1. This is optional.
gotoURL($url, [$nowait])
This method navigates to the given url and waits for it to be loaded completely if second argument is not provided Second argument is optional and it represents the boolean value for not waiting till page gets loaded. Giving second argument as 1 (true boolean value) makes your code not to wait for page loading in this 'gotoURL' method. This is useful if you need to interact with any dialog like security alert. In that case use this method with second argument, then interact with dialog (methods for interacting with dialog are described below) and then using method 'WaitforDone' (described below) wait for IE to load page completely.
Back()
Works as IE's Back button and waits for it to be loaded completely
Reload()
Works as IE's Refresh button and waits for it to be loaded completely
URL()
This will return the URL of the current document
Title()
This will return title of the current document
Content()
This will return the HTML of the current document. In scalar context return a single string (with \n characters) and in list context returns array. Please note that all the tags are UPPER CASED.
VerifyText($string, [iflags])
Verifies that given string is present in the current document text. It returns 1 on success and undefined on failure. Second parameter iflags is optional. It is integer value that specifies one or more of the following flags to indicate the type of search.
0 Default. Match partial words. 1 Match backwards. 2 Match whole words only. 4 Match case.
PageText()
It returns the text in the current page. (no html tags). In scalar context return a single sting (with \n characters) and in list context returns array.
It will assist for using VerifyText method. User can print the returned array to some file and see what string he/she can pass as an argument to the VerifyText method.
WaitforDone()
Waits till IE had came out of busy state and document is loaded completly. This will poll IE for every one second and check its busy state and document complete state, before we move on.
closeIE()
It will close the instance of internet explorer.
getAgent()
It will return a reference to the Internet Explorer automation object, created using Win32::OLE.
getLink($how, $what)
This is the method to access link on web page. It returns Win32::IEAutomation::Element object containing html link element.
$how : This is the option how you want to access the link
$what : This is string or integer, what you are looking for. For this, it also supports pattern matching using 'qr' operator of perl (see example below)
Valid options to use for $how:
'linktext:' - Find the link by matching the link text i.e. the text that is displayed to the user
'id:' - Find the link by matching id attribute
'name:' - Find the link by matching name attribute
'linkurl:' - Find the link by matching url attribute of the link
'class:' - Find the link by matching class attribute
Typical Usage:
$ie->getLink('linktext:', "Sign in"); # access the link that has Sign in as its text $ie->getLink('linktext:', qr/About Google/); # access the link whose text matches with 'About Google' $ie->getLink('id:', 5); # access the link whose id attribute is having value 5
getAllLinks()
This will return a list of all links present in the current document, in form of Win32::IEAutomation::Element objects. For return value, in scalar context, gives number of links present and in list context gives array of all link objects. Each object in the array is similar to one we get using getLink method.
Methods supported for link object
Click($nowait);
Clicks the link and waits till document is completely loaded. As it uses click method of DOM, it supports clicking link with javascript in it.
$nowait: This is optional. Giving this argument as 1 (true boolean value) makes your code not to wait for complete page loading after clicking link. This is useful if you need to interact with any dialog (like logon dialog) after clicking the link. (please see logon() method example for details)
linkText();
Returns text of the link
linkUrl();
Returns url of the link
getProperty($property)
Retrieves the value of the given property for link object. This makes easy to get value of any property that is supported by html link.
getImage($how, $what)
This is the method to access image on web page. It returns Win32::IEAutomation::Element object containing html image element.
$how : This is the option how you want to access the image
'id:' - Find the image by matching id attribute
'name:' - Find the image by matching name attribute
'imgurl:' - Find the image by matching src attribute of the image
'alt:' - Find the image by matching alt attribute of the image
'class:' - Find the image by matching class attribute
$ie->getImage('imgurl:', qr/logo.gif$/); # access the image that matches logo.gif at last of string of its url (src) $ie->getImage('alt:', "Google"); # access the image whose alt attribute is 'Google' $ie->getImage('class:', $some_class); # access the image whose class attribute is having value $some_class
getAllImages()
This will return a list of all images present in the current document, in form of Win32::IEAutomation::Element objects. For return value, in scalar context, gives number of images present and in list context gives array of all image objects. Each object in the array is similar to one we get using getImage method.
Methods supported for image object
Click($nowait)
Clicks the image and waits till document is completely loaded. As it uses click method of DOM, it supports clicking link with javascript in it.
$nowait: This is optional. Giving this argument as 1 (true boolean value) makes your code not to wait for complete page loading after clicking image. This is useful if you need to interact with any dialog (like logon dialog) after clicking the image. (please see logon() method example for details)
imgUrl()
Returns url of the image
Retrieves the value of the given property for image object. This makes easy to get value of any property that is supported by html image.
getButton($how, $what)
This is the method to access button on web page. It returns Win32::IEAutomation::Element object containing html input type=button or submit element.
$how : This is the option how you want to access the button
'id:' - Find the button by matching id attribute
'name:' - Find the button by matching name attribute
'value:' - Find the button by matching value attribute
'caption:' - Find the button by matching text shown on button
'class:' - Find the button by matching class attribute
If there are more than one button having same value for the option you are quering, then it returns first button of the collection.
$ie->getButton('caption:', "Google Search"); # access the button with 'Google Search' as its caption $ie->getButton('name:', "btnG"); # access the button whose name attribute is 'btnG'
Methods supported for button object
Clicks the button and waits till document is completely loaded.
$nowait: This is optional. Giving this argument as 1 (true boolean value) makes your code not to wait for complete page loading after clicking button. This is useful if you need to interact with any dialog (like logon dialog) after clicking the button. (please see logon() method example for details)
Retrieves the value of the given property for button object. This makes easy to get value of any property that is supported by html button.
getRadio($how, $what)
This is the method to access radio button on web page. It returns Win32::IEAutomation::Element object containing html input type=radio element.
getCheckbox($how, $what)
This is the method to access checkbox on web page. It returns Win32::IEAutomation::Element object containing html input type=checkbox element.
$how : This is the option how you want to access the radio or checkbox
'id:' - Find the radio or checkbox by matching id attribute
'name:' - Find the radio or checkbox by matching name attribute
'value:' - Find the radio or checkbox by matching value attribute
'class:' - Find the radio or checkbox by matching class attribute
'index:' - Find the radio or checkbox using the index in the total collection of the radio or checkbox. (see example below)
'beforetext:' - Find the radio or checkbox before the specified text.
'aftertext:' - Find the radio or checkbox after the specified text.
If there are more than one object having same value for the option you are quering, then it returns first object of the collection.
$ie->getRadio('beforetext:', "Option One"); # access the radio which appears before text 'Option One' $ie->getRadio('value:', $radio_value); # access the radio whose value attribute is $radio_value $ie->getCheckbox('aftertext:', "Remember Password"); # access the checkbox which appears after text 'Remember Password' $ie->getCheckbox('index:', 3); # access third checkbox from the collection of checkbox on the current web page
Methods supported for radio or checkbox object
Select()
It selects the specified radio or checkbox, provided it is not already selected.
$ie->getRadio('beforetext:', "Option One")->Select;
deSelect()
It deselects the specified radio or checkbox, provided it is not already deselected.
$ie->getCheckbox('aftertext:', "Remember Password")->deSelect;
Retrieves the value of the given property for radio or checkbox object. This makes easy to get value of any property that is supported by html radio or checkbox.
getSelectList($how, $what)
This is the method to access select list on web page. It returns Win32::IEAutomation::Element object containing html select element.
$how : This is the option how you want to access the select list
'id:' - Find the select list by matching id attribute
'name:' - Find the select list by matching name attribute
'class:' - Find the select list by matching class attribute
'index:' - Find the select list using the index in the total collection of the select lists. (see example below)
'beforetext:' - Find the select list before the specified text.
'aftertext:' - Find the select list after the specified text.
$ie->getSelectList('aftertext:', "some text"); # access the select list which appears after text 'some text' $ie->getSelectList('name:', 'time_zone'); # access the select list whose name attribute is 'time_zone' $ie->getSelectList('index:', 3); # access third select list from the collection of select lists on the current web page
Methods supported for select list object
SelectItem()
It selects one or more items from the select list. You can pass a single or multiple item to this method. Provide the name of item which is visible to user on web page ( and not that is in html code). Use this method for selection of multiple items only if select list is supporting multiple selection.
$ie->getSelectList('name:', 'time_zone')->SelectItem("India"); # selects one item "India" in the select list $ie->getSelectList('name:', 'time_zone')->SelectItem("India", "U. S. A.", "Australia"); # selects three items "India", "U. S. A." and "Australia" in the select list
deSelectItem()
It deselects one or more items from the select list. You can pass a single or multiple item to this method. Provide the name of item which is visible to user on web page ( and not that is in html code)
$ie->getSelectList('name:', 'time_zone')->deSelectItem("India"); # deselect one item "India" in the select list $ie->getSelectList('name:', 'time_zone')->deSelectItem("India", "U. S. A.", "Australia"); # deselect three items "India", "U. S. A." and "Australia" in the select list
deSelectAll()
It deselects all items from the select list. Call this method without any argument. This method is useful, when a select list appears with a random selected item and you need to deselect that.
$ie->getSelectList('name:', 'time_zone')->deSelectAll(); # deselect all items in the select list
Retrieves the value of the given property for select list object. This makes easy to get value of any property that is supported by html select list.
getTextBox($how, $what)
This is the method to access input text field on web page. It returns Win32::IEAutomation::Element object containing html input type=text or password element. Additionaly this method works for file upload text field also. (i.e. input type=file).
getTextArea($how, $what)
This is the method to access input text area on web page. It returns Win32::IEAutomation::Element object containing html textarea element.
'id:' - Find the text field by matching id attribute
'name:' - Find the text field by matching name attribute
'value:' - Find the text field by matching value attribute
'class:' - Find the text field by matching class attribute
'index:' - Find the text field using the index in the total collection of the text fields. (see example below)
'beforetext:' - Find the text field before the specified text.
'aftertext:' - Find the text field after the specified text.
$ie->getSelectList('aftertext:', "User Name:"); # access the text fields which appears after text 'User Name:' $ie->getSelectList('name:', 'password'); # access the text field whose name attribute is 'password' $ie->getSelectList('index:', 3); # access third text field from the collection of text fields on the current web page
Methods supported for text field object
SetValue($string)
It will set the value of text field or text area to the string provided.
$ie->getTextBox('name:', "q")->SetValue("web automation"); # it will enter text 'web automation' in the input text filed. $ie->getTextBox("name:", "importFile")->SetValue("C:\\temp\\somefile"); # to set somefile in file upload text field
GetValue()
It will return the default text present in the textbox or text area.
$ie->getTextBox('name:', "q")->GetValue() # return the default text present in the textbox
ClearValue()
It will clear the text field.
$ie->getTextBox('name:', "q")->ClearValue() # it will clear the input text field
Retrieves the value of the given property for text field object. This makes easy to get value of any property that is supported by html input text field.
getTable($how, $what)
This is the method to access table on web page. It returns Win32::IEAutomation::Table object containing html table.
'id:' - Find the table by matching id attribute
'name:' - Find the table by matching name attribute
'value:' - Find the table by matching value attribute
'class:' - Find the table by matching class attribute
$ie->getTable("id:", "1a"); # access the table whose id attribute is '1a' $ie->getTable("class:", "data") # access the table whose class attribute is 'data'
getAllTables()
This will return array containing all table on that page. Each element of an array will be a Win32::IEAutomation::Table object.
my @alltables = $ie->getAllTables;
Methods supported for table object
rows([index of row])
This method returns the row object/objects from the table. It takes an optional argument, the index number of the row you wish to take. If this method is used without any argument then it returns array of row objects in the table. And if you provide an argument, then it returns a scalar row object present at specified index. The rows are counted inclusing header row.
my @all_rows = $table_object->rows; # get collection of all row objects in the table my $third_row = $table_objects->rows(3) # get third row of the table.
getRowHavingText($string);
This method returns a single row object that contains specifed text. If the text string is present in any of the row of the table, then that row objetc is returned. This method supports perl pattern matching using 'qr' operator.
my $target_row = $table_object->getRowHavingText("Last Name:"); # access the row which contains text "Last Name:". It will try to match eaxact string. my $target_row = $table_object->getRowHavingText(qr/First Name:/); # access the row by pattern matching text "First Name:"
tableCells([$row, $column])
This method returns an array of all cell objects present in the table. Each element of the array will be a cell object. Please see below for methods on cell object. Additionaly it also supports two optional parameters, first parameter is index of the row and second is index of column. When these two parameters are used, it returns a scalar cell object using combination of row and column index.
my @allcells = $table_object->tableCells; # get all cell objects in an array my $target_cell = $table_object->tableCells(2, 5); # get cell at second row and fifth column
Methods supported for row object
cells([index of cell])
This methos returns an array of cell objects present in that cell. Each elemnt of an array will be a cell object. Additionaly it supports one optional parameter, cell index. If this method is used without any argument then it returns array of cell objects in that row. And if you provide an argument, then it returns a scalar cell object present at specified index.
my @all_cells = $row_object->cells; # get collection of all cell objects in that row my $third_cell = $table_objects->cells(3) # get third cell of that row.
Methods supported for cell object
cellText
It returns a text present in that cell.
$text = $cell_object->cellText; # access the text present in that cell.
In addition to this, all methods listed under LINK METHODS, IMAGE METHODS, BUTTON METHODS, RADIO and CHECKBOX METHODS, SELECT LIST METHODS, TEXTBOX and TEXTAREA METHODS are supported on cell object.
getFrame($how, $what)
It will return the Win32::IEAutomation object for frame document. Frame document is having same structure as that of parent IE instance, so all methods for link, button, image, text field etc. are supported on frame object.
'id:' - Find the frame by matching id attribute
'name:' - Find the frame by matching name attribute
'value:' - Find the frame by matching value attribute
'class:' - Find the frame by matching class attribute
$ie->getFrame('id:', "f1"); # access the frame whose id attribute is 'f1' $ie->getFrame('name:', 'groups'); # access the frame whose name attribute is 'groups'
To control any objects under frame, first get the frame object using 'getFrame' method and then use other methods (getLink, getRadio etc.) to access objects.
$ie->getFrame('name:', 'groups')->getRadio('beforetext:', "Option One")->Select; # select the radio which is under frame
There might be case of frame inside frame (nested farmes), so use getFrame method uptp target frame
$ie->getFrame("name:", "first_frame")->getFrame("name:", "nested_frame");
Methods supported for frame object
All methods listed under GENERIC METHODS, LINK METHODS, IMAGE METHODS, BUTTON METHODS, RADIO and CHECKBOX METHODS, SELECT LIST METHODS, TEXTBOX and TEXTAREA METHODS, FRAME METHODare supported.
getPopupWindow($title)
It will return the Win32::IEAutomation object for popup window. Popup window is having same structure as that of parent IE instance, so all methods for link, button, image, text field etc. are supported on popup object.
Provide the exact title of the popup window as an argument to this method.
$ie->getPopupWindow("Popup One"); # access the popup window whose title is "Popup One"
To control any objects under popup, first get the popup object using 'getPopupWindow' method and then use other methods (getLink, getRadio etc.) to access objects.
my $popup = $ie->getPopupWindow("Popup One") # access the popup window $popup->getRadio('beforetext:', "Option One")->Select; # select the radio
There might be case where popup takes time to load its document, so you can use 'WaitforDone' method on popup
my $popup = $ie->getPopupWindow("Popup One") # access the popup window $popup->WaitforDone; # wait so that popup will load its document completly
Methods supported for popup object
All methods listed under GENERIC METHODS, LINK METHODS, IMAGE METHODS, BUTTON METHODS, RADIO and CHECKBOX METHODS, SELECT LIST METHODS, TEXTBOX and TEXTAREA METHODS, FRAME METHOD are supported.
Win32::IEAutomation::WinClicker class provides some methods to ineract with dialogs like security alert, confirmation dialog, logon dialog etc. COM interface to AutoIt (http://www.autoitscript.com/autoit3/) is used to implement these.
You need to create a new instance of Win32::IEAutomation::WinClicker and then use these methods.
Win32::IEAutomation::WinClicker->new( warnings => 1)
push_security_alert_yes($wait_time)
It will push the 'Yes' button of Security Alert dialog box. Provide wait time so that it will wait for Security Alert dialog box to appear. Default value of wait time is 5 seconds (if wait time is not provided). It will timeout after wait time, and execute next line of code.
push_button_yes($title, $wait_time)
It will push 'Yes' button of window which is having provided title.
$title: Provide exact title of dialog box
$wait_time: Provide wait time so that it will wait for confirmation dialog box to appear. Default value of wait time is 5 seconds (if wait time is not provided). It will timeout after wait time, and execute next line of code.
push_confirm_button_ok($title, $wait_time)
It will push the 'OK' button of any confirmation dialog box.
push_confirm_button_cancle($wait_time)
It will push the 'Cancle' button of any confirmation dialog box.
logon($title, $user, $password, $wait_time)
It will fill the logon dialog box with user name and password, and then press enter.
$title: Provide exact title of logon doalog box
$user: Provide user name to enter
$password: Provide password to enter
$wait_time: Provide wait time so that it will wait for logon dialog box to appear. Default value of wait time is 5 seconds (if wait time is not provided). It will timeout after wait time, and execute next line of code.
# To navigate to some authenticated site and pushing 'Yes' button of security alert dialog box use Win32::IEAutomation; use Win32::IEAutomation::WinClicker; # this will provide methods to interact with dialog box my $ie = Win32::IEAutomation->new(); $ie->gotoURL('http://pause.perl.org'); $ie->getLink('linktext:', "Login")->Click(1); # providing no wait argument says that don't wait for complete document loading and allow code to go to next line. my $clicker = Win32::IEAutomation::WinClicker->new(); $clicker->logon("Enter Network Password", $user, $password, $wait_time); # here 'Enter Network Password' is the title of log on window $ie->WaitforDone; # we will wait here for complete loading document
Prashant Shewale <pvshewale@gmail.com>
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
42 POD Errors
The following errors were encountered while parsing the POD:
Expected '=item *'
Unknown directive: =over4
'=item' outside of any '=over'
To install Win32::IEAutomation, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::IEAutomation
CPAN shell
perl -MCPAN -e shell install Win32::IEAutomation
For more information on module installation, please visit the detailed CPAN module installation guide.