Groovy Script Test Step

Applies to ReadyAPI 3.57, last modified on December 20, 2024

About Groovy test step

Use this test step to execute Groovy or JavaScript code from your tests.

Note: The default scripting language is Groovy (ver. 2.4.17). To use JavaScript, use the project setting Script Language.

Scripts allow you to implement complex behavior of your test. For example:

  • Complex looping or branching.

  • Modifying to test step assertions during the test run.

  • Modifying of the underlying test case (for example dynamic generation of test steps from a database) for advanced data-driven scenarios.

  • Complex validation of messages that is not possible with default assertion mechanisms.

  • Integration with external systems for reading or writing data.

  • Triggering of external actions or processes, for example sending emails or starting other programs.

  • Interacting with the user (dialogs, prompts, and so on) for getting the input or controlling execution.

  • and a lot more.

To extend your scripts, you can also use the Script Library.

Editing Groovy test step

You can modify test step settings in its editor:

Groovy Script test step editor

Click the image to enlarge it.

In the editor, you can enter the script code, run it and analyze the output to check if it works correctly. If the font of the script editor is not comfortable for you, change it by using Ctrl + mouse wheel.

In the script code, you can use the following objects:

Object Description
context Provides a scripting interface to the test case run.
log

Provides a scripting interface to the Script log (to view this log, click Logs in the bottom left corner of the ReadyAPI window and switch to the Script log tab).

You use this for debugging and logging purposes: to post and view data in the log.
testRunner Provides a scripting interface to the test runner object that is executing the current test case and test step. It exposes methods related to test execution and the underlying object model (via the testCase property).

See the common usage scenarios for testRunner below.

You can view these objects’ methods and properties in the Code Completion window. To invoke it, in the editor, type the object name and a period (for instance, testRunner.) and press Ctrl+Space.

Property list

Besides the test step editor, you can adjust the test step’s behavior by using its properties in the GroovyScript Properties and Custom Groovy Script Test Step Properties panels in the Navigator.

Name Description
Name

The test step’s name.
Description

Text describing the test step.

Values on the Custom Groovy Script Test Step Properties tab are available to other test steps in your project. For instance, you can verify these property values with the Assertion test step, or check them and change the execution flow with the Conditional GoTo test step.

You can modify, add, remove and change custom properties load values of custom properties from a file, or save them to a file. To learn more, see About Properties.

This tab contains the following properties that provide access to the test step data:

Name Description
result

A read-only property. Returns the result of the script execution.

Note: The execution result is the value passed in the return script statement:

...
return myVariable;
...
script

Returns the entire script code as a string.

Test step toolbar

The Test Step toolbar contains commands that allow you to modify a test step or appearance of the test step editor.

Groovy test step toolbar

Click the image to enlarge it.

Debugging Groovy scripts

Debugging scripts means halting the test execution on a certain line and then running through the test step by step, stopping on operations or script lines. Every time the debugger stops, you can check the values of variables. However, merely stopping before certain operations or lines is often a great help in tracking what your test is doing.

During the debugging, ReadyAPI displays information about all available variables in the Debug Info tab:

Groovy Script Debugging: Debug Info panel

Click the image to enlarge it.

Requirements and limitations

Use the debugger

Enable debugger

To save operating system resources, the debugger is disabled by default. If you click while the debugger is disabled, you will be prompted to restart ReadyAPI to enable it.

To enable the debugger when you run ReadyAPI via shell script (.bat or .sh file), use the groovy parameter:

readyapi.bat groovy

If you want to make the debugger enabled by default, do the following:

  1. Open the vmoptions file.

  2. Add the following lines:

    -agentlib:jdwp=transport=dt_shmem,suspend=n,server=y
    -Djdk.attach.allowAttachSelf=true

  3. Save the file.

  1. Open the ReadyAPI executable in a text editor.

  2. Uncomment the following section:

    # uncomment the following lines to enable Groovy debugger by default
    DEBUG_PORT=53677

    netstat -an | grep $DEBUG_PORT | grep LISTEN >/dev/null 2>&1
    while [ $? = 0 ]
    do
    DEBUG_PORT=$((DEBUG_PORT+1))
    netstat -an | grep $DEBUG_PORT | grep LISTEN >/dev/null 2>&1
    done
    INSTALL4J_ADD_VM_PARAMS="$INSTALL4J_ADD_VM_PARAMS -agentlib:jdwp=transport=dt_socket,address=$DEBUG_PORT,suspend=n,server=y -Djdk.attach.allowAttachSelf=true"
    # end of Groovy debugger switching script

  3. Save the file.

Start debugging

To start debugging, click . You can run debugging in two ways:

  • From a Groovy Script test step. This executes only the script you run it from.

    Groovy Script Debugging: Debugging Script

  • From a test case, test suite or a project. This executes the entire test in debug mode. The test will stop on every breakpoint it encounters in Groovy Script test steps.

    Groovy Script Debugging: Debugging Test
Use breakpoints

A breakpoint is a location in your script where you want the script or test to pause during the execution. Once the execution is paused, ReadyAPI will open the line with the breakpoint so that you can check the state of the test, its output and its variables.

To set a breakpoint:

  • Click the left margin of a source code line.

    Groovy Script Debugging: The left margin

– or –

  • Right-click the source code line and select Toggle Line Breakpoint.

    Groovy Script Debugging: Context menu
Step through tests

