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


Eviware Logo

Using Properties in soapUI

soapUI opens for the use of custom "properties" for storing custom values within a Project. A "property" is a named string value (currently all properties are handled as strings), that can be accessed from a Groovy Script, a Property Transfer or a Property-Expansion references. soapUI allows for the definition of properties at multiple levels within the project hierarchy;

  • Projects : for handling Project scope values, for example a subscription ID
  • TestSuite : for handling TestSuite scoped values, can be seen as "arguments" to a TestSuite
  • TestCases : for handling TestCase scoped values, can be seen as "arguments" to a TestCase
  • Properties TestStep : for providing local values/state within a TestCase
  • Local TestStep properties : several TestStep types maintain their own list of properties specific to their functionality : DataSource, DataSink, Run TestCase
  • MockServices : for handling MockService scoped values/arguments
  • MockResponses : for handling MockResponse scoped values
  • Global Properties : for handling Global properties, optionally from an external source

Apart from these custom properties, many soapUI objects expose their own built in properties, see for a list of which are available.

Property Editors

Properties are generally editable in three places:

  1. From the selected objects main editor window in a Properties inspector:
  2. Properties Inspecotr in soapUI

  3. From the selected objects Details tab (bottom left) in a Test Properties tab
  4. Test Properties in soapUI

  5. From the navigator itself when in Property_Mode.

The table available in the first two options has buttons to Add, Remove, Move Up and Down, Clear and Load properties from an external source as well as Save properies to a file. Loading properties has additional options of handling specific properties from a file, and properties already defined on SoapUI object.

Load Properties to Specific SoapUI object

In the table both names and values of properties can be edited as desired.

When renaming a property, soapUI will attempt to refactor all references to that property in both Property Expansions and Property Transfers.

Global Properties in soapUI

Global properties are handled in the Global Properties preferences tab, which contains a standard property-table as described above. Is is also possible to specify an external properties-file by adding a -Dsoapui.properties argument in the soapui.bat/.sh file.

For example, create a properties-file named "properties.txt" containing

test.a.property=hello!

in the soapUI bin folder. Modify the java arguments in the soapUI.bat file to be

set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx256m -Dsoapui.properties=properties.txt

Add the following Property-Expansion to a TestRequest, Endpoint, etc...

${test.a.property}

When expanded, the specified properties file will be loaded as shown in the soapUI log:

01:20:05,234 INFO  [PropertyExpansionRequestFilter] Loaded 52 properties from [C:\workspace\core\project.properties]

This feature can be especially useful when wanting to specify global endpoints or authentication settings, just specify the corresponding expansions in the endpoint or authentications properties and they will get expanded when used

Both global and system properties can be set directly from the command-line when running any of the soapUI bat/sh files; -Dproperty.name=value sets a system property and -Gproperty.name=value sets a Global Property.

Property Expansion in soapUI

soapUI provides a common syntax to dynamically insert ("expand") property values during processing. The syntax is as follows:

${[scope]propertyName[#xpath-expression]}

where scope can be one of the following literal values:

  • #Project# - references a Project property
  • #TestSuite# - references a TestSuite property in the containing TestSuite
  • #TestCase# - references a TestCase property in the containing TestCase
  • #MockService# - references a MockService property in the containing MockService
  • #Global# - references a global property (optional)
  • #System# - references a system property
  • #Env# - references a environment variable
  • [TestStep name]# - references a TestStep property within the current TestCase

Many of the scopes will of course only work if they are available, i.e. you can not use the #MockService# scope within a TestCase script since there is no containing MockService to access.

If no scope is specified, the property is resolved as follows:

  1. Check the current context (for example the TestRunContext) for a property with the matching name
  2. Check for a matching global property
  3. Check for a matching system property

If the property expansion further includes an XPath expression, this will be used to select the corresponding value from the referenced property value (which must contain XML), for example the following example could "extract" the author value from a preceding response with:

${Search Request#Response#//ns1:Item[1]/n1:Author[1]/text()}

Which would first get the "Response" property of the "Search Request" step and then select the value of the first Items' first Author element. Note that the namespace prefix must match those used in the response message, otherwise the expansion will fail.

As you can see, there is no way to access properties "outside" scope, i.e. you can not access a property in another TestCase from within a TestStep. The is a deliberate restriction aiming to reduce dependencies between items in a project. If you need to transfer values between (for example) two TestCases you should use the containing common TestSuite or Project as an intermediary; the first TestCase transfers to the common parent using a Property-Transfer or Groovy script, the second reads from the same parent. In this way, there is no direct dependency between the two TestCases and the value supplied by the first TestCase can be supplied by any other source (TestCase, Script, etc...) or statically.

Property Transfers are a more tedious way of accomplishing the same functionality as with property-expansion. On the other hand, property transfers provide the possibility to transfer complex content between request, response messages. Also, the result of a Property Transfer is visible directly in the corresponding request, response editors.

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

...
${=request.name}
...

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

...
${=request.operation.interface.project.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. One current limitation is that although scripts can be multiple lines, they can not contain nested braces (yet).. as always there is room for improvement!

Nested Properties

soapUI supports both nested and recursive property-expansion (be careful!), for example:

test = "value"
testexp = "${test}" 

-> "${testexp}" evaluates to "value"
testexp = "value"
exp = "${exp}" 

-> "${test${exp}}" evaluates to "value"
testxml = "<test><value id="123">hello</value></test>"
testxpath = "//value[@id=${id}]/text()"
id = "123"

-> "${#testxml#${testxpath}}" evaluates to "hello"

Property Expansion Points

Property Expansion is supported in many places in soapUI:

  • request messages
  • mock response messages (from the MockRunContext see Response Scripts), testStepName is ignored.
  • XPath and XQuery assertions and their matching values
  • Contains and Not-Contains content assertions
  • Request endpoints and authentication settings
  • custom request or mock response HTTP Headers
  • Property-Transfer source and target XPath expressions
  • DataSource step configuration values (soapUI Pro only)
  • MockResponse step response messages (soapUI Pro only)
  • Property Values in DataSink teststeps
  • Outgoing WSS-related username and password values
  • SAML Assertions

If the specified property in an expansion is not available during processing, an empty string will be output instead. If you are missing the possibility to expand in a desired place, please let us know so we can add support there as well!

Built-In Properties

The table below lists all properties available for property-expansion and property-transfers. The corresponding properties can also be seen in the Navigator when in "Property-Mode".

TestRequest Step

PropertyDescription
RequestThe configures request message
ResponseThe last response message (read-only)
EndpointThe current endpoint for the request
UsernameThe current username for the request
PasswordThe current password for the request
DomainThe current domain for the request

Properties

PropertyDescription
<any defined property>the properties' value

GroovyScript Step

PropertyDescription
resultthe value returned by the script from its last run (read-only)
scriptthe script itself

Run TestCase Step

PropertyDescription
<any defined property in the target TestCase>the properties' value

DataSource Step (soapUI Pro only)

PropertyDescription
<any defined property>the properties' value (read-only)

DataSink Step (soapUI Pro only)

PropertyDescription
<any defined property>the properties' value

MockResponse Step (soapUI Pro only)

PropertyDescription
RequestThe last request message (read-only)
ResponseThe configured response message


Next: Functional Testing Web Services