Skip to main content
Version: 23.3

Running from the Command Line

You can run Eggplant Functional scripts and suites from a command line. There are several reasons why you might want to do this:

  • You can have one or more instances of Eggplant Functional running tests from the command line while you continue to develop and run scripts in GUI mode.
  • You can add a command-line call to Eggplant Functional at the end of a product build script to perform a smoke test of the new build.
  • You can use Windows Scheduled Tasks (or Unix crontab or at command on Mac and Linux) to schedule Eggplant Functional scripts to run at specific times.

For tips on when running from the command line is an appropriate approach as opposed to using Eggdrive, see Eggdrive vs. Command Line Execution.

note

The Ask and Answer commands won't prompt for input when running from the command line. If you intend to run Eggplant Functional script from the command line and have Ask or Answer commands in scripts, you should set default values for the information that would otherwise be obtained from the user.

Every instance of Eggplant Functional requires a license. To use Eggplant Functional from the GUI and the command line at the same time, you need at least two licenses.

You can run Eggplant Functional scripts from a command line two ways:

  • The runscript command, which runs scripts without launching the Eggplant Functional GUI.
  • The Eggplant command, which launches the Eggplant Functional GUI, then runs scripts.

When using the runscript or Eggplant commands, the command might be unable to obtain a license (due to all of the licenses being in use). If there is no license available, the command being run immediately exits and shows an error code 127. For a better experience, pass the -MaxWaitForLicense MAX_SECONDS parameter so that the command continues to query the license server or servers for a license up to the MAX_SECONDS duration (in seconds). If the command being used (runscript or Eggplant) obtains a license within the MAX_SECONDS time frame, it opens normally.

The Runscript Command

The runscript command launches Eggplant Functional from a command line and runs scripts without showing the Eggplant Functional GUI. Execute the runscript command as described here:

  1. Type the full path and name of the runscript command, followed by a space.
  2. Type the full path and name of a script to run.
  3. For each additional script, insert a space and then type the full path and name for each one.
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 allows runscript 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 remains /Applications/Eggplant.app/runscript.

Examples

Mac

/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Alex/Documents/appTests.suite/Scripts/test1.script /Users/Alex/Documents/appTests.suite/scripts/test2.script

Windows

"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\My Documents\MySuite.suite\Scripts\test1.script" "C:\Users\Alex\My Documents\MySuite.suite\Scripts\test2.script"

Linux

runscript ~/Documents/appTests.suite/Scripts/test1.script ~/Documents/appTests.suite/Scripts/test2.script

Eggplant Functional saves the results of each script run in the Results folder for that script's suite. Then, after all scripts have finished running, Eggplant Functional reports the number of successful scripts as the return value.

note

The Linux installation of Eggplant Functional sets environment variables so you can call the runscript command from any directory by specifying only its name.

note

To have Eggplant Functional report script successes instead of failures, set the -ReportFailures flag to no. For more information about command line options, see Command Line Options.

note

The Ask and Answer commands don't prompt for input when run from the command line. If you intend to use this approach and have Ask or Answer commands in scripts, you should set default values for the information that would otherwise be obtained from the user. For information about using these commands, see User Interaction.

Using Runscript on Linux Machines Without GUIs

If you want to run EPF scripts on linux machines that do not have GUIs, such as AWS instances, Docker containers, SSH connections, or other situations where a GUI is not present, you can include the -GSBackend option with the runscript command. For example:

For Ubuntu 22

runscript ~/Documents/Scripts/test.script -GSBackend libgnustep-headless

If you are using Ubuntu 16.04, CentOS 7.x, or Red Hat Enterprise Linux (RHEL) 7, you should use the -GSBackend libgnustep-back-headless syntax.

The Eggplant Command

The Eggplant command opens the Eggplant Functional GUI from the command line. You can use it to open the application and run scripts, or you can use it to simply open the application.

Examples

Mac

/Applications/Eggplant.app/Contents/MacOS/Eggplant

Windows

"C:\Program Files\Eggplant\Eggplant.bat"

Linux

Eggplant
note

The Linux installation of Eggplant Functional sets environment variables so that you can launch the Eggplant GUI application from any directory by specifying only its name.

note

When you launch the Eggplant Functional GUI from the command line, the standard output is not displayed in the terminal. Instead, it is saved as a log in the Application Support\Eggplant directory of your user account.

Passing Parameters to a Script

