Preface
Test preparation becomes more complicated task when a test should be automated. One of the difficulties is the existence of a test environment where the automated tests can be prepared.
The Message Stub tool from the SOAtest can help in test preparation when a test environment is not ready.
This document is focusing on several request/response correlation mechanisms provided by SOAtest.
In Short
Use the message stub tool where there is no a test environment for automated tests preparation.
Use a data source (always use a data source ;) to store request information and response.
Use correlation mechanisms provided by the message stub to provide expected response for a request.
Data Source Correlation
This mechanism uses a data source to find a matching data to response.
Request XML Message
This is the most simple correlation method. The following example will help to illustrate it.
Let’s say that a request has an element <Key>. Let’s say that a data source has a column MessageID. This correlation method uses a value in the <Key> element and tries to match it to a value in the MessageID column.
The SOAtest user guide describes several different matching attempts that should be used. From my experience only matching by exact value and wild cards are working.
When a REST client with POST method is used to send a request to a Message Stub make sure that Content-Type header is changed from default value to text/xml.
Sometime you can get an error about correlation even with a simple data source table, where a mistake is unlikely:
-------------------
<Error>
<Reason>Failed to respond to incoming message using data source row correlation</Reason>
<Details>Values in incoming message did not match values in the data source "Excel"</Details>
<Values>
<Value DataSourceColumnName="Key">42</Value>
</Values>
</Error>
-------------------
Restart SOAtest server. The server keeps a bad response in its cash.
When data is update, the correlation mechanism still uses old data until the server is re-started or the SOAtest is restarted.
Request HTTP URL parameter
The Request HTTP URL parameter correlation mechanism can be the best illustrated with an HTTP GET request.
Let’s say that a request is http://<host>:<port>/path/Endpoint?param1=value1¶m2=value2
Let’s say that a data source has a column MySales.
This correlation method finds a response row in a data source by searching specified parameter’s value in the specified column. For example correlation configured to use param2 and the column MySales. A row from a data source will be selected for a response if data source column MySales has value matching to param2 value.
Test Correlation
The Test Correlation does not use a data source. This is a difference from Data Source Correlation.
Transport
This correlation uses header name and it’s value pair to determine if this message stub should respond on a request.
For example a message stub is using Transport correlation. Let’s configure it with header named NewHeader and value 21. As a result, this message stub will be used only if a request has NewHeader with value 21.
Transport and Data Source correlations can be used together.
XML Message
This correlation mechanism uses either an element’s value or elements name/position from an xml based request to decide if this message stub.
This correlation can have only one value.
In order to simplify the configuration do the following:
This correlation mechanism is very similar to Data Source: Request XML Message correlation but does not allow multiple values.
URL Parameters
This correlation mechanism is very similar to Data Source Request HTTP URL Parameters correlation with only difference that parameters’ values do not come from a data source.
Test preparation becomes more complicated task when a test should be automated. One of the difficulties is the existence of a test environment where the automated tests can be prepared.
The Message Stub tool from the SOAtest can help in test preparation when a test environment is not ready.
This document is focusing on several request/response correlation mechanisms provided by SOAtest.
In Short
Use the message stub tool where there is no a test environment for automated tests preparation.
Use a data source (always use a data source ;) to store request information and response.
Use correlation mechanisms provided by the message stub to provide expected response for a request.
Data Source Correlation
This mechanism uses a data source to find a matching data to response.
Request XML Message
This is the most simple correlation method. The following example will help to illustrate it.
Let’s say that a request has an element <Key>. Let’s say that a data source has a column MessageID. This correlation method uses a value in the <Key> element and tries to match it to a value in the MessageID column.
The SOAtest user guide describes several different matching attempts that should be used. From my experience only matching by exact value and wild cards are working.
When a REST client with POST method is used to send a request to a Message Stub make sure that Content-Type header is changed from default value to text/xml.
Sometime you can get an error about correlation even with a simple data source table, where a mistake is unlikely:
-------------------
<Error>
<Reason>Failed to respond to incoming message using data source row correlation</Reason>
<Details>Values in incoming message did not match values in the data source "Excel"</Details>
<Values>
<Value DataSourceColumnName="Key">42</Value>
</Values>
</Error>
-------------------
Restart SOAtest server. The server keeps a bad response in its cash.
When data is update, the correlation mechanism still uses old data until the server is re-started or the SOAtest is restarted.
Request HTTP URL parameter
The Request HTTP URL parameter correlation mechanism can be the best illustrated with an HTTP GET request.
Let’s say that a request is http://<host>:<port>/path/Endpoint?param1=value1¶m2=value2
Let’s say that a data source has a column MySales.
This correlation method finds a response row in a data source by searching specified parameter’s value in the specified column. For example correlation configured to use param2 and the column MySales. A row from a data source will be selected for a response if data source column MySales has value matching to param2 value.
Test Correlation
The Test Correlation does not use a data source. This is a difference from Data Source Correlation.
Transport
This correlation uses header name and it’s value pair to determine if this message stub should respond on a request.
For example a message stub is using Transport correlation. Let’s configure it with header named NewHeader and value 21. As a result, this message stub will be used only if a request has NewHeader with value 21.
Transport and Data Source correlations can be used together.
XML Message
This correlation mechanism uses either an element’s value or elements name/position from an xml based request to decide if this message stub.
This correlation can have only one value.
In order to simplify the configuration do the following:
- Prepare a literal form of an expected request.
- Click on Edit button and switch to the Literal tab.
- Paste the prepared xml into the text area.
- Switch to Tree view.
- Select an element for the correlation.
- Select a Function and Value if required.
- Press OK.
This correlation mechanism is very similar to Data Source: Request XML Message correlation but does not allow multiple values.
URL Parameters
This correlation mechanism is very similar to Data Source Request HTTP URL Parameters correlation with only difference that parameters’ values do not come from a data source.
