Below is information about how to use Eggdrive with Eggplant Functional. Use Eggdrive to allow external processes, such as scripts from other testing tools, to use Eggplant Functional’s automation capabilities. For a description of the Eggdrive product, see About Eggdrive.
There are four basic steps to using Eggdrive:
- Launch Eggplant Functional in drive mode.
- Start an Eggdrive session.
- Send Eggplant Functional commands through XML-RPC calls.
- End your Eggdrive session.
Each step is explained below. You can see examples of scripts using Eggdrive in the following programming languages:
Launch Eggplant Functional in Drive Mode
To use the Eggdrive interface, launch Eggplant Functional from the command line with an argument specifying the port number to be used (-driveport portNum). Eggplant Functional listens for communications on this port, waiting for a client to connect. This process is known as running Eggplant Functional in drive mode.
You can launch the Eggplant Functional GUI when running in drive mode by passing the -rungui YES argument.
Logging with Eggdrive
By default, Eggplant Functional does not provide console output about the commands performed by the application when it is running in drive mode. Only messages such as errors and warnings are typically returned. You can change this behavior by including the drivelogging argument in your launch command. The drivelogging options are as follows:
- -drivelogging 0 turns off all logging.
- -drivelogging 1 logs all commands that Eggplant Functional receives and acts upon from your client.
- -drivelogging 2 logs the full content of each XML-RPC message that Eggplant Functional receives, as well as the shorter logs shown by -drivelogging 1.
If you want to save the session log to a file, you can use the DriveOutputFile command line option with your launch command, and provide the file path as its argument: -DriveOutputFile <filePath>
For example, to use this option on Mac, you would use a command such as the following:
/Applications/Eggplant.app/Contents/MacOS/runscript -driveport 5400 -DriveOutputFile ~/Desktop/mydriveoutput.txt
With this option, the output file receives all returned output from executed commands. If the specified output file doesn't already exist, it will be created. If the file does exist, new output is appended to the existing file content.
Start an Eggdrive Session
Before using Eggdrive to execute commands, a client must first establish a session. This process is done by sending an XML-RPC request with StartSession as the method name. This method can take as an optional parameter the full path to a suite. If you include this parameter, Eggplant Functional opens the suite, which becomes the context for all commands executed during the session. That is, scripts and images within that suite are used by any command that is sent to Eggplant Functional.
Check the response to the StartSession call. If a fault is returned, no session has been started. The most common reason for a fault is that another session is already in progress. A Session Busy fault is returned in this case. A fault is also returned if a suite parameter was passed but Eggplant Functional failed to open the suite.
Sending Eggplant Functional Commands
After a session has been started, the client can call the Execute method. Each Execute request contains a command consisting of an arbitrary amount of UTF-8 text. This text command most often consists of a single command statement, but it can also be a multi-line block of code to be executed. The code that is sent must be a complete executable unit. Code containing repeat loops, conditional blocks, and try/catch blocks can be sent, but cannot be split among multiple requests. Upon receipt of the command or code block, Eggplant Functional executes the script text that was received, and sends back a response.
If the command code sent to Eggplant Functional successfully executes, an XML-RPC response message is returned. The content of the response is a hash that can contain any of the following elements:
- Output: A string value containing any output that was produced during the command execution.
- Duration: A double value indicating the execution duration in seconds.
- ReturnValue: If the command returns a value, this element contains that value, which can be of any XML-RPC value type, depending on what was returned.
- Result: The value of SenseTalk’s the result function following execution of the command, if it sets the result.
If an error occurs while processing the command text received by Eggplant Functional, an XML-RPC Fault record is returned. The fault includes a FaultCode and a FaultString. The FaultCode is one of the following values, and the FaultString contains additional information about the problem:
- Unknown Method: The client sent a request with a MethodName that was not recognized by Eggplant Functional.
- Session Busy: The client called the StartSession method when a session was already in progress.
- No Active Session: The client called the Execute or EndSession method without first calling StartSession to begin a session.
- Exception: An exception was thrown while trying to execute a command. This problem might be due to a command that is invalid syntactically, or it might result from an uncaught exception being raised during execution of the command.
- Session Suite Failure: A suite name parameter was given with a StartSession call, but Eggplant Functional was unable to locate or open the suite. The suite name should be the full path to the suite on the machine where Eggplant Functional is running.
End the Eggdrive Session
When a client is finished using Eggplant Functional, it should call the EndSession method. This step closes the session, frees up any resources used, and makes Eggplant Functional available for a new session to be started by another client.