Transaction Timers

LoadRunner measures the response time of each step in a business process via the use of lr_start_transaction() and lr_end_transaction() Timers, which are inserted into a script immediately prior to the first request of a business process step and immediately after the last request of that business process step.

Timer documentation is critical to the execution of DoxRunner's Process Raw operation.

Because the steps in a business process are executed sequentially, 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 analysis report recipients.

Timer Types

DoxRunner supports three types of timer:

Standard - normal LoadRunner start/end transaction functions wrapped around all requests associated with one business process step. This type is the one familiar to all LoadRunner scripters;
Common - also wrapped around one business process step, but with any context such as the Test Case ID and Timer ID removed - only the Timer Name remains, and the first character is an underscore;
End-to-End - wrapped around -all- requests in Action.c.

Standard Timers

This is the one that all LoadRunner scripters use. It is the one documented in the Timers section.

The DoxRunner Process Raw operation formats them in special way.

Example for Test Case CEP001, Timer 02:

lr_start_transaction("CEP001 02 Log Into Cane View");

|

lr_end_transaction("CEP001 02 Log Into Cane View");

Common Timers

This Timer Type is one that DoxRunner invented.

They only appear in any script if the option was selected when initiating the Process Raw operation. It simply wraps the Common Timer around the Standard Timer, so it essentially duplicates the Standard Timer within one script, but with the effect described below.

The more occurrences of a transaction during a test, the better and more reliable the statistics in the analysis report are. However, often the number of transactions during a test, especially within vuser_init.c, are far fewer than ideal. Often some of these transactions are present in more than one Test Case, but are still of interest from a performance perspective. The Standard Timer Type discussed above will report these transactions separately, so the statistical count for each may be relatively low. A typical example is the login step.

Example for Test Case CEP001, Timer 02:

lr_start_transaction("_Log Into Cane View");

lr_start_transaction("CEP001 02 Log Into Cane View");

|

lr_end_transaction("CEP001 02 Log Into Cane View");

lr_end_transaction("_Log Into Cane View");

They are designed to improve the statistical reporting in the analysis report of these low-count transactions by naming them with the Timer Name only. They are then collected across all test cases in a test and appear in the analysis report as one line item.

Common timer names begin with an underscore so that when the analysis report is prepared, they appear altogether at the top. In this way you can decide whether to delete them all, or delete all except a sub-set that may be of interest. For example, if a Timer Name of "Press Cane Estimate Button" appears in several scripts, their response times appear in the analysis report in two places

under each Test Case in which they are configured;
in one line as "_Press Cane Estimate Button", representing the statistics of all those that appear in all Test Cases in the test.

If the Timer Name appears in only one test case, then the common type in the analysis report is irrelevant - they will be identical. It's best practice to manually delete these from the analysis report.

End to End Timer

Often a business is interested in the time it takes for all transactions in an iteration. This can be achieved in the analysis report by wrapping a special timer around all transactions in Action.c.

DoxRunner uses a specific name for this timer. For example, if the Test Case ID is "CEP001", and the Test Case Name is "Cane Volume Estimation Process", then the Timer will be configured in the script as:

lr_start_transaction("CEP001 Cane Volume Estimation Process_End_To_End");

|

lr_end_transaction("CEP001 Cane Volume Estimation Process_End_To_End");

It is not necessary to document the end-to-end timer - it is generated automatically if selected when initiating the Process Raw operation.

Process Raw Operation

The DoxRunner Process Raw operation uses the DoxRunner documentation to convert a raw script into one that meets the desired final script, or close to it. Timers play a significant part in this operation.

The illustration below summarises what happens with Timers when you initiate that Process Raw operation.

How Timers are documented is detailed after the illustration below.

After recording a raw script the DoxRunner way, only lr_start_transaction() functions are recorded, containing only the Timer ID.

The Notes column is used when recording a raw script, not by the Process Raw operation.

The Timer Name is appended to the Test Case ID and Timer ID to form the Timer Long Name. This can be influenced by the Timer Name Template in the Configuration section.

The Expected Results are inserted into the script as comments.

The lr_think_time() function is either untouched, or updated. If updated, the value is determined by the option set when initiating the Process Raw operation. It could be the documented Think Time as shown in the illustration below, or a static value.