Eggplant Functional supports the passing of parameters to scripts even when you run them from a command line. You can pass a single parameter, multiple parameters, parameter and value pairs for multiple parameters, and even lists. Parameter values are passed as text strings to the script immediately preceding them. Keep this in mind if you are running multiple scripts in a command.

To pass parameters to a script, you need to precede each parameter value with the -param argument. See -param for information about when to use this argument and examples of how to use it.

note

Information in this section uses the following terms when talking about passing parameters.

  • The parameters term refers to what you pass to your scripts.
  • The parameter values term refers to the values you are passing for the parameters to your scripts.
  • The arguments term refers to the options you pass to the runscript or EggPlant commands. For example, -param is an argument. See Command Line Options for a list of these arguments.

Passing Parameters to Scripts in a Schedule

If you are running a schedule from a command line, the parameters you specify after the suite are passed to each script that is run in the schedule.

How to Pass the Parameters

Following are the syntax and rules for using -param to pass parameter values to scripts at the command line:

  1. Provide the runscript or Eggplant command first followed by a space, as described in Runscript Command or Eggplant Command above.

    note

    Whether or not you need to provide the full path to the runscript or Eggplant command, script, or suite depends on which directory you are in when you run the command. On Linux, the Eggplant Functional installer sets variables so that you don't need to provide the path to the runscript or EggPlant commands.

  2. Specify the script you want to run, followed by a space.

  3. Provide the -param argument immediately following the script, followed by a space.

  4. Provide the parameter value you want to pass to the script, enclosed in double quotes. If you need to pass multiple parameters, you must specify the -param argument with each one.

note

If you are running multiple scripts, you must include -param with the appropriate parameter values with each script.

note

You can also specify parameters before script names as default parameters. If you include any parameters after a script name, those parameters are passed to the script.

Running Scripts with a Schedule

Eggplant Functional schedules let you collect scripts together that you want to run in a sequence. For more information about schedules, see Running Scripts using Eggplant Functional Schedules.

If you are running a schedule, use the runscript or Eggplant command with the full path to the suite containing the schedule, a slash appropriate for the operating system, and then the schedule name.

Examples

Mac

/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Sam/appTests.suite/Schedule1
/Applications/Eggplant.app/Contents/MacOS/Eggplant/Eggplant /Users/Sam/appTests.suite/Schedule1

Windows

"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\My Documents\MySuite.suite\Schedule1"
"C:\Program Files\Eggplant\Eggplant.bat" "C:\Users\Alex\My Documents\MySuite.suite\Schedule1"

Linux

runscript ~/Documents/appTests.suite/Schedule1
Eggplant ~/Documents/appTests.suite/Schedule1
note

If you only specify the suite name, this command runs the first schedule in the suite, determined alphabetically. If there are no schedules to run, Eggplant Functional returns a "No Scripts to Run" error. For more information about running scripts with schedules, see Running Scripts using Eggplant Functional Schedules.

note

Eggplant Functional saves the results of each script run in the Results folder for that script's suite. Then, after all scripts and suites have finished running, Eggplant Functional reports the number of successful scripts and suites as the return value. A suite is successful if every script in it is successful.

note

This can be used with the -RunOnLaunch command line option.

note

You will not see the name of the schedule in a directory listing of the suite.

Running a Table Test

Keyword-driven testing enables you to use keywords to represent functionality you want to test in an external table, along with arguments (data) for each keyword. You can run keyword-driven tests from the command line using the runscript command followed by the path to the table to be executed. For more information about keyword-driven testing, see The Tables Feature and Keyword-Driven Testing.

Examples

Mac

/Applications/Eggplant.app/Contents/MacOS/runscript /Users/Greg/Documents/AppTests.suite/TableScripts/TableName.table

Windows

"C:\Program Files\Eggplant\runscript.bat" "C:\Users\Alex\nobr>My Documents\AppTests.suite\TableScripts\TableName.table"

Linux

runscript ~/Documents/appTests.suite/TableScripts/TableName.table

Running Gherkin Features

To run Gherkin tests from the command line, you use the runscript command. This process is essentially the same as it is for running SenseTalk scripts.

Examples

Mac:

/Applications/Eggplant.app/Contents/MacOS/runscript /Users/<username>/Documents/ePFSuites/gherkin.suite/Features/test1.feature -CommandLineOutput Yes

Windows:

"C:\Program Files (x86)\Eggplant\runscript.bat" "C:\Users\<username>\Documents\FeatureImageEdit.suite\Features\test1.feature"

In both examples above, following the full path to the runscript command, you enter the full path and name for the .feature file you want to run. You also can include tags as parameters to the runscript command in a -param statement.