Running the Agent in Command Line Mode (DAI Run Agent)

The DAI Run Agent runs at a command line without a graphical user interface (GUI). Thus, you can launch a Run Agent from a batch or shell script, or from within a container. You can also customize how a Run Agent operates by passing arguments with the Run Agent command at the command line. Information about how to use the Run Agent command and available options are provided below.

To use the Run Agent command, follow these steps:

1. From the command prompt, navigate to the agent directory. For example:

   • For Windows: C:\Program Files (x86)\eggplantDAIRunAgent\
   • For Mac: /Applications
   • For Linux: The path to your eggplantDAIRunAgent executable (where you extracted it)

2. Run the agent executable, and add the appropriate arguments:

   • For Windows: eggplantDAIRunAgent.exe [arguments]
   • For Mac: ./eggplantDAIRunAgent [arguments]
   • For Linux: ./eggplantDAIRunAgent [arguments]

   See Troubleshooting Run Agent Launch Issues for information about how to resolve a common launch issue on macOS.

Using DAI Run Agent Command Line Arguments

You can specify how your DAI Run Agent operates by passing arguments with the Run Agent command at the command line. Each argument is preceded with two, concatenated dashes, like this: --argument_name. For a full list of DAI Run Agent arguments and how to use them, see Run Agent Command Help or Table of Run Agent Command Line Arguments below. Examples of Run Agent commands are also provided below.

ノート

When the DAI Run Agent starts, it also starts an Eggplant Functional (EPF) instance in command-line mode, which is without its GUI. This is also known as the Fusion Engine. The Fusion Engine actually runs the DAI snippets. You can specify options you want this Fusion Engine to run with along with your Run Agent command. See Passing Eggplant Functional Command-Line Arguments with the Run Agent Command below for more information.

Simple Example of Running the DAI Run Agent

You can launch a fully-configured DAI Run Agent with the simple command shown below when you specify the path to an existing DAI environment .ini file that is downloaded to your system. For more information about DAI .ini files, see How to create a DAI Environment.

Windows:

In a CMD shell or PowerShell on Windows systems:

“C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe” --ini-file "C:\Users\myuser\my_env.ini"

Mac/Linux:

In a bash shell terminal on a Mac or Linux-based systems:

./eggplantDAIRunAgent --ini-file "my envs/my_env.ini"

Where:

• "C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" is the DAI Run Agent command on Windows and ./eggplantDAIRunAgent is the DAI Run Agent command on Mac and Linux.
• --ini-file C:\Users\myuser\my_env.ini on Windows and --ini-file "my envs/my_env.ini on Mac or Linux are the DAI Run Agent arguments for the DAI .ini file and value, which is the .ini file location. The .ini file location is arbitrary. Specify the location where the file is saved on your system.

Important

On Mac, Linux and Windows, if the path to your DAI .ini file contains spaces, you must enclose it in quotes as shown in the Mac/Linux example above.

Also, if your DAI .ini file contains more than one environment section you must provide the --host-url and --env-id arguments and values along with the --ini-file argument in your Run Agent command. You cannot use the syntax as shown in the simple example above.

Other Examples for the DAI Run Agent

Following are examples of how to run the DAI Run Agent on different operating systems with more verbose, but optional, arguments. See Run Agent Command Help or the Table of Run Agent Command Line Arguments below for a list of available arguments.

Windows:

In a CMD shell or PowerShell on Windows systems:

“C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe” --ini-file "C:\Users\myuser\my_env.ini" --log-level INFO --drive-port 5401

“C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe” --ini-file "C:\Users\myuser\my_env.ini" --host-url https://server.company.com --env-id 1

Mac/Linux:

In a bash shell terminal on a Mac or Linux-based systems:

./eggplantDAIRunAgent --ini-file envs/my_env.ini --log-level INFO --drive-port 5401

./eggplantDAIRunAgent --ini-file "my envs/my_env.ini" --host-url https://server.company.com --env-id 1

Run Agent Command Help

For a full list of DAI Run Agent arguments, you can run the DAI Run Agent command with the
--help argument as shown in the following examples. You can also see the arguments in the Table of Run Agent Command Line Arguments.

