Skip to main content
Version: 23.3

Runscript Command Line Options

This page explains the different options you can use when you run Eggplant Functional scripts from a command line using the runscript command. This command runs scripts without launching the Eggplant Functional GUI.

To add multiple options, insert a space before each one. For more information about these commands, see Running from the Command Line.

To invoke scripts using the Eggplant command, which launches the Eggplant Functional GUI, see Eggplant Command Line Options.

Important

Important: For Mac installations of Eggplant Functional version 18.0 and later, the path to call the runscript command has changed to /Applications/Eggplant.app/Contents/MacOS/runscript. You might need to update tests created in earlier versions of Eggplant Functional to prevent errors. You also can click the Install runscript in /usr/bin/local button in Eggplant > Preferences > Run Preferences to add the runscript command to your user path. This allowsrunscript to be called from any directory via the command line.

If you're running Eggplant Functional on a Mac and using a version older than 18.0, the runscript command path is /Applications/Eggplant.app/runscript.

note

We use the term arguments to describe the options you pass with the runscript or Eggplant command when you run those commands from the command line. Other terms you might be familiar with include options and flags.

We use the term parameters to refer to the values that you pass as input to scripts. See Passing Parameters for more information about passing parameters to scripts when you run them from a command line.

Connection Information​

RDP & VNC​

Specify the connection information for a Virtual Network Computing (VNC) or Remote Desktop Protocol (RDP) system under test (SUT) using the runscript command with the following flags:

  • -host – The hostname or IP address of a specific SUT to use for your scripts. When you pass a -host argument, you can also specify a color depth, password, port, username, and connection name.
  • -connectionname – The desired name for a new connection being created. Used in conjunction with the -host flag, the -connectionname flag provides the SUT identification name for the connection. This value is returned by the Name parameter if the connectioninfo function is called.
  • -port – The port of the software you are using to connect to the SUT. This is the port of either the VNC server or RDP connections, you provide the username and password for the host Windowsmachine.
  • -username and -password – For VNC server connections to the SUT, you usually need to provide only the password. In rare cases, primarily when using UltraVNC, you might need the username. For RDP connections, you provide the username and password for the host Windows machine.
  • -password64 or -pass_code64 – If you use Base64 encoding for passwords or passcodes that include standard and nonstandard characters, you can use either the -password64 or -pass_code64 option. Use the -password64 option to pass Base64 encoded passwords and the -pass_code64 option to pass Base64 encoded passcodes. For more information about encoding passwords or passcodes to Base64 format, see Base64 (Encode and Decode).
  • -colorDepth – The color depth of the SUT in the Viewer window: 8, 16, 32. (Default value: The native color depth of the SUT.)
  • -type [RDP, VNC] – The type of connection. "RDP" specifies an RDP connection and is available for Windows SUTs only. RDP connections use port 3389 by default. "VNC" specifies a VNC connection. The default connection type is VNC. Omitting the -type parameter results in a VNC connection.
  • -DefaultHeight and -DefaultWidth – These parameters specify to display the SUT screen, and the height and width in pixels at which it displays. These options are for use with RDP connections only, which means only when the -type option is included and set to RDP.

Examples​

Here are some examples demonstrating VNC and RDP connections with the runscript command.

Mac VNC and RDP Connection Examples​
/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Alex/Docs.suite/Scripts/myTests/test2.script -host <ip address> -port 5901 -username <username> -password <password>
Windows VNC and RDP Connection Examples​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\Documents\MySuite.suite\Scripts\test2.script" -host <ip address> -password "<password>" -type rdp -DefaultWidth 1920 -DefaultHeight 1080
Linux VNC and RDP Connection Examples​
runscript ~/Documents/appTests.suite/Scripts/test1.script -host <ip address> -port 5901 -username "<username>" -password <password>

Sauce Labs​

Specify the connection information for a Sauce Labs system under test (SUT) using the runscript command with the following flags:

  • -SauceLabsConnectionName – The name to assign to this connection. (Optional)
  • -SauceLabsUser – The user name for the Sauce Labs account being used. (Required)
  • -SauceLabsApiKey – The Sauce Labs API key for the account. (Required)
  • -SauceLabsDataCenter – The Sauce Labs data center to connect to. (Required)

For Sauce Labs Browser connections:

  • -SauceLabsBrowserName – The name of the browser, such as "Chrome", "Firefox", etc. (Required)
  • -SauceLabsPlatformName – The name of the operating system platform, such as "Windows 10". (Required)
  • -SauceLabsUrl – The URL of the site to connect to in the browser. (Required)
  • -SauceLabsBrowserVersion – Specific browser version requested. (Optional)
  • -SauceLabsScreenResolution – The browser screen size in the form width X height, such as "1400x1050". (Optional)

