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:

1. Launch Eggplant Functional in drive mode.
2. Start an Eggdrive session.
3. Send Eggplant Functional commands through XML-RPC calls.
4. End your Eggdrive session.

You can see examples of scripts using Eggdrive in the following programming languages:

• C#
• Java
• Python
• Ruby

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.

note

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’s the 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 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.

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 of False 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 of True 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.

note

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.