Windows:

In a CMD shell or PowerShell on Windows systems:

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" --help

Mac/Linux:

In a bash shell terminal on a Mac or Linux-based systems:

./eggplantDAIRunAgent --help

Troubleshooting Run Agent Launch Issues

If you attempt to launch the Run Agent on macOS, you might see the following Apple message, "eggplantDAIRunAgent Not Opened", as shown below:

Apple incorrectly preventing the launch of the DAI Run Agent

You see this message when Apple incorrectly prevents the launch of the DAI Run Agent. You can safely work around this issue because Eggplant is a trusted source by quarantining the Run Agent so that the Apple malware check skips it. Run the following commands in Terminal (your macOS shell app) command line before you try to launch the Run Agent again:

1. Change to the /Applications folder where the Run Agent is installed on macOS.

2. Enter the following command to allow the Run Agent to launch and run.

   xattr -rd com.apple.quarantine eggplantDAIRunAgent

   You only need to run the quarantine command one time.

Table of Run Agent Command Line Arguments

The following is a list of the supported command-line arguments and their corresponding environment variables. You can also run the Run Agent command with the --help argument at the command line to see this list of options as described in Run Agent Command Help above.

Arguments	Environment Variables	Description
--ini-file FILE	DAI_AGENT_INI_FILE	The location of the environment settings (.ini) file downloaded from the DAI server. The (.ini) file is only created during loading of the downloaded ini file. Default: Windows: C:\Users\{user}\.eggplantDAI.ini (It is marked as hidden.) Mac: ~/.eggplantDAI.ini Linux: ~/.eggplantDAI.ini
--host-url TEXT	DAI_HOST_URL	The Eggplant DAI server that you connect to, e.g. https://server.company.com. This maps to host_url in your environment settings (.ini) file. Use this parameter in conjunction with --env-id to select the appropriate section of the environment settings (.ini) file. If not specified, uses the first section in the .ini file.
--env-id INTEGER	DAI_EXEC_ENV_ID	The ID of the execution environment on the DAI server. Use this parameter in conjunction with --host-url to select the appropriate section of the environment settings (.ini) file. If not specified, uses the first section in the .ini file.
--suite-root DIRECTORY	EGGDRIVE_SUITE_ROOT	The folder used to store downloaded suites. Eggplant Functional (EPF) suites will be uploaded and downloaded as subfolders of the specified root folder. Default: Windows: C:\ProgramData\Eggplant\agent\Suites Mac: ~/Library/Application Support/agent/suites Linux: ~/.local/share/agent/suites
--gui [True|False]		Specifies whether or not to display the Eggplant Functional UI. Default: False
--drive-port INTEGER	EGGDRIVE_PORT	The port Eggplant Functional will use to listen for eggDrive commands. If not specified, it will use a randomly assigned free port.
--log-level [INFO|DEBUG|WARNING|ERROR|TRACE]		The logging level. INFO: logs basic messages indicating the Run Agent is operating as expected. DEBUG: logs detailed messages typically used for diagnosing problems. WARNING: logs unexpected events or potential problems. This level includes the messages logged at level ERROR. ERROR: Logs errors that occurred preventing the Run Agent from functioning properly. TRACE: logs all log-level messages. Default: INFO
--log-folder DIRECTORY	DAI_AGENT_LOG_FOLDER	The folder used to store log files. Default: Windows: C:\ProgramData\Eggplant\agent\logs Mac: ~/Library/Logs/agent Linux: ~/.cache/agent/log
--win-service [INSTALL|START|STOP|REMOVE|RESTART]		For management of DAI Run Agents that you want to run, or already configured to run, as a Windows service, specify the appropriate option to control the Windows service. Use this parameter with the --service-name parameter to specify the Run Agent Windows service's display name. See Running the Agent as a Windows Service for more information. [Default service name: DAI Run Agent (when you install a service but do not specify a service name)] Note: You only see this and the other Windows service options when you run the DAI Run Agent command with the --help argument on Windows. The Windows service options are not available on Mac and Linux.
--service-name TEXT		The display name of the installed DAI Run Agent Windows service. Use this parameter with the --win-service parameter to specify a Run Agent's Windows service display name. [Default: DAI Run Agent] Note: You only see this and the other Windows service options when you run the DAI Run Agent command with the --help argument on Windows. The Windows service options are not available on Mac and Linux.
--service-desc TEXT		The description of a DAI Run Agent Windows service. Use this parameter with the --win-service parameter to set the service description. [Default: Eggplant DAI Agent] Note: You only see this and the other Windows service options when you run the DAI Run Agent command with the --help argument on Windows. The Windows service options are not available on Mac and Linux.
--licenser-host TEXT	(Optional) An extra argument for specifying the RLM License Server host for the EPF instance started with this agent.
--licenser-password TEXT	(Optional) An extra argument for specifying a password when you use the --licenser-host option described above.
--version		Show the version
--help		Show the help message and exit.

