Using Eggdrive with Eggplant Functional
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 drive mode
.
Mac:
/Applications/Eggplant.app/Contents/MacOS/runscript -driveport 5400
Windows:
"C:\Program Files\Eggplant\runscript.bat" -driveport 5400
Linux:
/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 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.
Each communication with Eggplant Functional is synchronous; that is, the client sends a request and waits for a response before proceeding.
Success Responses
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’sthe result
function following execution of the command, if it sets the result.
Failure Responses
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 aMethodName
that was not recognized by Eggplant Functional.Session Busy:
The client called theStartSession
method when a session was already in progress.No Active Session:
The client called theExecute
orEndSession
method without first callingStartSession
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 aStartSession
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.
Other Eggdrive Methods
There are additional methods you can use when working with Eggdrive.
ExecuteWithTimeout Method
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.
Unlike the Execute
method, 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 Output
, Duration
, ReturnValue
, and Results
values that the Execute
method returns, an ExecuteWithTimeout
call will also include a TimedOut
entry in the returned object, with a Boolean value:
- If
TimedOut
value ofFalse
is 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
TimedOut
value ofTrue
is 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.
Update Method
Following a 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 (TimedOut
is False
) or still running (TimedOut
is True
). If the Update
method returns a TimedOut
value of True
, then Update
should be called again to get more intermediate results, until it returns a TimedOut
value of False
.
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.