The renewal maintenance has officially ended for Progress iMacros effective November 30, 2023.
This Wiki site will also no longer be moderated from the Progress side.
Thank you again for your business and support.
Sincerely, The Progress Team
Difference between revisions of "iimOpen"
(31 intermediate revisions by 5 users not shown) | |||
Line 2: | Line 2: | ||
− | Initializes the Scripting Interface. It opens a new instance of the iMacros Browser, IE or Firefox, or connects to an existing instance (depending on the specified parameters). If the command fails for any reason it returns an [[ | + | Initializes the Scripting Interface. It opens a new instance of the iMacros Browser, IE or Firefox, or connects to an existing instance (depending on the specified parameters). If the command fails for any reason it returns an [[iimOpen#Return_values|error code]]. |
'''Note:''' You must call iimOpen before calling any other scripting interface functions like iimSet or iimPlay. | '''Note:''' You must call iimOpen before calling any other scripting interface functions like iimSet or iimPlay. | ||
− | === Syntax === | + | === Syntax [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]] [[Image:Cr-icon.png|Chrome]] === |
− | int ret_code = iimOpen( String commandLine [, boolean openNewBrowser] [, int timeout]) | + | int ret_code = iimOpen( [String commandLine] [, boolean openNewBrowser] [, int timeout]) |
In some languages you might be able to omit some or all the parameters, but if you would like to input timeout, you will have to include all of them. | In some languages you might be able to omit some or all the parameters, but if you would like to input timeout, you will have to include all of them. | ||
Line 17: | Line 17: | ||
iimOpen("-ie", true, 300); | iimOpen("-ie", true, 300); | ||
+ | |||
+ | In Python, True and False must be specified with initial caps: | ||
+ | |||
+ | iimOpen ("-ie", True, 300); | ||
+ | |||
+ | or, you can also specify an integer value (1=True, 0=False) | ||
+ | |||
+ | iimOpen ("", 0) | ||
In Delphi | In Delphi | ||
Line 22: | Line 30: | ||
iimOpen ('-ie', true, 300); | iimOpen ('-ie', true, 300); | ||
− | In | + | In VBScript can you can simply use |
iimOpen("-ie") | iimOpen("-ie") | ||
Line 28: | Line 36: | ||
or | or | ||
− | iimOpen("-ie", | + | iimOpen("-ie", True, 300) |
You find more code examples for other languages in our [[Sample Code]] section. | You find more code examples for other languages in our [[Sample Code]] section. | ||
Line 34: | Line 42: | ||
=== Parameters === | === Parameters === | ||
− | *String commandLine | + | *String commandLine |
− | *:Specifies | + | *:Specifies iimOpen options. All options start with a dash (-). Possible options are detailed below. |
− | + | ||
− | + | *boolean openNewBrowser | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | *boolean openNewBrowser | ||
*:Specifies whether to create a new iMacros Browser, Firefox or Internet Explorer process. | *:Specifies whether to create a new iMacros Browser, Firefox or Internet Explorer process. | ||
*:If set to ''false'', iMacros Scripting Interface looks around for '''uncontrolled''' instances (that is, not connected to a scripting interface) and attaches to any one found. If none is found, it will create a new process and connect to it. | *:If set to ''false'', iMacros Scripting Interface looks around for '''uncontrolled''' instances (that is, not connected to a scripting interface) and attaches to any one found. If none is found, it will create a new process and connect to it. | ||
*:Default is ''true''. | *:Default is ''true''. | ||
+ | |||
*Long timeout | *Long timeout | ||
− | *: | + | *:iimOpen waits <timeout> seconds for the iMacros Browser, Firefox or IE to start. Default is 30 seconds. Note that on systems with a heavy CPU load (near or equal 100%) it can take around 30s for a web browser to start. Example: You can change the timeout to 90s with ''iret = iim1.iimOpen ("", true, '''90''')'' |
=== Return values === | === Return values === | ||
Line 63: | Line 60: | ||
*-6 (only with -runner flag) [[iimRunner]] not running. Please start iimRunner.exe first. You find this file in the iMacros program directory. | *-6 (only with -runner flag) [[iimRunner]] not running. Please start iimRunner.exe first. You find this file in the iMacros program directory. | ||
*-7 (only with -runner flag) The max. number of allowed iMacros instances is reached. You can change this limit in the iimrunner.xml file. You find this file in the iMacros program directory. This error also occurs if there is no iimrunner.xml file. | *-7 (only with -runner flag) The max. number of allowed iMacros instances is reached. You can change this limit in the iimrunner.xml file. You find this file in the iMacros program directory. This error also occurs if there is no iimrunner.xml file. | ||
− | *-9 Failed to connect to Firefox or Chrome, or could not load imtcp.dll, the assembly necessary to remote control iMacros for Firefox and iMacros for Chrome. [[iimGetLastError]] should have the complete error message. Please, call [[ | + | *-9 Failed to connect to Firefox or Chrome, or could not load imtcp.dll, the assembly necessary to remote control iMacros for Firefox and iMacros for Chrome. [[iimGetLastError]] should have the complete error message. Please, call [[iimClose]] to kill this process if you used [[iimOpen]] to create it. |
For more information see the complete list of [[Scripting Interface Return Codes]]. | For more information see the complete list of [[Scripting Interface Return Codes]]. | ||
− | Note: You should call [[ | + | Note: You should call [[iimClose]] always at the end of a loop or task, even if iimOpen itself returns an error value and the browser is not started. This way you make sure all is "cleaned up". That is especially useful for [[Web_Testing#Q:_How_can_I_set_up_a_24_hours_a_day.2C_7_days_a_week_.28non-stop.29_operation_with_iMacros.3F|running iMacros non-stop for weeks]]. |
+ | |||
+ | === Options === | ||
+ | |||
+ | Possible iimOpen options are: | ||
+ | |||
+ | ;[[Image:Ie-icon.png|IE]] ''-ie'' | ||
+ | :Starts IE and the iMacros Sidebar to control IE. | ||
+ | ;[[Image:Ff-icon.png|Firefox]] ''-fx'' | ||
+ | :Starts Mozilla Firefox instead of the iMacros Browser. [[iMacros for Firefox]] needs to be installed along with [[Webextensions#Add_File_Access|File Access for iMacros Extensions]]. | ||
+ | ;[[Image:Cr-icon.png|Chrome]] ''-cr'' | ||
+ | :Starts Google Chrome instead of the iMacros Browser. [[iMacros for Chrome]] needs to be installed along with [[Webextensions#Add_File_Access|File Access for iMacros Extensions]]. | ||
+ | ;''[[-title]]'' | ||
+ | :Sets the window title of iMacros Browser and iMacros.Sidebar before the browser starts. | ||
+ | ;''[[-tray]]'' | ||
+ | :Starts the iMacros Browser or iMacros Sidebar in tray mode. <br />Note that some browser elements (e. g. Flash) might behave strange when the iMacros Browser is hidden. In this case we recommend to use iMacros Sidebar, which runs in tray mode, while IE is still open and visible. | ||
+ | ;''[[-silent]]'' | ||
+ | :Starts the iMacros Browser or the iMacros Sidebar in silent mode, i.e. tray mode without a tray icon. | ||
+ | ;''[[-kioskmode]]'' | ||
+ | :Starts the iMacros Browser with menu, sidebar, and toolbar hidden. In combination with '''-ie''', IE opens in full screen, while the iMacros Sidebar is hidden. | ||
+ | ;''-runner'' | ||
+ | :Starts iMacros via the [[iimRunner]] tool. See also the -fxProfile and -crUserData options for using [[iimRunner]] with iMacros for Firefox or Chrome. | ||
+ | ;''[[-profiler]]'' | ||
+ | :Starts iMacros with the Profile Macro Performance option enabled. See [[Performance Profiler]] | ||
+ | ;''[[-iePrivate]]'' | ||
+ | :(IE only, so "-ie" or "-ie_ext" must be given, too). This starts IE in "InPrivate" mode, i.e. each instance is separated from another. | ||
+ | ;''[[-key]]'' | ||
+ | :(only works with iMacros 10.02 and older, for iMacros 10.1 and newer see [[Distributing_iMacros#Configuring_the_Player_License|Configuring the Player License]]) Starts iMacros with the specified license key, for example as Player. This ignores any license key that the user might have entered. <br/>Currently, this switch is supported in the iMacros Browser, iMacros Sidebar, and IE. For Firefox, a special registry tweak is available instead (contact tech support for details). | ||
+ | ;''-fxPath'' FirefoxPath | ||
+ | :(FX only!) Specifies the path to firefox.exe if it is not installed in the default Program Files folder, for example: <br> -fxPath "C:\Users\iMacros\AppData\Local\Mozilla Firefox\firefox.exe" <br>Note: quote and backslash characters may need to be escaped accordingly depending on the scripting/programming language you are using. | ||
+ | ;''-fxProfile'' MyProfile | ||
+ | :(FX only!) Specifically for Firefox there is also the fxProfile switch. This switch is necessary when running several instances simultaneously, or with [[iimRunner]]. The -fx switch must also be specified when using this switch. <br />Note: the profile name is case sensitive and must match exactly how it is defined in Firefox. | ||
+ | <!--This command is used for running automated tests with various Firefox versions. For IE there is no version switch as there can only be one IE version installed on a system. --> | ||
+ | ;''-crUserDataDir'' MyUserDataDir | ||
+ | :(Cr Only!) Uses Chrome --user-data-dir option. This switch is necessary when running several instances simultaneously, or with [[iimRunner]]. Use the full path to an already existent Google Chrome user-data-dir, if the path contains spaces, use double quotes. <br />'''Important''': see [[Chrome_Nags#How_to_create_different_user_profiles|How to create different user profiles]] and [[Chrome_Nags#How_to_enable_iMacros_for_Chrome_for_different_user_profiles|How to enable iMacros for Chrome for different user profiles]] | ||
=== Examples === | === Examples === | ||
Line 75: | Line 106: | ||
Dim imacros, iret | Dim imacros, iret | ||
Set imacros = CreateObject("imacros") | Set imacros = CreateObject("imacros") | ||
− | iret = imacros. | + | iret = imacros.iimOpen("-silent") |
Initialize the Scripting Interface connection to an ''existing'' Internet Explorer instance: | Initialize the Scripting Interface connection to an ''existing'' Internet Explorer instance: | ||
Line 81: | Line 112: | ||
Dim imacros, iret | Dim imacros, iret | ||
Set imacros = CreateObject("imacros") | Set imacros = CreateObject("imacros") | ||
− | iret = imacros. | + | iret = imacros.iimOpen("-ie", FALSE) |
Start Firefox via [[iimRunner]] : | Start Firefox via [[iimRunner]] : | ||
Line 87: | Line 118: | ||
Dim imacros, iret | Dim imacros, iret | ||
Set imacros = CreateObject("imacros") | Set imacros = CreateObject("imacros") | ||
− | iret = imacros. | + | iret = imacros.iimOpen("-fx -fxProfile default -runner") |
Start Chrome via [[iimRunner]]: | Start Chrome via [[iimRunner]]: | ||
Line 93: | Line 124: | ||
Dim imacros, iret | Dim imacros, iret | ||
Set imacros = CreateObject("imacros") | Set imacros = CreateObject("imacros") | ||
− | iret = imacros. | + | iret = imacros.iimOpen("-cr -runner -crUserDataDir c:\1test\c2") |
Important: | Important: | ||
Line 99: | Line 130: | ||
# If the profile path contains blanks, so you should quote it, but because the whole command line is already a quoted string, you have to escape the quotes by using two quotes (in vbs). The whole thing should look like that: | # If the profile path contains blanks, so you should quote it, but because the whole command line is already a quoted string, you have to escape the quotes by using two quotes (in vbs). The whole thing should look like that: | ||
− | iret = iim1. | + | iret = iim1.iimOpen(" -cr -runner -crUserDataDir ""c:\chrome profile""",true) |
− | If your | + | If your iimOpen() is in C#, then use : |
− | iret = iim1. | + | iret = iim1.iimOpen("-cr -runner -crUserDataDir \"c:\\chrome profile\", true); |
=== Separate Browser Instances === | === Separate Browser Instances === | ||
Line 111: | Line 142: | ||
Example: Assume you are Google and need to test Gmail. Then you may need twenty IE or Firefox instances running on the same machine, but each one logged into a different Gmail account. What iMacros does in instance A with the Gmail account A should not influence the next instance that is logged into Gmail account B. | Example: Assume you are Google and need to test Gmail. Then you may need twenty IE or Firefox instances running on the same machine, but each one logged into a different Gmail account. What iMacros does in instance A with the Gmail account A should not influence the next instance that is logged into Gmail account B. | ||
− | + | iMacros achieves this with the following iimOpen switches: | |
− | iMacros achieves this with the following | ||
− | |||
====iMacros for Internet Explorer==== | ====iMacros for Internet Explorer==== | ||
− | Use the "-iePrivate" switch. Then cookies are ''not'' shared between each instance. The IE InPrivate mode is identical to a normal IE instance except that cookies are not stored on the hard drive and thus not shared. | + | Use the "-iePrivate" switch in addition to the "-ie" switch. Then cookies are ''not'' shared between each instance. The IE InPrivate mode is identical to a normal IE instance except that cookies are not stored on the hard drive and thus not shared. |
− | |||
====iMacros for Firefox==== | ====iMacros for Firefox==== | ||
− | Please use the "-fxProfile" profile switch. Firefox does not share cookies between different profiles. If you need to have 20 separate Firefox instances, you need to [[Clone_Firefox_Profiles|create 20 Firefox profiles]]. | + | Please use the "-fxProfile" profile switch in addition to the "-fx" switch. Firefox does not share cookies between different profiles. If you need to have 20 separate Firefox instances, you need to [[Clone_Firefox_Profiles|create 20 Firefox profiles]]. |
− | |||
====iMacros for Chrome==== | ====iMacros for Chrome==== | ||
− | Please use the "-crUserDataDir" [[Chrome_Nags#How_to_create_different_user_profiles|chrome profile switch]] and read [[Chrome_Nags#How_to_enable_iMacros_for_Chrome_for_different_user_profiles|How to enable iMacros for Chrome for different user profiles]]. Chrome does not share cookies between different profiles. If you need to have 20 separate Chrome instances, you need to [[Clone_Chrome_Profiles|create 20 Chrome profiles]]. | + | Please use the "-cr" switch plus "-crUserDataDir" [[Chrome_Nags#How_to_create_different_user_profiles|chrome profile switch]] and read [[Chrome_Nags#How_to_enable_iMacros_for_Chrome_for_different_user_profiles|How to enable iMacros for Chrome for different user profiles]]. Chrome does not share cookies between different profiles. If you need to have 20 separate Chrome instances, you need to [[Clone_Chrome_Profiles|create 20 Chrome profiles]]. |
− | ''Note:'' The crUserDataDir support has | + | ''Note:'' The crUserDataDir support has been added in Version 7.36. |
====iMacros Browser==== | ====iMacros Browser==== | ||
− | For the iMacros Browser instance separation is not | + | For the iMacros Browser instance separation is not supported. But you can use iMacros for IE instead. |
− | Related forum post: [ | + | Related forum post: [https://forum.imacros.net/viewtopic.php?uid=14026&f=8&t=12787&start=0#p38017 Best Practices for running Multiple Browser Macros] |
=== See Also === | === See Also === | ||
− | [[x64|64-bit Scripting Interface]], [[iimPlay]], [[iimDisplay]], [[ | + | [[x64|64-bit Scripting Interface]], [[iimPlay]], [[iimDisplay]], [[iimClose]], [[iimGetErrorText]], [[iimGetExtract]], [[iimTakeBrowserScreenshot]] |
Revision as of 09:38, 4 February 2020
As of iMacros V7.40 and later you can also use the new, simplified iimOpen command. In the long run it will replace iimInit, so we recommend to use it for all new scripts and programs. Both commands are 100% compatible! Thus you can use the iimInit documentation and examples.
Initializes the Scripting Interface. It opens a new instance of the iMacros Browser, IE or Firefox, or connects to an existing instance (depending on the specified parameters). If the command fails for any reason it returns an error code.
Note: You must call iimOpen before calling any other scripting interface functions like iimSet or iimPlay.
Syntax
int ret_code = iimOpen( [String commandLine] [, boolean openNewBrowser] [, int timeout])
In some languages you might be able to omit some or all the parameters, but if you would like to input timeout, you will have to include all of them.
Example:
In C# you write
iimOpen("-ie", true, 300);
In Python, True and False must be specified with initial caps:
iimOpen ("-ie", True, 300);
or, you can also specify an integer value (1=True, 0=False)
iimOpen ("", 0)
In Delphi
iimOpen ('-ie', true, 300);
In VBScript can you can simply use
iimOpen("-ie")
or
iimOpen("-ie", True, 300)
You find more code examples for other languages in our Sample Code section.
Parameters
- String commandLine
- Specifies iimOpen options. All options start with a dash (-). Possible options are detailed below.
- boolean openNewBrowser
- Specifies whether to create a new iMacros Browser, Firefox or Internet Explorer process.
- If set to false, iMacros Scripting Interface looks around for uncontrolled instances (that is, not connected to a scripting interface) and attaches to any one found. If none is found, it will create a new process and connect to it.
- Default is true.
- Long timeout
- iimOpen waits <timeout> seconds for the iMacros Browser, Firefox or IE to start. Default is 30 seconds. Note that on systems with a heavy CPU load (near or equal 100%) it can take around 30s for a web browser to start. Example: You can change the timeout to 90s with iret = iim1.iimOpen ("", true, 90)
Return values
- 1 Completed ok
- -1 Could not start the specified web browser
- -3 Timeout (In the trial version this error can also occur if you do not press the iMacros trial version reminder screen "Continue" button in time. This issue can never occur in the full version.)
- -6 (only with -runner flag) iimRunner not running. Please start iimRunner.exe first. You find this file in the iMacros program directory.
- -7 (only with -runner flag) The max. number of allowed iMacros instances is reached. You can change this limit in the iimrunner.xml file. You find this file in the iMacros program directory. This error also occurs if there is no iimrunner.xml file.
- -9 Failed to connect to Firefox or Chrome, or could not load imtcp.dll, the assembly necessary to remote control iMacros for Firefox and iMacros for Chrome. iimGetLastError should have the complete error message. Please, call iimClose to kill this process if you used iimOpen to create it.
For more information see the complete list of Scripting Interface Return Codes.
Note: You should call iimClose always at the end of a loop or task, even if iimOpen itself returns an error value and the browser is not started. This way you make sure all is "cleaned up". That is especially useful for running iMacros non-stop for weeks.
Options
Possible iimOpen options are:
- -ie
- Starts IE and the iMacros Sidebar to control IE.
- -fx
- Starts Mozilla Firefox instead of the iMacros Browser. iMacros for Firefox needs to be installed along with File Access for iMacros Extensions.
- -cr
- Starts Google Chrome instead of the iMacros Browser. iMacros for Chrome needs to be installed along with File Access for iMacros Extensions.
- -title
- Sets the window title of iMacros Browser and iMacros.Sidebar before the browser starts.
- -tray
- Starts the iMacros Browser or iMacros Sidebar in tray mode.
Note that some browser elements (e. g. Flash) might behave strange when the iMacros Browser is hidden. In this case we recommend to use iMacros Sidebar, which runs in tray mode, while IE is still open and visible. - -silent
- Starts the iMacros Browser or the iMacros Sidebar in silent mode, i.e. tray mode without a tray icon.
- -kioskmode
- Starts the iMacros Browser with menu, sidebar, and toolbar hidden. In combination with -ie, IE opens in full screen, while the iMacros Sidebar is hidden.
- -runner
- Starts iMacros via the iimRunner tool. See also the -fxProfile and -crUserData options for using iimRunner with iMacros for Firefox or Chrome.
- -profiler
- Starts iMacros with the Profile Macro Performance option enabled. See Performance Profiler
- -iePrivate
- (IE only, so "-ie" or "-ie_ext" must be given, too). This starts IE in "InPrivate" mode, i.e. each instance is separated from another.
- -key
- (only works with iMacros 10.02 and older, for iMacros 10.1 and newer see Configuring the Player License) Starts iMacros with the specified license key, for example as Player. This ignores any license key that the user might have entered.
Currently, this switch is supported in the iMacros Browser, iMacros Sidebar, and IE. For Firefox, a special registry tweak is available instead (contact tech support for details). - -fxPath FirefoxPath
- (FX only!) Specifies the path to firefox.exe if it is not installed in the default Program Files folder, for example:
-fxPath "C:\Users\iMacros\AppData\Local\Mozilla Firefox\firefox.exe"
Note: quote and backslash characters may need to be escaped accordingly depending on the scripting/programming language you are using. - -fxProfile MyProfile
- (FX only!) Specifically for Firefox there is also the fxProfile switch. This switch is necessary when running several instances simultaneously, or with iimRunner. The -fx switch must also be specified when using this switch.
Note: the profile name is case sensitive and must match exactly how it is defined in Firefox. - -crUserDataDir MyUserDataDir
- (Cr Only!) Uses Chrome --user-data-dir option. This switch is necessary when running several instances simultaneously, or with iimRunner. Use the full path to an already existent Google Chrome user-data-dir, if the path contains spaces, use double quotes.
Important: see How to create different user profiles and How to enable iMacros for Chrome for different user profiles
Examples
Initialize the Scripting Interface in silent mode (iMacros not visible in taskbar or tray - Visual Basic Script example):
Dim imacros, iret Set imacros = CreateObject("imacros") iret = imacros.iimOpen("-silent")
Initialize the Scripting Interface connection to an existing Internet Explorer instance:
Dim imacros, iret Set imacros = CreateObject("imacros") iret = imacros.iimOpen("-ie", FALSE)
Start Firefox via iimRunner :
Dim imacros, iret Set imacros = CreateObject("imacros") iret = imacros.iimOpen("-fx -fxProfile default -runner")
Start Chrome via iimRunner:
Dim imacros, iret Set imacros = CreateObject("imacros") iret = imacros.iimOpen("-cr -runner -crUserDataDir c:\1test\c2")
Important:
- See How to enable iMacros for Chrome for different user profiles
- If the profile path contains blanks, so you should quote it, but because the whole command line is already a quoted string, you have to escape the quotes by using two quotes (in vbs). The whole thing should look like that:
iret = iim1.iimOpen(" -cr -runner -crUserDataDir ""c:\chrome profile""",true)
If your iimOpen() is in C#, then use :
iret = iim1.iimOpen("-cr -runner -crUserDataDir \"c:\\chrome profile\", true);
Separate Browser Instances
For some web testing tasks it is important that different browser instances on the same machine do not share cookies.
Example: Assume you are Google and need to test Gmail. Then you may need twenty IE or Firefox instances running on the same machine, but each one logged into a different Gmail account. What iMacros does in instance A with the Gmail account A should not influence the next instance that is logged into Gmail account B.
iMacros achieves this with the following iimOpen switches:
iMacros for Internet Explorer
Use the "-iePrivate" switch in addition to the "-ie" switch. Then cookies are not shared between each instance. The IE InPrivate mode is identical to a normal IE instance except that cookies are not stored on the hard drive and thus not shared.
iMacros for Firefox
Please use the "-fxProfile" profile switch in addition to the "-fx" switch. Firefox does not share cookies between different profiles. If you need to have 20 separate Firefox instances, you need to create 20 Firefox profiles.
iMacros for Chrome
Please use the "-cr" switch plus "-crUserDataDir" chrome profile switch and read How to enable iMacros for Chrome for different user profiles. Chrome does not share cookies between different profiles. If you need to have 20 separate Chrome instances, you need to create 20 Chrome profiles.
Note: The crUserDataDir support has been added in Version 7.36.
iMacros Browser
For the iMacros Browser instance separation is not supported. But you can use iMacros for IE instead.
Related forum post: Best Practices for running Multiple Browser Macros
See Also
64-bit Scripting Interface, iimPlay, iimDisplay, iimClose, iimGetErrorText, iimGetExtract, iimTakeBrowserScreenshot