DoxRunner
Macquarie University Student Accommodation
Overview
​
LoadRunner measures the response time of each step in a business process via the use of lr_start_transaction() and lr_end_transaction() functions.
DoxRunner defines how these timers are configured in a script. DoxRunner recognizes three types of timer:
-
Step;
-
Common;
-
End to End.
​
The underlying assumption is that the steps in a business process are executed sequentially, hence the name of each timer is prefixed by a sequential integer so that the LoadRunner Analysis report also lists them sequentially, facilitating the understanding of the test by the report recipients.
​
An extract of how a typical Transaction Timer is documented in DoxRunner is shown in the illustration below.
​
The Process Raw operation applies the documentation to a raw script. The illustration below also shows how Timer ID 5 is applied to a raw script.
​
ID
​
DoxRunner identifies Transaction Timers by a
numeric ID followed by the Timer Name.
​
The ID is mandatory and is designed to ensure
that timers are reported sequentially.
​
The integer must be sequential but there is some
flexibility. It can have gaps which allows steps to increment by, say, 10 (ie. 10, 20, 30,...) or if a script has more than one stream, a longer gap can be utilized (ie. 1, 2, 3, 25, 26...etc).
When recording a script, use this number and only this number, as described in the recording section. That is, don't use the Timer Name when recording.
​
Do not leave the ID blank, and only use integers.
​
Think Time
​
Although Think Time is entered by VUGen during recording, it is often unrealistic.
​
By including them in the Transaction Timer table, the scripter has the opportunity to tailor them based on a more appropriate value that represents how long it would take for a competent user to execute that step.
​
For example, if a tab or button is to be pressed, the think time would be short, whereas if text such as a description or a name is required, then the think time should be much longer
The ​Process Raw operation will (optionally) replace all think time functions that LoadRunner may have inserted, with the value from the Transaction Timer table, and places them immediately prior to the relevant start transaction timer (refer to the script illustration above).
​
Timer Name​
​
The Timer Name forms a part of the Full Timer Name. It is mandatory and should be a very brief alphanumeric description of the business process step so that it can be better identified by anybody who is the recipient of the analysis report. For example "Press Next", when reported in the Analysis, is meaningless. Consider "Accept Details Of Cane Estimate".
​
Make the Timer Name consistent across all scripts that use the same business process step. This way the Common Timer will represent all instances across all scripts in the Analysis report.
When all components of the full timer name are combined, it must conform to LoadRunner rules.
​
When recording a script, do not use it - use the Timer ID only, as described in the Recording section.
​
Expected Results
​
This is optional text description of what is expected when the step is executed in a LoadRunner test. The Process Raw operation includes it in the script as documentation (refer to the script illustration above).
​
Response Time NFR
​
This column is optional and documents the Response Time NFR in two possible ways:
-
As a value in seconds (example: 5.9 secs);
-
As a link to the NFR section when the NFR is more complex.
​
Since NFRs can be more complex than just pinning it down to a single response time, the latter option is recommended. It is easier when liaising with a Business Analyst - each step can then be categorized depending on its task, and each category can then be placed into the NFRs section and described at length.
​
Phase
​
The Phase is useful if you choose the easy way of recording a raw script. That is, if you choose to record ALL actions in Action.c rather than attempting to record the log-in sequence in vuser_init.c and the log-out sequence in vuser_end.c.
The Phase tells the Process Raw operation to move the appropriate steps from Action.c into the appropriate file.
​
There are four phases recognized by the Process Raw operation, and they must appear in the same order as the description of each here:
LI - Log In - optional - the step(s) needed to log in.
These are normally moved to vuser_init.c, or a function that is called from vuser_init.c
TI - To Iteration - optional - the step(s) needed to move the session from the login or home page to the first step of the iteration.
These are normally moved tovuser_init.c, or a function that is called from vuser_init.c.
I - Iteration - mandatory - the steps executed during each iteration. These are normally left in Action.c.
LO - Log Out - optional - the step(s) used after all iterations are complete.
These are normally moved to vuser_end.c, or a function that is called from vuser_end.c.
By default, when recording a script, VUGen will place all steps into Action.c (unless you configured it otherwise, which is not recommended here). Also by default, the Process Raw operation automatically moves steps from Action.c into another script file. Intuitively the LI and TI steps would be moved to vuser_init.c and LO steps moved to vuser_end.c, but it is more flexible than that. It actually moves the steps into any file that has the following signature(s):
// <Transfer phase LI to here>;
// <Transfer phase TI to here>;
// <Transfer phase LO to here>;
This allows one or more files to be placed in the _Included Files folder that allows better management of the session. Refer to <TBA> for more details.
​
Validation
​
When recording a script, VUGen provides the option of entering a value used by web_reg_find, but it limits the LB and RB to <title> and </title> respectively, and some applications do not include these tags in some responses. In addition, the web_reg_find function prepared by VUGen does not include the tags, so there is a risk that the page is wrong but the text is still in the response.
The options described here are more flexible. If you enter text into the Validation column, the Process Raw operation will automatically prepare web_reg_find functions using that text, and place it immediately prior to the first request of the step. Note that if the Transaction Timer includes multiple requests, the Process Raw operation only applies the web_reg_find() function to the first one. If any others are required, then they must be manually configured.
​
If the Validation cell is left empty for one or more steps, the Process Raw operation will attempt to determine a value using the Validation Template LB and Validation Template RB CIs defined in the Configuration section, if they are found in the appropriate response. By choosing appropriate LB and RB values, more cells in the Validation column will be empty and typing is reduced, enhancing the efficiency of re-recording the script. Even if you just emulate VUGen's rule and use <title> and </title>, these tags will be included in the web_reg_find function, improving accuracy.
If the Validation cell for a step is empty and either there is no Validation Template CIs, or the Process Raw operation could not find a value, then the following is placed into the script (where nnn is the snapshot event number):
​
// web_reg_find("Text=<update manually from response to snapshot event tnnn>", LAST);
In this case, even if a value cannot be found, typing is reduced because the function skeleton is prepared for you, but commented out. You can either do nothing (and take the risk that the wrong page is returned), or manually find a value in the response and update it manually (don't forget to un-comment it). If the latter, don't forget to also copy the text into the Validation cell so that it is automatically updated the next time you record the script.
Refer also to the Validation Template CIs in the Configuration section.
​
​
Timer Long Name​
​
The Timer Long Name is constructed by the Process Raw operation from a template specified as a CI in the Configuration section.
​
At a minimum it should consist of the ID and Timer Name, but ideally it should be prefixed by the Test Case ID so that it appears in the LoadRunner Analysis report in a logical order.
​
For example, Timer ID 5 in the example above should ideally appear as "CEP001 05 Enter Lot Number'" in the analysis report, using the Timer Template that is the default when the DoxRunner Solution document is initially downloaded, reproduced here:
<Test Case ID> <Timer ID> <Timer Name>
​
Notes
​
This column is designed purely to assist the scripter when recording a raw script. It does not appear in any script or report and is optional.
Use this column to enter notes that are useful to the person recording and debugging the script. When recording the script keep these notes visible to ensure you record correctly and/or update the notes if it's helpful.
​
Although some notes can be written when defining the test case, it is expected that most updates will occur when recording the first script. Update this column so that future scripters will find it easier to re-record it (including yourself). Include any gotchas, preparation, etc that is relevant to recording the step. Consider it a replacement for screenshots.
​
If the cell is insufficient to describe what is required, add a paragraph to the Scripting Notes section, and provide a link to it in the Notes cell. This is particularly useful if a screenshot is necessary.
​
Timer Types
​
Step
​
This is the standard timer type, and is the one documented in the Transaction Timers section. It is the one that is generated when recording the script. It is designed to time steps in a business process.
​
​
Common
​
This timer type is not documented - it is generated automatically if selected when executing the Process Raw operation. It is simply wrapped around the standard Step timer type, but without any reference to the Test Case ID or the Timer ID.
​
It is designed to aggregate the response times across all scripts with the same Timer Name so that a test-wide view of these timers is reported in the Analysis report.
​
End to End
​
This timer type is not documented - it is generated automatically if selected when executing the Process Raw operation. It is simply wrapped around all steps in Action.c so that the total response time for all steps for the iteration is reported.
​
Section Management - Transaction Timers
​
A Transaction Timer section is mandatory, is semi-structured, and may appear in two places:​​
-
Any Test Case;
-
The Test Case Template document.
Common Characteristics
​
Each instance of the Transaction Timer section consists of:
-
a Section Title;
-
a Bookmark;
-
free-form Body Text;
-
a Table with, ideally, eight columns (ID, Notes, Timer Name, Expected Results, Think Time, Response Time NFR, Phase, and Validation);
-
Only the ID and Timer Name columns are mandatory, but the remaining six are highly recommended;
-
More columns can be added.
​
Because of the number of columns, it is recommended that the page is landscape oriented.
​
The Bookmark:​
-
Mandatory;
-
Location: Immediately before the Section Title;
-
Structure: Depends on which document it is embedded in:
- Test Case: P_APP056_Timers (where APP056 is the Test Case ID)
-
Test Case Template: P_Timers
​
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 timer);
-
If there are no timers, the last Data row can contain empty cells;
-
-
Ideally eight columns:
-
ID, Notes, Timer Name, Expected Results, Think Time, Response Time NFR, Phase, and Validation;
-
More columns can be added;​
-
-
All cells must conform to specific rules, as described in the Overview above.​
​
A Transaction Timer section is mandatory, is semi-structured, and may appear in two places:​​
-
Any Test Case;
-
The Test Case Template document.
​
​
Advice
​
This section is mandatory for all Test Cases.
​
Assess the Section Title and update it if necessary.
​
Make sure the table has the two mandatory columns (ID 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.
​
If all ideal columns are included, then the section looks better when on a page with landscape orientation.
​
Test Case Section
​
The Transaction Timer Rules section is mandatory In all Test Cases.
Because of the number of recommended columns, it should be on a page oriented as Landscape and, because of this, it is best to place it as the last section of the Test Case.
​
It is semi-structured as described above.
​
You should not delete the section in any Test Case. If you do, you will need to manually re-add it.
​
The illustration below shows a typical Transaction Timer Rules section as it appears in a Test Case. Note the following points:
- The Bookmark must be structured as shown in the previous section:
-
That is, "P_", followed by the Test Case ID, followed by "_Timers";
- For example, if the Test Case ID is TSC705, then the bookmark should be P_TSC705_Timers;
-
-
The symbol is an optional link to the top of the Test Case for easier navigation;
-
The test case long name is automatically appended to the section title by the Create Test Case operation (this can be changed at any time).
​
Example
​
Test Case Template Section
​
The Transaction Timers section is mandatory and can be located anywhere in the Test Case Template However it is recommended that it be positioned as the last section, and the page be oriented as landscape.
​
It is highly structured. The structure is illustrated below.
​
It must be referenced by a Bookmark that must be located immediately before the Title.
The Bookmark is structured as follows:
P_Timers
​
The Body Text is expected to contain generic text that will be copied to any new test case.
​
The Table must have a minimum of two rows - a Heading row and a Data row. The Data row may contain more than 2 rows and may contain Timers that are common to any test case.
​
Example
​
Solution Document Section
​
Transaction Timer rules do not appear in the Solution document outside of any test case..
​
Add a Timer rule
​
All Transaction Timer rules are documented as a row in the table that is embedded in a Transaction Timers section, which must exist beforehand.
​
They can be added to a Test Case in two ways:
-
Manually add a row in the table that should exist in the appropriate Transaction Timers section;
-
Via the Reverse Engineer operation from a legacy script.
​
It can only be added to the Test Case Template manually.
They do not exist in the Solution document.
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 (or most) new test cases.
​
​
Add a Timer rule manually
This can be done in a test case, and the Test Case Template, but not the Solution document. Make sure the Timers 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 timer as illustrated below. Only the following columns are used by the Process Raw operation:
-
ID - Mandatory
-
Timer Name - Mandatory
-
Expected Result - Optional
-
Think Time - Optional
-
Phase - Optional
-
Validation - Optional
The Notes column is very useful for guidance when recording the script. Extra columns can be added, but are ignored by the Process Raw operation.
​
Refer to the Overview above for more details of each column.
​
Add using the Reverse Engineer Operation
​
The Reverse Engineer operation is designed to update the documentation for a Test Case from a legacy script.
Transaction Timers 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 Timer
​
Except for the last Timer, 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 only one way:
-
Simply clear all cells in the row (do not delete the row);
-
Do not delete the section - it's mandatory.
​
Before executing any of the Test Case or Script operations, there must be at least one transaction timer. That is, even a single row that is empty is not valid.
​