DoxRunner
Macquarie University Student Accommodation
Overview
​
In the context of this site, Boundary Correlation Rules represent a method of documenting those correlation rules that are primarily defined by LB and RB. The documentation is structured in such a manner that the rules can be automatically applied to a raw script that was re-recorded. This saves a lot of time when re-correlating a re-recording. It is a method that is part-way between the current auto-correlation provided by VUGen and the need to manually correlate each time it is re-recorded.
Update this table manually while correlating and it can be applied to future recordings. Although it's complex, and manual correlation is still required, the benefits when re-scripting are enormous, especially for complex correlation such as SAP NWBC and Dynamics CRM. It has the best of two worlds: Manual correlation and automated re-correlation.
​
Not all Correlation Rules are supported - only those that support function web_reg_save_param_ex.
Each rule consists of one or more Request rules, and one or more Response rules.
The DoxRunner Process Raw operation searches the script files for any occurrence of the Request rule. If found, it searches the snapshot files for any occurrence of the Response rule. If found, it inserts a web_reg_save_param_ex function immediately prior to the request that gave rise to the response, and replaces all subsequent values that meet the Request rule with the parameter name.
​
Several types of encoding of the value found in the Response before it can be used in any Request is also automated.
​
​
​
​
​
The Correlation Rules section is described below.
A correlation rule consists of a minimum of two rows in the table, both rows representing one parameter. One row must have a Role of Request and the other must have a Role of Response. There can be multiple Request rules per parameter and multiple Response rules per parameter. The result of a rule is one or more web_reg_save_param_ex functions, positioned in the script file just prior to the request that caused the response that matches the Response rule.
Summary: Correlation Rules are often not necessary, but they can be handy. The effort to to implement them manually is the same, and adding the rules to the test case document is an overhead. The value comes when rescripting. If any of the rules are still valid (coloured green) then no effort is needed. Updating the red ones is less of an effort than the original manual correlation.
How it works
A summary of the process follows:
1. The scripter prepares a fresh recording.
2. The scripter manually identifies all correlation rules.
3. The scripter selects the Boundary Correlation Rules and enters them into the Boundary Correlation Rules section of the test case.
4. If the script needs to be re-recorded, the scripter initiates the Process Raw operation which applies the rules to the raw script, automatically parameterizing the values specified. It places the web_reg_save_param_ex() function just before the appropriate request.
Refer to the table below. You will notice that there are two rows in the table per rule - a Request and a Response.
The Process Raw operation makes heavy use of the snaphot files, so the script's ...\data\... folder must be in place. If it's not there it will warn you and if you proceed it will ignore the documented Correlation Rules.
Using the pSAMLResponse parameter as an example, the Process Raw operation does the following:
1. It changes the colour of all entries in the Parameter column to red.
2. It first searches the script for any value(s) that matches the Request role. If the Signature contains a value, it first looks for that. If found (or if there's no Signature) it then looks for the LB and RB and selects the value between them. It records this value as a candidate and continues searching. It may find more than one candidate for each Request rule.
3. For each Request candidate that was found, it searches the snapshot files for its associated Response rule (that is, the one with the same Parameter name). It only searches those snapshot files that occur before the request. If the Rule is Encode, then the Value in the Request rule is encoded prior to the search.
4. If the Signature contains a value, it first looks for that. If found (or if there's no Signature) it then looks for the LB and RB and selects the value between them (if any was found that is). If the value is the same as the Request candidate, then it knows that a web_reg_save_param_ex can be prepared and it knows where in the script to insert it from the snapshot name .
5. It changes the Parameter name of the Request rule in the test case to green.
6. If the Response rule was found, it places a web_reg_save_param_ex function just prior to the request that gave rise to it. It appends the snapshot filename to the parameter name to distinguish it from similar correlated values, and to indicate where the web_reg_save_param_ex function can be found. Example: pRelayState_t44 where t44 is the snapshot name of the response.
7. It changes the Parameter name of the Response rule in the test case to green.
8. Depending on the Rule, it parameterises all occurrences in the script that occur after the request where the web_reg_save_param_ex function was inserted. If the Rule is Value, then all values after that request are parameterised regardless of LB and RB. Otherwise it only changes those values that relate to the LB and RB.
The colourisation is designed to be a quick assessment as to whether the rule was used.
Example
The example below shows that this test case defines 4 Correlation Rules (two parameters, each with one request rule and one response rule).
One pair is shown in green and one is red. The green one was found in the latest execution of the Process Raw operation and fully parameterized, but the red one wasn't. The red one should be checked to ensure it is still valid.
The name in the Parameter column is not exactly the name used in the script. The name in the script consists of the Parameter name plus the name of the snapshot that contains the appropriate response. This allows for multiple instances of the one rule.
The example also shows that the pSAMLRequest response rule was found in the t3.htm snapshot file. Hence the name of the parameter becomes pSAMLRequest_t3.
The Process Raw operation first searches all script files for the LB and RB defined in each Request rule. If the Signature column also contains a value, it is included in the search. The value between the LB and RB is used for searching for the appropriate snapshot.
Once it knows the value in the script file and the snapshot name of the Request, the Process Raw operation uses the Response rule to search all snapshot files from the first one to the one before the one in the Request.
It looks for a concatenation of the Response's LB, Value, and RB. If the Signature column contains a value, it only searches for the concatenation after the Signature value.
When a snapshot file is found that meets all criteria, it parameterises the value in the script file with a parameter name formed from the name in the Parameter column and the snapshot file number (example: pSAMLRequest_t3). It also appends the original value to the end of all lines that are updated with the parameter.
Finally the Process Raw operation places an appropriate web_reg_save_param_ex action function immediately prior to the request that gave rise to the Response rule. It also appends the original value to the web_reg_save_param_ex function.
Section Management - Boundary Correlation Rules
A Boundary Correlation Rules section may appear in three places:
-
The Test Case Template document
-
Any Test Case
-
A Solution document
It is optional. Unless you have deleted it from the Test Case Template, it will be included in all new test cases you create.
It is recommended that the section be on a page that is landscape oriented due to the number of columns.
Although the table in the Correlation Rules section is relatively complex, the structure of the section itself is relatively simple. The important components are identical to all other sections that contain a table. That is, the important components are the bookmark and the table.
There is one small difference - the table must contain a minimum of two rules - a Request Rule and a Response rule.
The table contains seven columns. A correlation rule consists of a minimum of two rows in the table, both rows representing one parameter. One row must have a Role of Request and the other must have a Role of Response. There can be multiple Request rules per parameter and multiple Response rules per parameter.
If you find yourself parameterising the same value over and over in each test case, it may be worthwhile putting those in the Correlation Rules section that is included in the Performance Test Support document. The Process Raw operation will reference those first, then reference any that are specified in the test case. If the same rule exists in both, the one in the test case overrides the one in the Performance Test Support document.
Manually deleting or re-adding it in any of the documents is relatively straightforward, but must be done with care. Make sure you follow the links on the right and review the methods described there before taking any action.
The one in the Performance Test Support document and the Test Case Template must be manually managed.
The two links on the right refer to the test case only.
In the Test Case Template
If the section exists, it is semi-structured:
-
The bookmark in the Test Case Template document = P_CorrelationRules
-
Title - can be any text, but the Microsoft Word style should begin with I_Appendix.
-
Text - can be any text up to 1,000 characters. The Microsoft Word style should be I_BodyText.
-
Table columns - there must be at least six columns with the following headings:
-
Parameter
-
Role
-
Rule
-
Signature
-
LB
-
RB
-
A Description column is useful but is not used by the Process Raw operation.
-
-
Table rows - there must be at least two rows per parameter - one for a Role of Request and one for Response. These are described in more details below.
It is recommended that you leave it with two empty rules - one for Request and one for Response. as shown here:
In the Test Case
If the section exists, it is semi-structured:
-
The bookmark will include the Test Case ID. Example P_TC001_CorrelationRules
-
Title - can be any text, but the Microsoft Word style should begin with I_Appendix.
-
Text - can be any text up to 1,000 characters. The Microsoft Word style should be I_BodyText.
-
Table columns - there must be at least six columns with the following headings:
-
Parameter
-
Role
-
Rule
-
Signature
-
LB
-
RB
-
A Description column is useful but is not used by the Performance Test Support application.
-
-
Table rows - there must be at least two rows per parameter - one for a Role of Request and one for Response. These are described in more detail below.
All entries in the table can be manually entered or populated via the Reverse Engineer process. Experience will guide the scripter as to what values are useful.
In the Solution document
If you find yourself parameterising the same value over and over in each test case, it may be worthwhile putting those in the Global Parameters section that is included in the Performance Test Support document. The Process Raw operation will reference those first, then reference any that are specified in the test case. If the same parameter exists in both, the one in the test case overrides the one in the Performance Test Support document.
If the section exists, it is semi-structured:
-
The bookmark is V_CorrelationRules
-
Title - can be any text, but the Microsoft Word style should begin with I_Appendix.
-
Text - can be any text up to 1,000 characters. The Microsoft Word style should be I_BodyText.
-
Table columns - there must be at least six columns with the following headings:
-
Parameter
-
Role
-
Rule
-
Signature
-
LB
-
RB
-
-
A Description column is useful but is not used by the Process Raw operation.
-
Table rows - there must be at least two rows per parameter - one for a Role of Request and one for Response. These are described in more details below.
All entries in the table must be manually entered or copied from one in a test case.
Correlation Rules table columns
A summary is provided here. More details of each are given below.
The parameter name. When used, the snapshot name will be appended (some exceptions apply)
Only values Request or Response are valid here and define the role of the rule
Only Value, Reverse, Encode, and Integer are valid here, depending on the Role
Used to narrow the identification where there may be some ambiguity if only LB/RB was used
The left boundary (don't use escape characters)
The right boundary (don't use escape characters)
Free form text
Parameter
The parameter name in this table is only the main part of the name. Under normal circumstances the Process Raw operation will append the snapshot filename to it.
For example, if a parameter name in the table is pControl, and it correlated with a value in the response to a request with snapshot file t66.inf, then the parameter name will become: pControl_t66. Hence it is possible for one rule in the table to be applied more than once, so long as they are associated with a different snapshot filename.
If the parameter is associated with an Encode rule, the text "_Response" is appended to the parameter name in the web_reg_save_param_ex function, and "_Request" is appended to the encoded version used in the request. The example above would become pControl_t66_Response and pControl_t66_Request respectively. This is especially useful when using the SAP Web protocol.
The Parameter column is colourized depending on the results of the Performance Test Support application. If a rule was identified and processed, it is set to green. If it was not used, it is set to red. This allows a quick assessment as to whether a rule is out of date and should be revisited.
If the request was identified from the Request rule, but the response could not be identified from the Response rule, the value in the request is parameterised and the following is inserted at the top of Action.c. This highlights the problem which the scripter is expected to fix.
Role
The Role is mandatory. Only the text Request or Response is allowed here.
A Role of Request causes the Performance Test Support application to look for all values in the script's requests using Signature, LB, and RB. It then uses the value, in conjunction with the Response Role and the Response's LB and RB, to find the appropriate snapshot file for the resulting web_reg_save_param_ex function.
If the Request rule wasn't found in the script, its associated Response rule is ignored.
If the Response rule that matches the Request rule and its value wasn't found in the snapshot files, the request is still parameterised. Since the response could not be found, the snapshot filename cannot be appended to the parameter name, nor can the web_reg_save_param_ex function's location can be determined. So the parameter is assigned at the top of Action.c and formatted as follows: <ParameterName>_n_NotFound where n is a sequential integer to make it unique.
Rule
The Rule is optional.
Valid rules for the Request Role are: Value, Integer
Valid rules for the Response Role are: Encode, Reverse
If blank, only values in the script file and snapshot file that are bounded by the Signature, LB and RB, are parameterised.
Value Rule:
It's only valid for a Request Role. The Process Raw operation determines the request value as specified by the Signature, LB, and RB, then it parameterises the values in all subsequent requests without regard to the Signature, LB, and RB. This means that you need to be very sure that the value will be unique. For example, ViewState, SAMLRequest, Salt, Cache ID, are pretty much guaranteed to be unique, so the Value rule can be applied. In general, the shorter the value text, the less likely it'll be unique. The experience of the scripter is relied upon to determine the uniqueness of the value.
Integer Rule:
It's only valid for a Request Role. Only request values with an embedded integer are considered, even though they may meet the Signature, LB and RB criteria. An example of where this used is in SAP, where parameterising a control automatically is difficult unless those with embedded integers are specified. Those without an embedded integer can either be ignored or must be manually parameterised.
Encode "x" to "y" Rule:
It's only valid for a Response Role. The Encode rule is used where the value in a response must be encoded before it can be used in a subsequent request. It can only handle simple encoding. It is only used where the CONVERT attribute of the web_reg_save_param_ex or the web_convert_param functions are not appropriate. An example of where this used is in SAP, where a value in a response includes "\x2d", but "\x2d" needs to be converted to "-" before it can be used in a request. It has a specific structure: Encode "x" to "y", where "x" is the character(s) in the response that need to be converted to "y" before it can be used in a subsequent request. More details...
Reverse:
It's only valid for a Response Role. Normally the search for a valid response will start at the first snapshot file (typically t1) and stop at the snapshot file just prior to the one containing the relevant request. However sometimes this may not be appropriate. If the Reverse rule is used, the search will begin at the snapshot file just prior to the request and start searching backwards through the snapshot files. For example, if the request matching the Request Role has t7 as the snapshot file, the search will start at t6, then t5, etc.
Signature
The Signature is optional. In most cases web_reg_save_param_regexp will be more useful, but web_reg_save_param_regexp is not yet supported by the Process Raw operation.
Do not use escape characters.
It works with the LB and RB in finding a valid Value. In most cases the LB and RB are sufficient to identify the required value, but sometimes there can be multiple instances of LB/RB in the one request or response, so more information may be needed to identify the correct one. The Signature assists by identifying text prior to the LB, narrowing down the number of LB/RB pairs.
For example, the following text may be a part of a response, but only the instance that is preceded by "newContext" is required, and the text between "newContext" and LB may vary from interation to iteration. In this case S7 can only be captured if the Signature was "newContext", the LB "('+" and the RB "+'":
'needsContext':(even|odd|eq|gt|lt|nth|first|last)(?:\\('+S3+'newContext':((?:)))|:(even|odd|eq|gt|lt|nth|first|last)(?:\\('+S7+'*((?:)))
LB/RB
The LB and RB are mandatory.
As with all correlation in LoadRunner, the LB and RB, when applied to requests, define the boundaries of text that is to be replaced by a parameter. When applied to responses they assist in identifying the request that resulted in the text.
Do not use escape characters.
Description
The Description is optional and can be any text.
Populating the rules
There are three ways that the rules can be added into the table:
-
Once the script is manually correlated, or if migrating an existing script, execute the Reverse Engineer operation
-
As you are manually correlating, put the rules into the test case instead of updating the script, and allow the Process Raw operation to update the script (recommended)
-
Once the script is manually correlated, manually copy the contents of all web_reg_save_param_ex functions and paste them into the Correlation Rules table
Reverse Engineer
It's quite tedious to manually extract correlation rules from an existing script and place them into the table of the Correlation Rules section.
The Reverse Engineer operation has a function that will extract the Response rules from an existing script and place them into the table. It will also create a corresponding Request rule, but that will only be partially populated. It can't fully populate the Request rule because it's too difficult to programatically determine the best LB and RB - this is better done manually.
Documentation
​
Like all DoxRunner rules, Boundary Correlation parameter rules are documented in a Word document within the context of a DoxRunner section. The section is optional and may be included in a test case, the Test Case Template, and/or the Solution document. It consists of a bookmark, a heading, some descriptive body text, and a table. Each rule is defined within one row of that table.
​
If Boundary Correlation rules are documented in both the test case and the Solution document, and if one with the same same parameter name is documented in both, then the one defined in the test case takes precedence during the Process Raw operation.
​
The following paragraphs cover the following:
Reverse Engineer;
​
Add a Boundary Correlation rule
​
When adding a new rule, a Boundary Correlation section must exist beforehand in the test case or the Solution document.
​
A Boundary Correlation rule can be added to a test case in three ways:​
-
Manually add a row in the table that should exist in the appropriate Boundary Correlation section;
-
Via the Green Parameter Association form during a Process Raw operation;
-
Via the Reverse Engineer operation from a legacy script.
​
It can only be added to the Solution document or the Test Case Template manually. Rules are not normally present in the Test Case Template, but can be in the rare case where a rule is known to be needed in all new test cases.
​
​
Add manually
​
This can be done in all three places (test case, Solution document, and, in extreme cases, Test Case Template). Make sure the Boundary Correlation section exists. It should exist unless you have deleted it.
​
Adding a rule manually is simply a matter of adding a row to the table that should exist in the Boundary Correlation section and typing in the details, making sure there is one row per Parameter per Role as illustrated below.
Only the Parameter, Role, and Configuration columns are used by the Process Raw operation. A Description column is useful.
A description of each column is described below the illustration. Take particular note of the Configuration column.
Extra columns can be added but are ignored by the Process Raw operation, as is the Description column.
​
​
Parameter column
A parameter name is mandatory and must conform to LoadRunner rules. It must be unique.
Configuration column
The Configuration is mandatory.
In the context of LoadTest Database rules, it contains two items of information:
1. Tablename
The name of the MySQL table;
The table name can be preceded by the word 'Table:'
2. Operation
The Operation must be one or more of the following separated by a comma.
It can be preceded by the word 'Operation:'.
Get and burn
Get random
Get sequential
Put
Update
Update status
​
Description column
The description is optional but recommended - no more than 1,000 characters.
List of valid Operations
Follow the links to see the skeleton code that the Process Raw operation places in the DatabaseOperations.c file.
Get Random Reads a record randomly from the table given a status and, optionally, a where clause.
The record is also available to be updated later by one of the two update functions below.
Get and burn Reads a record randomly from the table given a status and, optionally, a where clause.
Increments the status by 1 and re-writes the record. The record is also available to be updated later by one of the two update functions below.
Put Creates a new record given the status and a list of columns.
Update Re-writes the record previously read, given the list of columns to update and a status.
Update status Updates the record previously read, but only updates the status.
Add via the green Parameter Association screen
​
The green screen is displayed during the Process Raw operation. A LoadTest Database rule can be added at this point as illustrated below. It will be processed by the Process Raw operation as if it was documented in the test case, then it is added to the test case once the operation completes (excluding any description, which will need to be added manually later).
​
Delete a LoadTest Database rule
A LoadTest Database rule can be deleted from a test case in two ways:
-
Manually delete a row in the table that should exist in the appropriate LoadTest Database section;
-
Via the Green Parameter Association form during a Process Raw operation.
​
It can only be deleted from the Solution document or the Test Case Template manually.
Delete manually
Except for the last one, deleting a LoadTest Database rule is simply a matter of manually deleting the appropriate row in the table in the relevant LoadTest Database section. The row of the last one should not be deleted - instead just clear all cells in it.
​
If it is expected that there will be no need for any more in that test case or the Solution document, consider deleting the section altogether, making sure you delete its associated bookmark too.
Delete via the green Parameter Association screen
The green Parameter Association screen is displayed during the Process Raw operation. When it is displayed, any of the LoadTest Database rules can be deleted as shown in the illustration below.
​
