Property Transfer TestSteps are used to transfer properties between TestSteps and their containing TestCase, TestSuite and Project. They are extremely useful in a number of situations, especially when properties containing XML are involved, for example when you need to
- Extracting a value from an XML message, for example a sessionID from a SOAP Response
- Write a value into an XML message, for example a saved sessionID or authentication data
- Transfer complex XML content between properties
Lets get to grips!
1. The Property-Transfer Window
Creating or double-clicking an existing Property-Transfer TestStep opens the following window:
The list to the left shows you the configured transfers in this TestStep, add and manage as many as you want. When selecting a transfer (like the "TransferUser" in the screenshot above), the area to the right allows you to configure it as desired;
- The Source area at the top specifies the source property and optional XPath for the transfer
- The Target area under that specifies the target property and optional XPath for the transfer
- The area below that holds different configuration options set on a transfer to transfer level.
The Transfer Log at the bottom shows the latest executed transfers while the window was open and their actual transferred values.
The available configuration options can drastically change what is transferred and their respective is defined as:
- Fail transfer on error - The transfer step will fail in case any errors happen while attempting to perform the transfer
- Transfer text content - Only text content will be transferred. No structural elements will be preserved
- Transfer to all - The matched values will be transferred to all the target locations in case there are several that matches
- Entitize transferred values - The values will have certain characters for example ampersand ("&") replaced with it's corresponding character entity value ("&")
- Set null on missing source - The target will be set to null in case the source resource is missing. This means that if the target already has a value it will be lost
- Ignore empty/missing values - This means that if the matched value of the source is empty or missing it will be ignored and the target value left untouched
- Use XQuery - SoapUI will assume that the source is XQuery rather than the default XPath when trying to extract the source values
- Transfer child nodes - SoapUI will not attempt any textual extraction from the matched source node but rather pick the children of the matched node and thus preserving the subtree XML structure
2. Transfer Execution
When the PropertyTransfer TestStep is executed during a TestCase run, each transfer in the Property Transfer is performed by selecting the property specified by the transfers source step, property and optional XPath expression and copying their value(s) to the destination steps specified property using an optional XPath expression. If XPath expressions are specified, soapUI will try to replace the target node with the source node if they are of the same type. If not (for example when assigning text() to an @attribute), soapUI will do its best to copy the value as possible.
Source and target XPath expressions must both point to existing nodes in their respective properties, the source property obviously requires the node so it can be selected, the target property requires the node so it can be found and overwritten.
If any of the transfers fail due to missing matches of any of the XPath expression, an error is printed and the step will either fail or go on, depending on of the "fail on error" option has been selected for that transfer. TestCase execution is only aborted if the TestCases' "Fail on error" option has been set as described for under TestCase Options.
3. An example: transferring a session ID from a response to a following request
This is a very common scenario, lets do a step-by-step walkthrough. Lets say we have a login service that returns a sessionID that we subsequently want to use to authenticate; a property-transfer is perfect for extracting the sessionID and writing it to a property that can then by referred to by all desired TestSteps. Here we go:
- Add and execute the login request to an empty TestCase so you have a valid response to work with;
- Create the Property-Transfer TestStep after the request and add a property-transfer to it;
- Configure the source-property to be the Response of the Login Request and then select the "Wizard" button to the right on the source property toolbar. This opens a convenient wizard for selecting the desired source node to transfer from (in standard soapUI you will have to manually create the generated XPath statement).
- Select the node and press OK; soapUI generates the corresponding XPath statement for you;
Now the source is all set up and your next step is to configure the target for the property-transfer, ie where it should be written. We have two options;
- write it to a temporary property that can be referred to by all subsequent TestSteps that need to use the sessionID. This is the best solution if we want to use the sessionID in several places or TestSteps
- transfer it directly to the target TestStep(s) where the value should be used. This is easier if you just want to use the value in one place
Lets have a look at both of these
3.1. Writing to a Temporary Property
Lets save the property to a TestCase property that we have defined with the name "SessionID";
Now when executed, the SessionID is transfered to the specified TestCase property and can later on be used in any request via standard property-expansion (or another property-transfer), for example in a logout request we could have
Which would replace the expansion with the saved SessionID when the request is being sent.
3.2. Writing directly to the desired target TestStep
This is more straight-forward; set the target to be the logout request and use the XPath Wizard again (or your XPath skills) to create the target XPath statement;
Now when executing this, the source target value will get directly extracted from the response and written into the request message.