Passing Eggplant Functional Command-Line Arguments with the Run Agent Command

When the DAI Run Agent starts, it also starts an Eggplant Functional (EPF) instance in command-line mode (which means without its GUI) as described in What are the DAI Design and DAI Run Agent?. Eggplant Functional running in this mode is also known as the Fusion Engine. You can specify how you want the Fusion Engine to operate by passing Eggplant Functional command-line arguments along with your DAI Run Agent command and arguments.

To pass EPF arguments with the DAI Run Agent command, precede the EPF arguments with two, standalone dashes, like this: --. The EPF arguments are distinguished from the DAI Run Agent arguments in that they are preceded with a single, concatenated dash, like this: -LicenserHost. See an example of this syntax below.

Simple Example of Running the Run Agent with Eggplant Functional Arguments

"C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe"  --ini-file C:\my_ini.ini -- -LicenserHost <ip_address> -LicenserPassword

The example DAI Run Agent command with Eggplant Functional arguments above shows following:

• "C:\Program Files (x86)\eggplantDAIRunAgent\eggplantDAIRunAgent.exe" is the DAI Run Agent command on a Windows system.
• --ini-file C:\my_ini.ini is the DAI Run Agent argument for the DAI .ini file and value, which is the .ini file location.
• -- (two, standalone, concatenated dashes) is the argument that specifies that this Run Agent command includes command-line arguments for the EPF instance it will launch.
• -LicenserHost <ip_address> is the EPF command-line argument that specifies the location of the EPF instance's Reprise License Manager (RLM) Server. The <ip_address> value would be replaced with the IP address (or host name) of the machine. Note that this example only shows 1 EPF argument. You can pass multiple EPF arguments. If you specify more than one EPF argument, you still include two-dashes argument (--) only once before them all.
• -LicenserPassword is the password for the RLM Server specified in the -LicenserHost argument above. Note that this example shows passing this argument without a value.

Commonly Passed Eggplant Functional Arguments

Examples of EPF arguments commonly passed with the Run Agent command are provided in the table below. For information about all EPF command-line arguments, see Running from the Command Line and Runscript Command Line Options in the EPF documentation.

Arguments	Environment Variables	Description
-LicenserHost TEXT		An Eggplant Functional (EPF) argument to specify the Reprise License Manager (RLM) Server host machine.
-LicenserPassword TEXT		An EPF argument for the RLM Server password.

ノート

You can specify the RLM Server for your Eggplant Functional/Fusion Engine instance in your DAI Agent command using either the DAI Run Agent arguments (--licenser-host and --licenser-password with their values) as described in the Table of Run Agent Command Line Arguments or using the EPF arguments (-- followed by -LicenserHost and LicenserPassword with their values) as shown above.

Running Multiple Agents Simultaneously

You can launch multiple instances of the DAI Run Agent across a network. Then you can use them to run multiple concurrent tests in DAI. You launch the additional instances the same way you launch the first instance, as described above in Simple Example of Running the DAI Run Agent and Other Examples for the DAI Run Agent.

情報

