iimInit()

From iMacros

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.

Contents 1 Syntax 2 Parameters 3 Return values 4 Examples 5 Separate Browser Instances 6 See Also

Syntax

int ret_code = iimInit( String commandLine [, boolean openNewBrowser] [, String user, String password, String domain], Long timeout)

Parameters

• String commandLine

  Specifies command line switches. All switches start with a dash (-). Possible switches are:

  • -ie Starts Internet Explorer instead of the iMacros Browser. Note that the iMacros sidebar needs to be open in IE so that it re-opens automatically when IE is started.
  • -fx Starts Mozilla Firefox instead of the iMacros Browser. (iMacros for Firefox needs to be installed). NOTE: Due to a Firefox bug, please use Firefox 3.6.3 or earlier.
  • -tray Starts the iMacros Browser in tray mode.
  • -silent Starts the iMacros Browser in silent mode, i.e. tray mode without a tray icon.
  • -kioskmode Starts the iMacros Browser with menu, sidebar, and toolbar hidden.
  • -runner Starts iMacros via the iimRunner tool.
  • -iePrivate" (IE only, so "-ie" must be given, too). This starts IE in "InPrivate" mode, i.e. each instance is separated from another.
  • -useragent Change the iMacros user agent string. In Firefox, you can use the !USERAGENT variable instead.
  • -key Start 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 and IE. For Firefox, a special registry tweak is available instead (contact tech support for details).
  • Specifically for Firefox there are also the -fxVersion, -fxLocale and -fxProfile switches. Typically these specialized commands are "only" 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.
• 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 attach to any one found. If none is found, it will create a new process and connect to it.

  Default is true.

• String user (Deprecated, please use the new iimRunner utility instead if you need to start iMacros under a certain user account)

  Username under whose account the iMacros Broser is started.

• String password (Deprecated, please use iimRunner instead)

  Password needed for the account specified in user.

• String domain (Deprecated, please use iimRunner instead)

  Domain in which the username given in user is valid.

• Long timeout

  iimInit waits <timeout> seconds for the iMacros Browser, Firefox or IE to start. Default is 300 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.iimInit ("", 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 simple.xml file. You find this file in the iMacros program directory. This error also occurs if there is no iimrunner.xml file.

For more information see the complete list of Scripting Interface Return Codes.

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.iimInit("-silent") 

Initialize the Scripting Interface connection to an existing Internet Explorer instance:

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit("-ie", FALSE)

Start Firefox via iimRunner :

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit("-fx -runner")

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 iimInit switches:

1. 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.

2. 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 create 20 Firefox profiles.

For the iMacros Browser instance separation is not yet available. But you can use iMacros for IE instead.

See Also

64-bit Scripting Interface, iimPlay, iimDisplay, iimExit, iimGetLastError, iimGetLastExtract, iimTakeBrowserScreenshot