10 June 2009 - 3.0-beta-2 user guide eclipse intellij netbeans maven download nightly forum bugs blog sf.net eviware


Eviware Logo

soapUI Scripting

soapUI provides extensive options for scripting, using either Groovy or Javascript (since soapUI 3.0) as its scripting language, which to use is set a the project level in the project details tab at the bottom left. The majority of the documentation available here will be for the Groovy language, as it greatly simplifies the scripting of Java APIs (you can get more information, tutorials, etc on the Groovy Web Site). An overview of how to use JavaScript instead is further down in this document.

Scripts can be used at the following places in soapUI:

All scripts have access to a number of situation-specific variables, always including a log object for logging to the Groovy Log and a context object for perform context-specific PropertyExpansions or property handling if applicable. A context-specific variable is always available for directly accessing the soapUI object model.

Script Editors

Script editors are generally available as inspectors at the bottom of the corresponding objects editor, each having a run button, a drop-down edit menu (same as the right-click popup), an information label, and a help button;

script editor

The popup-menu (as shown above) contains standard edit-related actions and will in soapUI Pro contain a "Get Data" menu option that expands to show all properties available within the current scope. Selecting a property (or the option to create a new one) will eventually create a script to get the variable, for example

def test = context.expand( '${#Project#test}' )

Which gets the Project-level "test" property.

It is also possible to drag a property from the navigator tree when it is in Property Mode into the script; if the dragged property is "within scope" (i.e. can be accessed via property expansion), the corresponding access script will be created at the caret location

Groovy Script Library

soapUI Pro adds the possibility to have a central library of Groovy Classes that can be accessed from any script within soapUI, which can be useful for centralizing common tasks and functionality and for creating soapUI extensions. Use as follows;

  • Specify which folder to use in the soapUI Pro Preferences tab (default is <working directory>/scripts). soapUI Pro will check this folder for files with the "Groovy" extension and compile these upon startup. The folder is then checked periodically (every 5 seconds) for updates and new or existing scripts are compiled and re-compiled if necessary.
  • Scripts should be placed in folders named after their containing package, ie a script in the package soapui.demo should be in a soapui/demo folder under the specified scripts folder.
  • The compiled classes are added to the parent class loader of all Groovy scripts, you can access them as standard java classes.

Remember that the script files must be valid classes, not just arbitrary scripts... see example below.

Example

The following example is included with the soapUI Pro distribution, it consists of the following Greet.groovy file that is located in the default scripts folder:

package soapui.demo

class Greet 
{
   def name
   def log
   
   Greet(who, log) 
   { 
      name = who;
      this.log = log 
   }
 
   def salute() { log.info "Hello $name" }
 
   def static salute( who, log ) { log.info "Hello again $who!" }
}

If we create a Groovy Script Step in a TestCase, we can use the above class with the following:

def greet = new soapui.demo.Greet( "Ole", log )
greet.salute()

Running this from within the Groovy Editor will show (roughly) the following in the Groovy Editors log:

Wed Jun 27 01:36:14 CEST 2007:INFO:Hello Ole

We can also call the static salute method:

soapui.demo.Greet.salute( "Ole", log )

Which will produce the following output:

Wed Jun 27 01:36:14 CEST 2007:INFO:Hello again Ole!

If we now modify the above Greet.groovy file and change the first salute method to include an exclamation mark at the end, soapUI will pick up the modified file (once it has been saved), which is seen in the soapUI log:

Wed Jun 27 01:39:20 CEST 2007:INFO:C:\workspace\soapui-pro\scripts\Greet.groovy is new or has changed, reloading...

And now when we rerun our initial script we get;

Wed Jun 27 01:40:16 CEST 2007:INFO:Hello Ole!

Dynamic Properties

soapUI 2.5 introduces the possibility to write groovy scripts directly inside a PropertyExpansion; prefix the content with a '=' and the remaining content up to the closing brace will be evaluated as a script and its result will be inserted. For example

${=(int)(Math.random()*1000)}

will be replaced with a random number between 0 and 999 every time it is evaluated.

Of course this applies to all places where property-expansions can be used; requests, property values, file names, endpoints, etc.. etc..

Depending on the context of the expansion, relevant variables will be available for accessing the soapUI object model. For example in a request message or parameter, the containing Request object will be available through the "request" variable, allowing you to (for example) insert its name in your request

...
<name>${=request.name}</name>
...

or if you want the name of the project just navigate up the soapUI ModelItem tree:

...
<name>${=request.operation.interface.project.name}</name>
...

The following variables are (almost) always available in these scripts:

  • log : a log4j Logger logging to the groovy log window
  • modelItem : the current modelItem (for example a Request, MockResponse, etc..).
  • context : the current run-context (for example when running a TestCase och MockService)

For soapUI Pro users, the global script library is available just as in any other script, allowing you to call into objects/methods defined there for reuse.

Code Templates

soapUI Pro 2.5 adds rudimentary support for configurable code templates which will be activated when typing the correspondig template ID and pressing Ctrl-Space in an editor. Templates can be added/changed in the Preferences\Code Templates page, the following templates are available by default:

  • grut - def groovyUtils = new com.eviware.soapui.support.GroovyUtils( context )\n|
  • xhre - def holder = groovyUtils.getXmlHolder( "|#Response" )

The '|' designates the position of the caret after inserting the template.

JavaScript support

soapUI 3.0 adds support for JavaScript as an alternative scripting language. When configured, all scripts in the containing project will be interpreted using a JavaScript engine (Rhino) instead (read more about the Rhino engine and supported features at ... ). For those of you used to JavaScript this might be an easier language to get started with, here are some examples in both languages to show some differences:


Next: Using Properties in soapUI