The text from the Response Time NFR column is assessed. If it references an NFR ID from the NFR Section, then the text from the NFR Requirement column is inserted into the script as comments. Otherwise the text from the Response Time NFR column of the Timer is inserted into the script as-is.

Although it is normal practice to record transactions into at least three files (vuser_init.c, Action.c, and vuser_end.c), recording the DoxRunner way means that all transactions are recorded only into Action.c. Using the Phase column in the Timers table, the DoxRunner Process Raw operation will automatically move Timers from Action.c to vuser_init.c and vuser_end.c. If the Error Recovery function is used, then they are automatically transferred to the file(s) of your choosing.

If the Validation column has a value, a web_reg_find() function is created if an associated response contains that value.

Documenting Test Case Transaction Timers

It is mandatory in DoxRunner to include at least one Transaction TImer per Test Case, so the Timer Section in all Test Cases and the Test Case Template is mandatory.

Timers are not relevant outside of the Test Cases, so they do not appear anywhere else in the Solution document.

If the script doesn't require a Timer (it may be a part of background load, where measuring response times may not be relevant), a dummy Timer must still be documented.

A Timer can only be added to the table in the Timer Section manually, using standard Microsoft Word, and the guidelines in the following paragraphs.

All Timers for a Test Case reside in the Timer Section.

Getting Started

Items 1 and 2 below are typically only done once, with the occasional review and tweaking if necessary.

Item 3 is where all the action takes place.

1. Test Case Template

When the Test Case Template is downloaded from this site, tailor the Transaction Timer section using the guidelines in the Test Case Template instructions below.

2. When the Solution document is downloaded:

tailor the Configuration Section for:
- the default Timer Long Name template;
- the default Validation template;
review the NFR Section and update it with any NFRs that the business may require.

3. Create the Test Case(s).

For each Test Case:

Assess the Timer section and update it if necessary:
- The Section Title;
- Make sure its bookmark is visible and located immediately before the first character of the Section Title;
- Assess the Description between the Section Title and the Table and update it if necessary;
- Make sure the table has the two mandatory columns (Timer ID and Timer Name), each with the specified heading text;
  - It's best to keep the ideal columns as documented here;
  - If all ideal columns are included, then the section looks better when on a page with landscape orientation;
  - Assess the table to see whether more columns are appropriate (they will be ignored by all DoxRunner operations);
- Manually step through the business process that the Test Case is meant to simulate and verify that the Timers match;
Add Timer rows to the table of the Transaction Timer Section - one Timer per Business Process step.

Do not change the Timer Section's bookmark or its location.

Do not delete the Timer Section.

Test Case Template

Document Test Case Template

Create Test Case

A skeleton Timer Section is present in the Test Case Template that is downloaded from the DoxRunner site. It is mandatory, so should not be deleted.

The illustration below shows it when the Test Case Template is initially downloaded.

There is no need to change it. However, if there are timers that are common to most Test Cases, then those Timers can be added, saving typing when a new Test Case is created. The illustration below shows three Timers are included. They can all be replaced by your own.

Columns can be added at this stage. They will be ignored by the Test Case and Script operations, and non-mandatory columns can be deleted (but not recommended). The mandatory columns are ID and Timer Name.

The Section Title is explained in more detail in the next section.

Test Case Template Section Title

The example in the illustration on the right shows the Section Title

and its three components in a typical Test Case Template.

The Bookmark:

It's mandatory;
Located immediately before the Title Text;
Indicated by the small vertical bar located immediately before the Title Text;
If you cannot see the vertical bookmark bar, it's a good idea to configure Word so that bookmarks are visible;
Do not move it or change it unless it's in the wrong place. DoxRunner depends on it during the Process Raw operation;
Structure: P_Timers;
Length: Cannot be longer than 30 characters.

The Title Text can be manually modified to any text desired.

It's mandatory;
Located immediately after the bookmark and above the Section Description;
Structure: Free-format text;
Length: Cannot be longer than 200 characters;
Word Style: I_Heading n or I_Appendix n, where n can be an integer from 1 to 5.

