iimOpen

From iMacros
Jump to: navigation, search

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 iMacros Browser IE Plug-in Firefox Chrome

 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 Delphi

iimOpen ('-ie', true, 300);

In VBS 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 -ie
Starts IE and the iMacros Sidebar to control IE.
Firefox -fx
Starts Mozilla Firefox instead of the iMacros Browser. (iMacros for Firefox needs to be installed, see this forum post for important information).
Info: If you are using iMacros for Firefox 7.4 or later with an older iMacros version (below V7.5) please download the Firefox Scripting Interface separately.
Chrome -cr
Starts Google Chrome instead of the iMacros Browser. iMacros for Chrome needs to be installed.
-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.
-profiler
Starts iMacros (IE, iMacros Sidebar, and iMacros Browser only) 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).
-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:

  1. See How to enable iMacros for Chrome for different user profiles
  2. 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 yet available. 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