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.