For Sauce Labs Device connections:

  • -SauceLabsDeviceName – The device identifier, such as "Iphone 12", etc. (Required)
  • -SauceLabsPlatformName – The name of the operating system platform, such as "iOS", "Android", etc. (Required)
  • -SauceLabsApp – The URL of the app to execute on the device. (Optional)

For Sauce Labs Tunnel Proxies options:

note

Sauce labs tunnels can be used to connect to both Sauce Labs browsers and devices.

To use the Sauce Labs Tunnel Proxy functionality, you must first have the Sauce Connect Proxy installed and running on the same machine as Eggplant Functional. Please see Connecting Using Sauce Connect Proxy for more information.

  • -SauceLabsTunnelName – The name of the active Sauce Connect tunnel to use when connecting to Sauce Labs. (Optional)
  • -SauceLabsTunnelOwner – The name of the Sauce Labs user account that was used to establish the active Sauce Connect tunnel. (Optional)

Example​

Linnux with Sauce Labs Connection​
runscript ~/phoneTests.suite/Scripts/galaxy.script -SauceLabsDeviceName "Samsung Galaxy S10" -SauceLabsPlatformName "Android" -SauceLabsUser "<username>" -SauceLabsApiKey "<sauce-labs-api-key>" -SauceLabsDataCenter "us-west-1"

Citrix (Windows-Only)​

For Citrix connections, specify the connection information for a Citrix system under test (SUT) using the runscript command with the following flags:

  • -CitrixStorefront - The Citrix domain to connect to. (Required)
  • -CitrixUsername - The user name for the Citrix account being used. (Required)
  • -CitrixPassword - The password for the Citrix account. (Required)
  • -CitrixApplication - The Application or Desktop to be launched. (Required)
  • -CitrixScreenshotInterval - The amount of time, in milliseconds, to wait between two subsequent captures of the Citrix SUT. (Optional)
  • -CitrixScreenResolution - The resolution of the Citrix SUT. (Optional)

Example​

Citrix Connection on Windows​
runscript.bat "C:\Users\EggplantUser\Documents\CtirixConnections.suite\Scripts\RunscriptCitrix.script" -CitrixStorefront "https://citrix.citrixdomain.com/Citrix" -CitrixUsername "<username>" -CitrixPassword "<password>" -CitrixApplication "Windows Server 2019" -CitrixScreenshotInterval 400 -CitrixScreenResolution 1600X900
note

A connect command from within a running script or connection information in a schedule overrides this connection. This connection remains open, but the new connection becomes the active connection.

Mobile Devices​

tip

If this is your first time connecting to a mobile device, we strongly recommend that you read Connecting to Mobile Devices and the appropriate "Working with ... Mobile Devices" topic for important concepts related to testing mobile devices (i.e. Working with Android Mobile Devices and Working with iOS Mobile Devices).

Specify the connection information for an Android Mobile Device using the runscript command with the following flags:

  • -AndroidDeviceId - The Device ID of the Android device to test. See Note below.
note

If only one device is connected to your system, you can specify an AndroidDeviceId of "connected" and Eggplant Functional will automatically connect to that device. If you have more than one device connected, the AndroidDeviceId parameter is required. Please see Getting Android Mobile Device IDs and Connecting to Android Emulators for details on working with Device IDs.

Specify the connection information for an iOS Mobile Device using the runscript command with the following flags:

  • -iOSDeviceUDID - The unique device ID of the iOS device to test. See Notes below
  • -iOSDeveloperCertificatePath - The fully qualified file name of your iOS Developer Certificate
  • -iOSDeveloperCertificatePassword - The password for your iOS Developer Certificate
  • -iOSProvisioningProfilePath - The fully qualified file name of an appropriate iOS Provisioning Profile
  • -iOSDeveloperDiskPath - The path to the top-level directory that contains the Developer Disks for your mobile device
note

If only one device is connected to your system, you can specify an iOSDeviceUDID of "connected" and Eggplant Functional will automatically connect to that device. If you have more than one device connected, the iOSDeviceUDID parameter is required. Please see Getting iOS Mobile Unique Device IDs (UDID) for details on working with Device IDs.

note
  • Please refer to Before You Start for details about Apple Provisioning Profiles, Developer Certs, and Developer Disks.

Examples​

Mac with a Mobile Device Connection to an Android Emulator​

The first example runs a script using a connection to an Android emulator with Device ID "emulator-5554":

Applications/Eggplant.app/Contents/MacOS/runscript ~/Documents/AndroidConnectCmd.suite/Scripts/Runscript.script -AndroidDeviceId "emulator-5554" -CommandLineOutput yes
Connecting to a Physical Android Mobile Device Using Auto-Discovery​

The next example runs a script using auto discovery to connect to whatever Android mobile device is currently connected to the system running Eggplant Functional:

