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: 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
.
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 theName
parameter if theconnectioninfo
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:
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
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
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.
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
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.
- 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.
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
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
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
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>
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.
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"
In order for Eggplant Functional to search for the image at its original size, a scale factor of 1 must be included.