01 March 2010 - 3.5 |
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;
Apart from these custom properties, many soapUI objects expose their own built in properties, see for a list of which are available.
Properties are generally editable in three places:
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 properties to a file. Loading properties has additional options of handling specific properties from a file, and properties already defined on 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 are handled in the Global Properties preferences tab, which contains a standard property-table as described above. These can be specified/overridden 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.
An extended possibility to override/set properties at the project/testsuite/testcase/mockservice level is also available by adding a
soapui.properties.<shortened-name-of-object>=pathtopropertiesfile
-Dsoapui.properties.TestSuite1=testsuite1props.properties
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 TestCaseMany 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:
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.
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:
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!
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"
The soapUI Navigator contains a small toggle button on top of the tree. Pressing it will
put the Navigator into Property Mode, displaying all Properties for their
corresponding objects in the tree (green = read/write, black = read-only), giving an overview of all
defined or available properties within a project.
One of the main Use cases for this mode is the possibility to drag a property from the tree into any text editor that supports Property Expansion, making it extremely easy to create property expansions as desired. If the property being dragged contains an XML value, the XPath Selector will be displayed after a drop, allowing for further property-expansion refinement | ![]() |
Property Expansion is supported in many places in soapUI:
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!
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 | |
Property | Description |
---|---|
Request | The configures request message |
Response | The last response message (read-only) |
Endpoint | The current endpoint for the request |
Username | The current username for the request |
Password | The current password for the request |
Domain | The current domain for the request |
Properties | |
Property | Description |
<any defined property> | the properties' value |
GroovyScript Step | |
Property | Description |
result | the value returned by the script from its last run (read-only) |
script | the script itself |
Run TestCase Step | |
Property | Description |
<any defined property in the target TestCase> | the properties' value |
DataSource Step (soapUI Pro only) | |
Property | Description |
<any defined property> | the properties' value (read-only) |
DataSink Step (soapUI Pro only) | |
Property | Description |
<any defined property> | the properties' value |
MockResponse Step (soapUI Pro only) | |
Property | Description |
Request | The last request message (read-only) |
Response | The configured response message |