When you run multiple instances of the DAI Agent, each instance must have a unique Execution Environment (Environment) name across the entire network. These names should be added to the Controller > Environments page in DAI.

ノート

You can run multiple Run Agents on the same machine. However, we recommend running them on separate machines as a best practice.

Running Multiple Run Agent Instances from a Script

You can launch multiple instances of the DAI Run Agent from a script. You can configure how these agents run using the various Run Agent command options as described in Using DAI Run Agent Command Line Arguments, the same way you do for a single instance.

To get started creating a script, you can see two sample shell scripts in Sample Scripts for Running Multiple Agents. One sample is a Windows batch (.bat) file, and the other is a bash (.sh) script for Mac and Linux.

Following are instructions for creating and running a script file that runs multiple agents, as well as instructions for stopping the agents started by the script.

Create the Batch File or Shell Script

Follow the steps below to create a script to run multiple DAI Run Agents.

1. Create a Windows batch (.bat) file or bash (.sh) shell script file and save it with the name you want. For example, for a Windows batch file, you could name it "MyAGENTStartFile.bat". For Mac or Linux, you could name it "MyAGENTStartFile.sh".

2. Copy the example batch file or shell script shown in Sample Scripts for Multiple Agents below and modify it for your systems, or create the script yourself. Refer to the Using DAI Run Agent Command Line Arguments for more Run Agent configuration options.

3. Save your file.

Run the Script File

After you create and save the script file, you can run it from a command line or terminal depending on your platform by following the steps below:

1. Open a CMD shell or PowerShell on Windows, or a terminal on Mac or Linux.

2. Enter the fully-qualified path to your script file and press Enter. The script file should launch, and report the status of the script file tasks to command shell or terminal. These scripts depend on the shells remaining open for the Agents to run. You can also configure it to run as a background process.

Stop the Agents Launched from the Script

The DAI Run Agents run from the script continue to run until you stop them either by closing shell or terminal or you enter Ctrl+C to terminate the processes within the shell, or one the agents encounter an error.

Sample Scripts for Running Multiple Agents

To get you started creating a script that runs multiple DAI Run Agents at the same time, below are two sample shell scripts: one is a Windows batch (.bat) file, and the other is a bash (.sh) script for Mac and Linux.

Here's what you need to know about the sample scripts:

• The sample scripts launch 4 Run Agent instances. When they run, they first end any running DAI Run Agents and associated Eggplant Functional processes, and then they start the Run Agent instances.

• You can copy the scripts and modify them with the information that is specific to your environment.

• For the bash script, you need to replace the line that changes directory with the directory to which you extracted your eggplantDAIRunAgent executable.

• For Mac, you can comment out the change directory line, and uncomment the one for Mac as explained in the comments in the script.

• The scripts are for use with the DAI Run Agents version 7.0 and later.

ヒント

You can copy the sample scripts below (or any code samples in this documentation) by hovering over the top, right side of their code block to display a copy button.

Windows Batch (.bat) File

@@ECHO OFF

cd "C:\Program Files (x86)\eggplantDAIRunAgent"

REM Kill all hanging processes before restarting Agents
tasklist /fi "imagename eq eggplantDAIRunAgent.exe" |find "eggplantDAIRunAgent" > nul
if errorlevel 1 (
   echo eggplantDAIRunAgent was not running, local time %time% %date% >> c:\temp\EggLog4.txt)
 else (
    taskkill /f /im "eggplantDAIRunAgent.exe">>c:\temp\EggLog4.txt 2>&1
    echo eggplantDAIRunAgent was running, local time %time% %date% >>c:\temp\EggLog4.txt
)

tasklist /fi "imagename eq runscript.exe" |find "Eggplant" > nul
if errorlevel 1 (
    echo Eggplant was not running, local time %time% %date% >> c:\temp\EggLog5.txt)
 else (
    taskkill /f /im "runscript.exe">>c:\temp\EggLog5.txt 2>&1
    echo Eggplant was running, local time %time% %date% >>c:\temp\EggLog5.txt
)

