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.
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
/Applications/Eggplant.app/Contents/MacOS/runscript -driveport 5400
"C:\Program Files\Eggplant\runscript.bat" -driveport 5400
/usr/GNUstep/Local/Applications/Eggplant.app/runscript -driveport 5400
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 0turns off all logging.
-drivelogging 1logs all commands that Eggplant Functional receives and acts upon from your client.
-drivelogging 2logs the full content of each XML-RPC message that Eggplant Functional receives, as well as the shorter logs shown by
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:
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.
Each communication with Eggplant Functional is synchronous; that is, the client sends a request and waits for a response before proceeding.
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 resultfunction 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
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
MethodNamethat was not recognized by Eggplant Functional.
Session Busy:The client called the
StartSessionmethod when a session was already in progress.
No Active Session:The client called the
EndSessionmethod without first calling
StartSessionto 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
StartSessioncall, 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.
Other Eggdrive Methods
There are additional methods you can use when working with Eggdrive.
This method is similar to the
Execute method, but must include a numeric timeout value (in seconds) as the first parameter. The SenseTalk code to execute is passed as the second parameter.
ExecuteWithTimeout will not wait for the code execution to complete before returning. If the execution completes before the timeout number of seconds have elapsed, the method will return the final result just as
Execute would. However, if the code is still executing after timeout seconds, the method will return at that time with only partial results.
In addition to the
Results values that the
Execute method returns, an
ExecuteWithTimeout call will also include a
TimedOut entry in the returned object, with a Boolean value:
Falseis returned, that indicates that the code completed executing without timing out. In this case the response contains the full output and final results of the execution.
- If a
Trueis returned, that indicates that the timeout period expired before the code completed. In this case the code is still running and the response information represents only the partial output.
TimedOut result of
True from the
ExecuteWithTimeout method, the
Update method can be called repeatedly as needed until the execution completes.
Update is called with a single (optional) timeout parameter. If no timeout is specified, the
Update call will return with the latest results without any delay. If a timeout is given, the executing code may continue to run for up to that length of time before the
Update call will return.
The response from the
Update method is the same as that from the
ExecuteWithTimeout method, including a
TimedOut entry which indicates whether the code is complete (
False) or still running (
True). If the
Update method returns a
TimedOut value of
Update should be called again to get more intermediate results, until it returns a
TimedOut value of
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.
You do not need to quit Eggdrive. However, you can pass the
Quit command if desired to end the current session and terminate Eggplant Functional in drive mode.