Note the "<IDx> <Namex>" text at the end of the Title Text. This is optional. It is code for the Process Raw operation to insert the Test Case ID and Test Case Name into the Title Text (refer to the example in the Test Case Section Title below). Sometimes it's useful to know which Test Case the Timers apply to, so it's handy when dealing with many Test Cases.

The triangle following the Title Text does not link to anywhere. It is a placeholder, ready for a link when a Test Case is created. It is useful, but not critical (refer to the example in the Test Case Section Title below). It can be deleted if it annoys you.

Test Case

The Transaction Timer section is the most important section in a Test Case. The illustration below is an example.

Note the ID - all are integers and in ascending order.

Also the Phase - LI comes first and LO comes last.

Document Test Case

Test Case Section Title

The example in the illustration on the right shows the Section

Title and its three components as it may appear in a Test Case.

The Bookmark:

It's mandatory;
Located immediately before the Title Text;
Indicated by the small vertical bar located immediately before the Title Text;
If you cannot see the vertical bookmark bar, it's a good idea to configure Word so that bookmarks are visible;
Do not move it or change it unless it's in the wrong place. DoxRunner depends on it during the Process Raw operation;
Structure: P_CEP001_Timers (where CEP001 is the Test Case ID);
Length: Cannot be longer than 30 characters.

The Title Text can be manually modified to any text desired.

It's mandatory;
Located immediately after the bookmark and above the Section Description;
Structure: Free-format text;
Length: Cannot be longer than 200 characters;
Style: I_Heading n or I_Appendix n, where n can be an integer from 1 to 5.

Note that the Title Text in the example above includes the Test Case ID and the Test Case Name. This is derived from the structure of the Test Case Template as explained in the paragraphs below. It is an optional feature.

The triangle following the Title Text is a link to the top of the Test Case. It is useful for navigating around the Test Case.

It is constructed from the Template's Timer Section Title.

It is useful, but not critical, so it can be deleted if it annoys you.

The Create Test Case operation replaces the text <IDx> from the Test Case Template with the Test Case ID.

The Create Test Case operation replaces the text <Namex> from the Test Case Template with the Test Case Name.

Timer Section

A Timer section is mandatory in all test cases. It is semi-structured, and always appears as the last section in each Test Case and the Test Case Template document.

As with all managed items, Timers are documented within a Microsoft Word section.

Each instance of the Timer section consists of:

a section title;
a bookmark;
a description;
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.

Section Title

Timer Section Description

Timer Table

Timer Table Column Headings

Due to the number of columns in the timer table, the timer section is best on a page that is oriented as landscape. Since it is, typically, the only section requiring the page to be oriented as landscape, for document simplicity it is usually the last section in a Test Case.

An example of a timer section is reproduced in the illustration above and described in following paragraphs.

Timer Section Title

The Section Title is slightly different depending on the document in which it resides, as discussed in the Test Case Template Section Title and Test Case Section Title sections above.

Timer Section Description

When the Test Case is created, DoxRunner uses the Timer Section Description from the Test Case Template.

It's optional;
Location: between the Timer Section Title and the Timer Table;
Structure: free-format text;
Length: Cannot be longer than 1,000 characters;
Style: I_BodyText;
DoxRunner operations do not use this text.

Timer Table

The Timer Table is the heart of Test Case documentation and many DoxRunner operations.

It's mandatory;
Location: immediately below the Timer Section Description (or Timer Section Title if there is no Timer Section Description):
A minimum of two rows:
- A heading row and a data row (one data row per Timer);
Ideally eight columns:
- ID, Notes, Timer Name, Expected Results, Think Time, Response Time NFR, Phase, and Validation;
- More columns can be added;
Do not change the column heading text - DoxRunner operations use them;
All cells must conform to specific rules, as described in the Table Column Headings below.

Timer Table Column Headings

The illustration below shows the relationship between the eight columns of the Timer table and a LoadRunner script as prepared by the Process Raw operation. Note that there is some interaction with the NFRs documented in the NFR section.

Timer ID Column

Refer to xxx in the illustration above.

The Timer ID must be a positive integer (no more than four digits), is mandatory, and is designed to ensure that timers are unique and listed sequentially in the same order as a user of the application would execute the business process. This ensures that they are also listed this way in the analysis report, facilitating the understanding of the test results by the report recipients.

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.