tasklist /fi "imagename eq eggplantDAIRunAgent.exe" |find "eggplantDAIRunAgent" > nul
if errorlevel 1 (
       echo eggplantDAIRunAgent was not running, local time %time% %date% >> c:\temp\EggLog6.txt)
      else (
         taskkill /f /im "eggplantDAIRunAgent.exe">>c:\temp\EggLog6.txt 2>&1
         echo eggplantDAIRunAgent was running, local time %time% %date% >>c:\temp\EggLog6.txt
)

REM Start Agents - need to use correct env-id's are NOT needed if the ini file only contains one env which is mostly the case for each instance from .ini file for each Agent.

ECHO Starting Agent1 . . .
START /B eggplantDAIRunAgent.exe --ini-file "C:\DAI_Agent_INI\Agent1.ini"

TIMEOUT 10

ECHO Starting Agent2 . . .
START /B eggplantDAIRunAgent.exe --ini-file "C:\DAI_Agent_INI\Agent2.ini"

TIMEOUT 10

ECHO Starting Agent3 . . .
START /B eggplantDAIRunAgent.exe --ini-file "C:\DAI_Agent_INI\Agent3.ini"
TIMEOUT 10

ECHO Starting Agent4 . . .
START /B eggplantDAIRunAgent.exe --ini-file "C:\DAI_Agent_INI\Agent4.ini"

TIMEOUT 10

ECHO All agents should be running . . .
ECHO This window should remain open, or the Agents shut down!

cmd /k

Mac or Linux Shell (.sh) script

You can use the following script for Mac and Linux. For linux, you need to edit the script to specify the path to your eggplantDAIRunAgent executable. For Mac, you need to comment out that line and uncomment the line for Mac below it.

#!/bin/bash

LOG_DIR="temp"

# Kill any running agent processes
# For linux, use the following line
for PROC in "eggplantDAIRunAgent" "runscript"; do
# For Mac, comment out the line above, and uncomment out the one below
# for PROC in "eggplantDAIRunAgent" "eggplant"; do
    if ! pgrep -f "$PROC" > /dev/null; then
        echo "$PROC was not running, local time $(date)" >> "$LOG_DIR/EggLog_${PROC}.txt"
      else
         pkill -f "$PROC"
         echo "$PROC was running, killed it, local time $(date)" >> "$LOG_DIR/EggLog_${PROC}.txt"
      fi
done

# Start agents

# For Linux: replace the following line with the path to your eggplantDAIRunAgent
cd "<The_path_to_where_you_extracted_your_eggplantDAIRunAgent>"
# For Mac: comment out the line above and uncomment the line below
# cd /Applications/eggplantDAIRunAgent

for i in {1..4}; do
    echo "Starting Agent$i..."
   # Subsitute the following line for Mac
   # /Applications/eggplantDAIRunAgent
   ./eggplantDAIRunAgent --ini-file "DAI_Agent_INI/Agent${i}.ini" &
   sleep 10
done

echo "All agents should be running..."
echo "This window should remain open, or the Agents shut down!"
exec bash

Eggplant Functional Stop and Restart Settings for Test Configurations Run with a Run Agent

When you run a test configuration with a DAI Run Agent, you can configure the length of time to run Eggplant Functional before restarting or the grace periods for poll-time stopping and restarting with the following environment variables. See Eggplant Functional Stop and Restart Settings for Test Configuration Runs for details.

Environment Variables	Default	Description
RESTART_EPF_AFTER_SECONDS	1800	When running a test configuration, you can configure the interval in seconds that EPF runs before restarting. This variable takes effect after the current step finishes and before moving to the next step if the defined time is exceeded. It only applies to test configurations run with the DAI Run Agent. During live runs, EPF runs continuously without restarting. If you do not want EPF to restart during your test runs, you can disable this option by setting it to 0 (zero).
EPF_QUIT_POLL_TIME_SECONDS	20	The grace period for EPF to quit during the restart process.
EPF_RESTART_POLL_TIME_SECONDS	120	The grace period for EPF to start up after having quit. EPF_RESTART_POLL_TIME_SECONDS does not include EPF_QUIT_POLL_TIME_SECONDS.