DoxRunner
Macquarie University Student Accommodation
Document the Text Data File Rules
Overview
​
LoadRunner's native method of handling test data is the use of Text Data Files and is one of the three methods of managing data supported by DoxRunner.
​
As well as providing a mechanism for documenting Text Data Files rules, DoxRunner saves a scripter's time by using those documented rules to instrument a raw script using the Process Raw operation.
​
​The illustration on the right shows how they are configured in LoadRunner.
​
The illustration below that shows how they are configured in a DoxRunner document.
​
The rules are contained in a Text Data File section of either a Test Case or the Solution document.
​
The important components are the Parameter Name and the Configuration, as described below.
​
Parameter
​
A Primary parameter is mandatory. It must be unique and only appears in the column with heading Parameter in the table of any Text Data File section. It must also conform to LoadRunner rules.
​
A Root parameter is a Primary parameter that has a Next Row and Update Value On configuration item. In the illustration, Primary parameters pSalary and pUse are also Root parameters.
A Secondary parameter name is one that appears in those rules that have a Next Row CI starting with 'Same line as...'. It must conform to several rules, one of which is that it must not be the same as the Primary parameter for that rule, and another is that it must appear in another rule as a Root parameter.
​
Configuration
​
The Configuration is mandatory. In the context of Text Data File rules there are four Configuration Items to choose from (Filename, Next row, Same line as, and Update value on. Each Configuration Item can be preceded by a Configuration Item ID (CI ID).
​
1. Filename
​
The Filename configuration item is mandatory.
​
It can be preceded by the CI ID File: or File name:.
​
It must exclude the folder. The folder will default to the script's folder, where it eventually resides. If it exists in the Included Files folder, configured as a CI, it is copied into the script's folder. Otherwise it is created new with a single record.
​
The extension can also be omitted - '.dat' will be assumed.
​
For every file, there must be one and only one Root parameter.
That is, the Next Row CI for one file can't all be 'Same line as'
​
The following examples are all valid. They all reference the file called Land.dat or Land.txt within the script folder:
Land.dat
File: Land.txt
File name: Land.dat
Land
​
2. Next Row
LoadRunner recognizes four Next Row configuration items (Random, Unique, Sequential, and Same line as), whereas DoxRunner treats 'Same line as' as a separate CI, due to its different rule profile.
​
Hence DoxRunner only recognizes these three Next row CIs:
a. Random
b. Unique
c. Sequential
​
It is mandatory if there is no 'Same line as' CI. Otherwise it is ignored. It can be preceded by the CI ID 'Next row:'.
​
If it is documented, then there must be an 'Update value on' CI.
​
​
4. Update value on
The Update value on configuration item is mandatory if there is no 'Same line as' CI. Otherwise it is ignored.
It must be one of the following and can be preceded by the CI ID 'Update value on:'.
​
-
Once - the value of the parameter is assigned only once during the whole test;
-
Iteration - the value of the parameter is assigned and reassigned at the start of each iteration;
-
Occurrence - the value of the parameter is assigned and reassigned every time it is used.
.
​
3. Same line as
The Same line as configuration item can be preceded by the CI ID 'Same line as:'. It can take two forms as described below.
If there is no Next Row CI, the second form is assumed. Only one form can be configured for any one Filename.
​
d. Same line as <secondary parameter>
​
<secondary parameter> must reference a root parameter, not the rule's primary parameter.
If this CI is omitted, 'Same line as' is assumed, and the <secondary parameter> is inferred from the Filename.
​
Section Management - Text Data Files
​
A Text Data File section is optional, is semi-structured, and may appear in three places:​​
-
Any Test Case;
-
The Solution document;
-
The Test Case Template document.
​
Common Characteristics
​
Each instance of the Text Data File section consists of:
-
a Section Title;
-
a Bookmark;
-
free-form Body Text;
-
a Table with a minimum of two columns (Parameter and Configuration). A Description column is optional but recommended.
​
The Bookmark:​
-
Mandatory;
-
Location: Immediately before the Section Title;
-
Structure: Depends on which document it is embedded in:
-
Test Case: P_TC008_TextDataFile (where TC008 is the Test Case ID)
-
Test Case Template: P_TextDataFile
-
Solution document: V_TextDataFile
-
​
The Section Title:
-
Mandatory;
-
Location: immediately after the Bookmark;
-
Structure: Free-format text;
-
Style: I_Heading n or I_Appendix n, where n can be an integer from 1 to 5;
-
Length: Cannot be longer than 200 characters.
​
The Body Text
-
Optional;
-
Location: between the Section Title and the Table;
-
Structure: free-format text;
-
Style: I_BodyText;
-
Length: Cannot be longer than 1,000 characters.
​​
The Table:
-
Mandatory;
-
Location: immediately below the Body Text (or Section Title if there is no Body Text):
-
A minimum of two rows:
-
A Heading row and a Data row (one data row per rule);
-
If there are no rules, the Data row can contain empty cells (or the section can be deleted);
-
-
A minimum of two columns:
-
A Parameter column and a Configuration column;
-
More columns can be added;
-
A Description column is recommended.
-
-
All cells in the Parameter and Configuration columns must conform to specific rules, as described in the Overview above.​
​
​
Advice
​
Assess whether the section is necessary. This decision will need to take into consideration two factors:
-
Whether the Test Case needs Text Data Files;
-
Which scenario you have chosen when assessing the relationship between Test Case sections and Solution document sections.
​
Assess the Section Title and update it if necessary.
​
Make sure the table has the two mandatory columns (Parameter and Configuration), each with the specified heading text.
​
Assess the table to see whether more columns are appropriate, especially a Description column.
​
Assess the Body Text between the Section Title and the Table and update it if necessary.
​
Make sure its bookmark is visible and located immediately before the first character of the Section Title (see each of the examples further down this page).
​
Do not change the bookmark.
​
The section looks better when on a page with portrait orientation.
​
Test Case Section characteristics
​
In a Test Case, the Text Data File section is optional and can be located anywhere between the Description sections and the Transaction Timer section.
​
It is semi-structured as described in the Common Characteristics section above.
​
If you know that a test case won't require Text Data File rules, you may decide to delete the section. This can be done in two ways:
-
Using the DoxRunner Manage Sections operation (recommended);
​
If you deleted the section from the test case and decide to re-add it, then it can be done in two ways also:
-
Using the DoxRunner Manage Sections operation (recommended);
​
If the Solution document also contains a Text Data File section with a Parameter name that is the same as one in a Test Case, then the one in the Test Case takes precedence.
​
The illustration below shows a typical Text Data File section as it appears in a test case. Note the following points:
-
The Bookmark must be structured as shown in the Common Characteristics section above:
-
That is, "P_", followed by the Test Case ID, followed by "_TextDataFile";
-
For example, if the Test Case ID is TC405, then the bookmark should be P_TC405_TextDataFile;
-
-
The symbol is an optional link to the top of the Test Case for easier navigation.
​
Example
​
Test Case Template Section characteristics
​
The Text Data File section is optional and can be located anywhere in the Test Case Template between the Description sections and the Transaction Timer section.
​
It is semi-structured. The structure is described in the Common Characteristics section above.
​
It must be referenced by a Bookmark that must be located immediately before the Section Title. The Bookmark is structured as follows: P_TextDataFile
​
The Body Text is expected to contain generic text that will be copied to any new test case, then updated by the scripter.
​
The Table must have a minimum of two rows - a Heading row and a Data row - and two columns as shown below.
It is recommended that you leave the table empty and populate it only after it's incorporated into a test case. If the Data row contains a rule, then that rule is copied to any new test case.
​
Example
​
​
Solution Document Section characteristics
​
Text Data File rules are normally defined in the Text Data File section of a test case, however they can also be documented in the Solution document. This is optional. A Text Data File section is included in the original downloaded version of the Solution document and is available unless it was manually deleted after the document was downloaded.
​
It is optional and can be located anywhere in the Solution document.
​
There is only one way to add rules to the Text Data File section of a Solution document and that is to manually insert them into the table.
​
If it exists, the section it is semi-structured. The structure is identical to the test case and is described under the Common Characteristics title above.
​
It must be referenced by a Bookmark that must be located immediately before the Section Title. The Bookmark is structured as follows: V_TextDataFile
​
Why would you use the Solution document to document Text Data File rules? You don't need to, but if there are rules that are common across multiple test cases, then itmay be easier to manage if placed in the Solution document instead. In fact, to take an extreme view, you can document -all- Text Data File rules in the Solution document and define -none- in the test cases, if that is easier to manage. The choice is yours.
​
If a rule in a Data row of the Table contains a Parameter name that is he same as one in a test case, then the one in the test case takes precedence.
​
Example
​
Add a text data file rule
​
In all cases, each Text Data File rule is documented as a row in the table that is embedded in a Text Data File section. The section must exist in the appropriate place beforehand.
​
They can be added to a Test Case in three ways:
-
Manually add a row in the table that should exist in the appropriate Text Data File section;
-
Via the green Parameter Association screen during a Process Raw operation;
-
Via the Reverse Engineer operation from a legacy script.
​
They can only be added to the Solution document or the Test Case Template manually.
An empty table is present in the Test Case Template when downloaded from this site. Rules are not normally added to this table, but can be in the rare case where a rule is known to be needed in all (or most) new test cases.
​
​
Add a Text Data File rule manually
This can be done in a Test Case, the Solution document, and the Test Case Template. Make sure the Text Data File 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 and typing in the details, making sure there is one row per rule as illustrated below. Only the Parameter and Configuration columns are used by the Process Raw operation.
Extra columns can be added, but are ignored by the Process Raw operation. A Description column is optional but recommended.
Refer to the Overview above for details of each column. Take particular note of the Configuration column.
​
Add a rule via the green Parameter Association screen
​
This can be used only for a Test Case.
The green screen is displayed during the Process Raw operation. If it is noticed that a Text Data File rule is missing, then it can be easily added to the Test Case at this point as illustrated below.
It will be processed by the Process Raw operation as if it was documented in the test case. Once the operation completes it is added to the Test Case (excluding any description, which will need to be added manually later).
​
Type in a unique Parameter name.
​
Either select an existing Filename or type in a new one.
Select a Next Row CI.
​
If the Next Row CI is 'Same line as', then select a Secondary Parameter Name, otherwise select an 'Update value on' CI.
Either press the Configure only button, or select a value from the Unassociated Name-Value Pairs pane and press one of the other two association buttons.
The new rule will be added to the Associated Values pane.
​
If this is the only rule for an existing Filename, then a Next Row CI of 'Same line as' won't be appropriate by itself.
​
In this case, adding or selecting a rule with a Next Row CI other than 'Same line as will allow you to continue.
​
Once all associations for all rules are complete, and the Apply button is pressed, the Process Raw operation treats the new rule like any other.
​
Once the Process Raw completes it's job of updating the script, it adds the new rule to the Test Case.
The scripter must manuall update any optional columns, including the Description column.
​
Add a rule using the Reverse Engineer operation
​
This option is only available if there is a legacy script that contains Text Data File rules, and only applies to a Test Case.
​
The Reverse Engineer operation is designed to update the documentation for a Test Case from a legacy script.
Text Data File rules are included in this process, however it's possible that not all rules are captured and documented.
Make sure you check the Test Case once the Reverse Engineer operation has completed.
Delete a text data file rule
​
A rule can be deleted from a Test Case either manually or via the green Parameter Association screen during a Process Raw operation.
​
Delete manually
​
Except for the last rule, deleting one can be done manually in all documents by simply deleting the respective row in the table.
​
Deleting the last rule can be done in two ways:
-
Simply clear all cells in the row (do not delete the row);
​
Delete using the Green Parameter Association Screen
​
If, during the Process Raw operation, a Text Data File rule is noticed that is no longer required, it can be deleted from the Test Case using the Delete from document button that appears on the green Parameter Association screen.
​
All those with "Same line as..." operations can be deleted immediately.
​
The root parameter can only be deleted once all of its secondary parameters are deleted.
​
The illustration below shows when a Text Data File rule can be deleted via the green Parameter Association screen.
​