If you leave the Timer ID blank, that Timer will be ignored by DoxRunner operations.

Notes Column

Refer to xxx in the illustration above.

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 a raw 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 to be a supplement to screenshots.

If the cell is insufficient to describe what is required, add a paragraph to the Scripting Notes section of the test case, and provide a link to it in the Notes cell. This is particularly useful if a screenshot is necessary.

Timer Name Column

Refer to xxx in the illustration above.

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 Report, is meaningless. Consider something like "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 for the lr_start_transaction() function.

When recording a script, do not use it - use the Timer ID only, as described in the Recording section.

Expected Results Column

Refer to xxx in the illustration above.

This is optional text describing what is expected when the step is executed in a LoadRunner test. The Process Raw operation includes it in the script as documentation because it is handy when developing the script.

Think Time Column

Refer to xxx in the illustration above.

This column is optional. Any integer entered is interpreted as the number of seconds.

Although Think Time functions are created by VUGen during recording, they are often unrealistic.

By including it in the Transaction Timer table, the scripter has the opportunity to tailor it 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. If the person recording the script paused before pressing the tab, the think time would be unrealistically long. Also if the person recording the script entered an unrealistically brief description, then it would be unrealistically too short.

The Process Raw operation will (optionally) replace all think time functions that LoadRunner may have inserted during recording, with the value from the Timer table, and places them immediately prior to the relevant start transaction timer.

If left blank or if the column was deleted, the Think Time is extracted from the Default Think Time Configuration Item in the Configuration Section by the Process Raw operation. If that does not exist, the Think Time remains as recorded.

Response Time NFR Column

Refer to xxx in the illustration above.

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 an NFR 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 NFR Section and described at length.

Phase Column

Refer to xxx in the illustration above.

Rationale

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.

Valid Contents

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.

Option 1 (recommended)

A file named SessionManagement.c is available to be downloaded from this site. It is recommended to download it and place it into the Included Files folder. It is also recommended to record all scripts the DoxRunner way, where all timers are placed into Action.c.

The SessionManagement.c file contains three C functions, LogIn(), ToIteration(), and Logout().

Each of these three functions contains one of the following lines:

// <Transfer phase LI to here>;

// <Transfer phase TI to here>;

// <Transfer phase LO to here>;

The Process Raw operation automatically moves steps from Action.c into SessionManagement.c based on the Phase as follows:.

The text "// <Transfer phase LI to here>;" in the SessionManagement.c file is replaced by all requests in those Timers with Phase LI.
The text "// <Transfer phase TI to here>;" in the SessionManagement.c file isreplaced by all requests in those Timers with Phase TI.
The text "// <Transfer phase LO to here>;" in the SessionManagement.c file is replaced by all requests in those Timers with Phase LO.
All requests for those Timers with Phase "I" remain in Action.c.

The script will be updated with Error Recovery code where the three functions are called within vuser_init.c and vuser_end.c and Action.c as appropriate.

Option 2

If you don't want to download the SessionManagement.c file or place it into the Included Files folder folder, but still want the functionality described in Option 1 above, create one, two, or three of your own, each with one of the three commented lines described in Option 1 above. Make sure these files have extension ".c".

The Process Raw operation will transfer the relevant requests into the relevant file that you created.

Make sure you place those files into the Included Files folder. and the commented lines reside within one of the three functions LogIn(), ToIteration(), and Logout().

The script will be updated with Error Recovery code.

Option 3

If there are no files containing the three commented lines listed in Option 1 above, the Process Raw operation will simply transfer the relevant requests into vuser_init.c and vuser_end.c.

No Error Recovery code is created.

Validation Column

Refer to xxx in the illustration above.

It allows the scripter to implement one of the three methods for specifying web_reg_find() functions.

It is optional.

If the value specified here exists in the response to any request within that Timer, then the Process Raw operation will prepare and insert a web_reg_find() function at the appropriate place.

Refer to Timer Validation for more details of this method.

Refer also to the following for the other two methods:

Standard VUGen Validation;
Validation Template from the Configuration Section.

Reverse Engineer

The Reverse Engineer operation is designed to update the documentation for a test case from a legacy script.

This operation is not yet operational.

Transaction timer 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.