/Applications/Eggplant.app/Contents/MacOS/runscript ~/Documents/AndroidConnectCmd.suite/Scripts/Runscript.script -AndroidDeviceId "connected"
Connecting to a Physical iOS Mobile Device with an Explicit UDID​

This example shows how to connect to a physical iOS mobile device including all of the required parameters related to developer certs and profiles.

Applications/Eggplant.app/Contents/MacOS/runscript \
    main.script \
    -iOSDeviceUDID "00008030-00134C6554E8802E" \
    -iOSProvisioningProfilePath "/home/sally/Desktop/ios/myteam.mobileprovision" \
    -iOSDeveloperCertificatePath "/home/sally/Desktop/ios/MyCert.p12" \
    -iOSDeveloperCertificatePassword "<my-cert-password>" \
    -iOSDeveloperDiskPath "/home/sally/Desktop/ios/DeviceSupport" \
    -CommandLineOutput YES

WebDriver Connection Information​

Specify the connection information for a WebDriver connection using the runscript command with the following flags:

  • -webBrowser – Opens a WebDriver connection to a specific browser. Required.
  • -webHost – The host for the WebDriver connection. Required unless -host has been specified.
  • -webPort – Defines the port to use when creating a WebDriver connection. If no port is specified, port 4444 is used. Optional.

Examples​

Mac Webdriver Connection Example​

/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Bob/Selenium.suite/Scripts/test1.script -webBrowser "Chrome" -webHost "10.211.55.4" -webPort "4445"

Windows Webdriver Connection Example​

"C:\Program Files\Eggplant\runscript.bat" C:\Users\Bob\Documents\Selenium.suite\Scripts\test1.script" -webBrowser "Chrome" -webHost "10.211.55.4" -webPort "4445"

Linux Webdriver Connection Example​

runscript ~/Documents/Selenium.suite/Scripts/test1.script -webBrowser "Chrome" -webHost "10.211.55.4" -webPort "4445"

Additional Arguments​

You can use the runscript command to send passwords, control where logs are stored, pass parameters, and more.

-CommandLineOutput​

Use​

Controls whether script logs (the data shown in the log area of the Run window) are output.

Valid values​

yes or no. To output script logs, set the -CommandLineOutput argument to yes. To turn off this output, set the -CommandLineOutput argument to no.

Examples​

Mac -CommandLineOutput Argument Example​
/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Alex/appTests.suite/Scripts/test3.script -CommandLineOutput no
Windows -CommandlineOutput Argument Example​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\Documents\appTests.suite\Scripts\test2.script" -CommandLineOutput no
Linux -CommandLineOutput Argument Example​
runscript ~/Documents/appTests.suite/Scripts/test1.script -CommandLineOutput no

You can also set the CommandLineOutput global property within a script. Global properties that are changed in a script always override initial settings.

note

Output sent to standard error (stderr or error) is always displayed. For finer control over the output while running from the command line, you can use this syntax in your script:

write "THIS IS SOME OUTPUT" to error

-DefaultDocumentDirectory​

Use​

Specifies the starting directory for relative file paths to suites, such as the paths of helper suites.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript -DefaultDocumentDirectory ~/Documents/EggplantDocs
Windows​
"C:\Program Files\Eggplant\runscript.bat" -DefaultDocumentDirectory "C:\Users\Elizabeth\Documents\eggPlantTests"
Linux​
runscript ~/Documents/appTests.suite/Scripts/test1.script -DefaultDocumentDirectory ~/Documents
note

This is the same as the Eggplant Functional General Preference for Default Suite Directory.

-GlobalResultsFolder​

Use​

Sets the name of the folder in which your script results are stored. The folder path can be absolute, or relative to the script's suite.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Alex/Docs.suite/Scripts/test2.script -GlobalResultsFolder ~/MyResults
Windows -GlobalResultsFolder Argument Example​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\Documents\MySuite.suite\Scripts\smoketestMain.script" -GlobalResultsFolder "C:\Users\Alex\Documents\ExecutionResults\SmokeTest"
Linux -GlobalResultsFolder Argument Example​
runscript ~/Documents/appTests.suite/Scripts/test1.script ~/Documents/appTests.suite/Scripts/test2.script -GlobalResultsFolder ~/MyResults
note

Setting the GlobalResultsFolder is temporary and only applies to the current Eggplant Functional session. It will not affect already started scripts and their results. Also, you must set the GlobalResultsFolder before you run your script, because once a script has started to execute, its log location is fixed. When you set the GlobalResultsFolder, your results are no longer stored in the suite, so you can't view them in the Suite window.

-LicenseKey, -LicenseUser​

Use​