When the test run reaches a breakpoint, it stops. ReadyAPI opens the Groovy script editor and enables the following commands:

  • Step over – The execution proceeds one statement or operation at a time within the script where the execution point is now located. If the next statement calls another script, the whole call is executed as a single step.

  • Step into – The execution proceeds one statement or operation at a time regardless of where the execution point is now located. If during the execution you enter another function or script, the debugger will open it and continue the step-by-step execution.

  • Resume debugging – The execution proceeds until the next breakpoint is reached and stops on it.

  • Continue to end – The execution proceeds until the end of current script ignoring any breakpoints. If there are other scripts with breakpoints in the test run, the test will still stop on them.

Logging

When you are using a script editor, you have the Log Output panel for the test runs. It contains different script messages. For example you can post any message you want by using the log.info method:

Groovy

Groovy

// Run the test step
def tst = testRunner.runTestStepByName("Groovy Script")

//Post a status of the test step run to the Log Output panel
log.info(tst.status)

Verifying response

In the Groovy script test step, you can perform assertions like you do in the Groovy Script assertion.

Working with

Below, you can find information on common tasks that you can perform with the Groovy Script test step.

To obtain the object which refers to the containing test case, use the following code snippet:

Groovy

Groovy

def case = testRunner.testCase;

By using the testCase object, you can access and manipulate test items of the project.

There are two ways to fail the test run from your scripts:

  • To fail only the Groovy Script test step, throw an exception in your script:

    throw new Exception("Result not as expected!")

    If the Abort test if an error occurs option is enabled in Test Case Options, the test will stop. Otherwise, it will continue.

  • To fail the entire test run, use the testRunner.fail method. This marks the test failed and stops the test run regardless of the Abort test if an error occurs option.

    testRunner.fail("Result not as expected!")

The testRunner scripting object has two methods to stop the current test run:

  • cancel(String reason) – Stops the test run and marks it as Canceled. The string argument specifies the reason.

  • fail(String reason) – Stops the test run and marks it as Fail. The string argument specifies the reason.

Groovy

Groovy

if (testObject == null)
{
  testRunner.fail("testObject was not found") // Stops the test run
}

You can run any test step in the current test case. To do this, use the runTestStepByName method of the testRunner object. This method runs the specified test step and returns the result. For example, the following code snippet runs ten random requests before executing the remaining script:

Groovy

Groovy

// Run ten random requests
for( i in 1..10 )
{
  if( Math.random() > 0.5 )
    testRunner.runTestStepByName( "Request 1")
  else
    testRunner.runTestStepByName( "Request 2")
}
// Do something else

This method does not work for the Data Sink and FTP test steps. To run them from a Groovy script, use the following approach:

Data Sink test step

FTP test step

The following code snippet creates a foo property that will be available in another groovy script:

The typical scenario is to save the needed counters and collections to the context and use them to control the test flow as required.

By using the gotoStepByName method of the testRunner object, you can command ReadyAPI to jump the test execution to the specified test step after the script has finished. For example the following script randomly selects the next test step:

Groovy

Groovy

if( Math.random() > 0.5 )
  testRunner.gotoStepByName( "Request 1")
else
  testRunner.gotoStepByName( "Request 2")
// do something else before executing one of the requests

To create an assertion:

  • Obtain a test step by using the getTestStepByName method of the testCase object.

  • Use the addAssertion method to create an assertion.

  • Specify the assertion name as a string.

    ReadyAPI will create a new assertion with the specified name and default settings.

    Note: If you already have an assertion with the same name, you will be prompted to specify the unique assertion name. The test will not continue until you close the dialog.

For example, the following code snippet shows how to create a Valid HTTP Status Codes assertion for the Test Request test step:

Groovy

Groovy

// Get the test step object
def ts = testRunner.testCase.getTestStepByName("Test Request")
// Add the assertion
def vas = ts.addAssertion("Valid HTTP Status Codes")

You can modify the created assertion by using assertion-specific methods.

For example, to change the code checked by Valid HTTP Status Codes and Invalid HTTP Status Codes by using the setCodes method of the Assertion object.

You can get this object when creating it in the following way:

Groovy

Groovy

// Get the test step object
def ts = testRunner.testCase.getTestStepByName("Test Request")
// Add the assertion
def vas = ts.addAssertion("Valid HTTP Status Codes")
// Set assertion codes
vas.setCodes("200,202")

If you have already created an assertion, you can access it in the following way:

Groovy

Groovy

// Get the test step object
def ts = testRunner.testCase.getTestStepByName("Test Request")
// Search all assertions
for ( e in assertionsList)
{
  // If the assertion name matches
  if (e.getName() == "Valid HTTP Status Codes")
  {
    // Set assertion codes
    e.setCodes("503, 504")
  }
}

To remove an assertion, use the removeAssertion method.

You need to specify the assertion object to remove.

Here is the sample code that will remove the assertion created in the example above.

Groovy

Groovy

// Get the test step object
def ts = testRunner.testCase.getTestStepByName("Test Request")
// Search all assertions
for ( e in assertionsList)
{
  // If the assertion name matches
  if (e.getName() == "Valid HTTP Status Codes")
  {
    // Delete the assertion
    ts.removeAssertion(e)
  }
}

To get a property value:

  • Obtain the containing object.

  • Use the getPropertyValue() method to get a property object.

For example, the following code snippet gets a test suite property:

Groovy

Groovy

// Get username property from the test suite object
def username = testRunner.testCase.testSuite.getPropertyValue( "Username" )

To write a value to a property, use the setPropertyValue() method. For example, the following code snippet, specifies the Username parameter of the HTTP Request test step:

Groovy

Groovy

// Write the username to the HTTP Request
testRunner.testCase.testSteps["HTTP Request"].setPropertyValue( "Username", username )

See Also

Scripting
Test Steps

Highlight search results