Adds a license key and user for use of Eggplant Functional.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript -LicenseKey <license_key> -LicenseUser <user_name>
Windows​
"C:\Program Files\Eggplant\runscript.bat" -LicenseKey <license_key> -LicenseUser <user_name>
Linux​
runscript -LicenseKey <license_key> -LicenseUser <user_name>

-LicenserHost​

Use​

You use the -LicenserHost argument to specify the location of the Eggplant Functional license server. You enter the -LicenserHost argument, followed by the IP address or hostname for the machine where your license server is running. Even if you specify the licenser host on the Eggplant License Registry panel, you might need to include this argument to run scripts from the command line.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Alex/Docs.suite/Scripts/test2.script -LicenserHost 10.1.11.105
Windows​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\Documents\MySuite.suite\Scripts\test2.script" -LicenserHost bkwinsPC
Linux​
runscript ~/Documents/appTests.suite/Scripts/test1.script ~/Documents/appTests.suite/Scripts/test2.script -LicenserHost 10.1.11.163
note

This argument is required in most environments for running from the command line for both Reprise License Manager (RLM) and Team License Server (TLS).

-LicenserPassword​

Use​

Use this flag if you've set up RLM to require a password.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Fred/Docs.suite/Scripts/bigtest.script -LicenserPassword <password>
Windows​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Fred\Documents\MySuite.suite\Scripts\bigtest.script" -LicenserPassword <password>
Linux​
runscript ~/Documents/appTests.suite/Scripts/test1.script ~/Documents/appTests.suite/Scripts/bigtest.script -LicenserPassword <password>
note

This argument is only required if you've configured Reprise License Manager (RLM) to require a password.

-param (-p)​

Use​

The -param argument passes a parameter to a script. You can use -param before or after the name of the script. Note that the -param string must precede each parameter in the script. The -p form is an abbreviation for the same argument. You can use them interchangeably.

note

The -param argument (without an "s" on the end) is not the same as the older -params argument.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript ~/Documents/appTests.suite/Scripts/test1.script -param "SUT1" -param "phonebook.txt"
Windows​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\Documents\MyTests.suite\scripts\test1.script" -p "SUT1" -p "phonebook.txt"
Linux​
runscript ~/Documents/appTests.suite/Scripts/test1.script -param "SUT1" -param "phonebook.txt"

-paramValue (-pv)​

Use​

The -paramValue argument (or its abbreviation, -pv) can be used to pass a list, property list, or other complex parameter value to a script. The SenseTalk Value Function is applied to the supplied value before passing it to the script.

You can freely mix the use of -paramValue and -param in your call. Values following -param or -p are passed as literal strings to the script. Values following paramValue or -pv are evaluated as SenseTalk expressions and the evaluated value is passed to the script.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript ~/Documents/appTests.suite/Scripts/test1.script -paramValue "[SUT1,SUT2]" -paramValue "{x:34, y:125}"
Windows​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\Documents\MyTests.suite\scripts\test1.script" -p "SUT1" -pv "[1,2,3,5,9]"
Linux​
runscript ~/MyTests.suite/Scripts/test1.script -paramValue "the international time" -pv '{name:"Joe User", id:"143G-2", password:"top secret"}'

-repeat​

Use​

Repeats the scripts you are running a specified number of times.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Alex/myTests.suite/Scripts/test1.script -repeat 4
Windows​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\Documents\MyTests.suite\Scripts\test1.script" -repeat 4
Linux​
runscript ~/Documents/appTests.suite/Scripts/test1.script -repeat 4

-ReportFailures​

Use​

Reports the number of failed scripts and suites back to the command line after script execution. Valid values: yes/no. Default value: yes. If you want Eggplant Functional to report the number of successful scripts and suites to the command line, set it to no.

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Alex/Docs.suite/Scripts/test1.script -ReportFailures yes
Windows -ReportFailures Argument Example​
"C:\Program Files\Eggplant\runscript.bat" C:\Users\Alex\Documents\MySuite.suite\Scripts\test1.script" -ReportFailures yes
Linux​
runscript ~/Documents/appTests.suite/Scripts/test1.script -ReportFailures yes

-ScaleFactors​

Use​

ets the ScaleFactors global property.

Values: A string with a single value indicating scale, a range of scales, or both. Default value: Empty (effectively 1.0).

Examples​

Mac​
/Applications/Eggplant.app/Contents/MacOS/Eggplant /Users/Elizabeth/Desktop/Tests.suite/Scripts/CLI.script -ScaleFactors "0.5..1.5 by 0.1"
Windows​
"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\Documents\appTests.suite\Scripts\test2.script" -ScaleFactors "0.5 to 1.5 by 0.5"
Linux​
runscript ~/Documents/appTests.suite/Scripts/test1.script -ScaleFactors "0.5 to 1 by 0.1"
note

In order for Eggplant Functional to search for the image at its original size, a scale factor of 1 must be included.

Last updated on