DoxRunner
​
Documentation
Word sections
​​​
DoxRunner only recognizes three documents:
​
-
Test Case (embedded in the Solution document or as a separate document when checked-out);
​
All are semi-structured because they must balance the need to document performance tests flexibly, and to take advantage of the ability of DoxRunner to use the documentation to manipulate LoadRunner scripts.​
​​​​
Microsoft Word is used for all documentation. LoadRunner contains many text files, and these are viewed as Word documents when they are being manipulated by DoxRunner's Script operations.
​
Some configuration of Word is required.
​
​
Solution Document
This is the document you will spend most of your time in.
​​
A solution (or any group of test cases) is represented by a single document - the Solution document (sometimes referred to as the support document). It contains one or more test cases, plus overall information about the performance test solution that isn't contained in any test case, including business requirements, scripting notes, tips and gotchas, etc.
​
The test cases may represent a solution, or simply a group of test cases that are logically related, or even just one test case.
It is similar to a handover document, but it is more enduring, designed to span multiple projects.
​
An organisation may have one or more solutions depending on the application(s) being tested.
It must reside in the folder defined in DoxRunner's Configuration CIs section as CI support folder.
Each solution should reside in its own folder for ease of administration.
​​​
​
Test Case Document
Test cases are normally contained within a Solution document.
​
Although a Test Case would normally be updated when it's in the Solution document, it can be checked-out into its own separate document and checked back in if updated by an external or off-shore party. In this case it is assumed that the team leader has responsibility for the entire solution document.
​
DoxRunner regards a test case as representing one script.
​​
​
Test Case Template
The Test Case Template, as the name suggests, is a skeleton document that is used when creating a new Test Case, an operation that can be found under the Test Case Operations menu.
​
It allows you to tailor how a new Test Case looks when it is initially created.
​
It must reside in the same folder as the Solution document, which is in turn defined in DoxRunner's Configuration CIs section as CI Support folder.
​​​
​
Microsoft Word styles
​​
All Microsoft Word styles used on all of the documents referred to in this site begin with I_. For consistency you should only use these styles because some of DoxRunner's Test Case operations use them. If you need to conform to your organization's styles, modify the styles below to suit. Try not to use styles with names that don't start with I_.
​
Examples:
-
I_Heading n (instead of Heading n);
-
I_BodyText (instead of Normal);
-
I_TableHeading (for the first row in a table);
-
I_TableText (for all data rows in a table);
-
I_Appendix n (where n is an integer from 1 to 5);
-
I_Caption for table and figure captions.
​
Configure Microsoft Word
​​
Some configuration of Microsoft Word is needed to take full advantage of DoxRunner's Test Case and Script operations.
​
Microsoft Word 2019 was used to develop the scripting and documentation defined here. Microsoft 365 work well too, with only minor changes.
You may need to seek help if other versions are used.
It is assumed that you have installed Microsoft Word and are reasonably familiar with the product.
​
Word Options
​​
Word Options are required for several steps relating to the configuration options that follow.
​
The screenshot below shows how it is done.
​
​​ Press the File tab;
​​
Select Options;
​​
The Options form opens.
​
​
Bookmarks
​
DoxRunner operations rely heavily on bookmarks. For example there is one bookmark per DoxRunner section. It uses them to navigate and manipulate the documents while giving the documenter the freedom to present the solution and its test cases to third parties clearly.
If any bookmark is deleted or moved to an inappropriate location, a DoxRunner operation may be compromised. Therefore it's useful to make the presence of bookmarks visible.
​​
If you find that there is a misplaced bookmark, place the cursor at the location where the bookmark should go, list the bookmarks as per the instructions below, identify the misplaced one, and select it.
​​​​​​
Accessing Bookmarks
​
Access the bookmarks by pressing the Insert tab and then the Bookmark link as shown in the illustration below. If the Bookmark link isn't displayed, the page may have been narrowed, in which case a Links drop-down will be visible instead. A Bookmark icon can be found once that is opened.
If the document is open and covers the full screen:
​
Press the Insert tab;
​
Press the Bookmark link.​
If the document is open but doesn't cover the full screen:
​
Press the Insert tab;
​
Press the Links drop-down - the three link types display;
​
Press Bookmark.​
As shown in the illustration below, you may get a list of hidden bookmarks, which, in the context of this site, is not useful.
To see the useful bookmarks, un-select the Hidden bookmarks checkbox.​
Unselect hidden bookmarks.
​
​
Making bookmarks visible​
​
Because bookmarks are so important to DoxRunner operations, it is useful to make them visible.
The illustration below shows how it is done, however you must open word options first.
​​​
Press Advanced;
​
​ Scroll down;
​​
​ Select 'Show bookmarks'.
​
Show formatting symbols​​
​​
This is not essential to any DoxRunner operation, and can be annoying for first time users, but it is very handy when the optional format of a Microsoft Word page is difficult to achieve.
In particular, 'Next Page' section breaks, where portrait and landscape layouts are mixed, may be difficult to format properly if you cannot see the formatting symbols.
​​
The illustration below shows how it is done, however you must open word options first.
​
Be sure to make them invisible when releasing the document to external users.
​
​
Word sections vs DoxRunner sections
​​​​
​A major component of the DoxRunner documents is sections. The definition of these sections is different to that used by Microsoft Word. A test case typically consists of many DoxRunner sections, but only two Microsoft Word sections.
​​
​
Microsoft Word Sections
​
Microsoft Word sections are delineated by a special artifact called a 'section break'. Two types are shown below.
The 'Continuous' section break (above) delineates two Microsoft Word sections on the same document page.
DoxRunner ignores this type of section break.
​​​
​
As you may guess. the 'Next Page' section break (above) places the two Microsoft Word sections onto separate pages.
DoxRunner makes extensive use of this one. It is used to separate one test case from the next, so that all test cases start on a new page.
​
It is also used to separate a test case into two parts. The pages iin the first part are usually oriented as portrait. The second part is oriented as landscape. The Transaction Timers section occupies the second, landscape page(s). The portrait pages and the landscape page(s) are separated by a 'Next Page' section break. That is, each test case is divided into two Word sections by default.
Section breaks are not normally visible, but there are benefits to make them so while you are developing the document. Make sure you make them invisible before releasing the document. To make them visible, refer to Configure Word below.
​​​​
Example of Word sections
​
​The example below shows the structure of the DoxRunner sections in a test case, and the use of 'next page' section breaks (circled in red), separating Microsoft Word sections.
​
It looks more complicated than it is. It is worth studying and understanding.
​
It has 5 major components:
​
The end of one test case;
​​
​ The first page of the next test case;
​​
The second page of that test case;
​​
The last page of that test case;
​​
The first page of the following test case.
​
More details:
​
Three 'Next Page' section breaks.
The first one and the third one separates the test cases.
The second one ensures that the Transaction Timers section is oriented as landscape.
​
The end of the first test case, the start and end of the next test case, and the start of the third test case.
​
The transaction timers section is the last section of any test case, and is oriented as landscape.
Only the use of 'next page' section breaks can achieve this format.
​​​
DoxRunner Sections
​​
​A DoxRunner section is one of the building blocks of the documents described in this site.
They have a specific structure that balances the need for the DoxRunner to use them and the need for humans to read and understand them.
​​
For example, all test data file rules for a test case are placed into one section devoted to those rules for that test case. Since those rules are presented in one place, they can be managed by the scripter and understood by other team members. DoxRunner can also read the section and apply the text data file rules to a raw script automatically.
​​​​​
​ Column headings
Data rows​
They are used in both the solution document and all test cases.
​
Most have an embedded table, listing the rules that apply to that section, while some don't have a table.
​
Those that don't have a table are usually descriptive only and, if relevant to DoxRunner, are used to insert comments into a script.
​
Most sections that do have a table contain Managed Items. Most Managed Items apply only to the test case that they are embedded in.
However, some apply to multiple test cases. Below is a description on how best to handle those Managed Items that span multiple test cases.​
Managed items that span multiple test cases
​
​In order to reduce the amount of typing, sections that deal with managed items can appear at the solution document level as well as each test case.
​​
The following example uses the managed item devoted to additional attributes, one of the runtime attributes of a script.
​
The URL used in a load test will most likely be the same across all, or most, scripts. It is good practice to place this URL into the additional attributes part of the runtime settings. This is so that, if the environment changes, the URL can be changed in the scenario without the need to edit any scripts.
​
When downloaded from this site the test case template includes an additional attribute section. Hence, unless the documenter has deleted it, all test cases will include that additional attributes section.
​
When downloaded from this site the solution document also includes an additional attribute section.
​
The documenter has a choice - create an additional attribute rule in all test cases, or just once in the solution document instance. The concept can be applied to all managed items, simplifying the document and saving typing.
​
Another example is test accounts. Include them as text data files in the solution document version of the text data file section rather than in all test cases.
​
The may be instances where the documenter has included a managed item at the solution document level, but one or two test cases require a different version of the item. The different version can be documented in the managed item section of the test case.
In this case, DoxRunner will apply the test case version, not the one at the solution document level.
​​​​​
DoxRunner section structure
​​
In the context of this site, a DoxRunner section consists of:
-
A bookmark;
-
Section title (using a style starting with "I_Heading_..." or "I_Appendix_...");
-
Body text (using style I_BodyText);
-
Often one table:
-
Table heading (using style (I_TableHeading);
-
Data rows (using style I_TableText);
-
Table caption (using style "I_Caption") is optional.
-
Refer also to Microsoft Word styles above and the illustration below.
​
The bookmark is only present if the section is critical to DoxRunner's Test Case and Script operations.
​
Section bookmark
​
All section bookmarks conform to Microsoft Word rules. They are located immediately in front of the section's title as shown in the illustration above. You must make bookmarks visible first to see it. Making bookmarks visible allows you to see whether the section's bookmark is in the correct place. DoxRunner depends on it's location.
​
There are three types of bookmark:​
-
Those specific to the solution document. They start with V_ (eg. V_Configuration);
-
Those specific to the test case template. They start with P_ (eg. P_Headers);
-
Those specific to a test case. They start with P_ followed by the test case id (eg. P_GOU546_Timers).​
​
Section title
​​
The title of any section is free-form text up to 200 characters, but the Microsoft Word style should begin with I_Appendix_ followed by an integer from 1 to 5 (eg. I_Appendix_3), or I_Heading_ followed by an integer from 1 to 5 (eg. I_Heading_2). It must be immediately preceded by the bookmark discussed above. Refer also to the illustration above.
The triangle at the end of the title is optional. Where appropriate, the triangle contains a link to the Test Case Summary section to facilitate navigation.
Section title triangle
​​
The triangle at the end of the title is optional. It is used for easy navigation around the document.
Within a test case, it links to the top of the test case. ​The triangle at the top of each test case links to the Test Case Summary section.
​
Section description
​
The section description is located immediately after the section title (and before the table if one exists). It can be any text up to 1,000 characters. The Microsoft Word style should be I_BodyText. There should not be any heading styles between the section description and the table.
Section table
​
Some managed sections don't have a table, but most do.
Column headings
​
The first row is always the column headings.
​
Some columns are mandatory and some are not mandatory, but are still useful.
Other columns can be added. The column headings of the mandatory and useful columns are important, so make sure you conform.
​
The Word style for all cells in the data rows is I_TableHeading. ​This is necessary for reliable navigation by DoxRunner operations.
Data rows
​
The data rows simply contain the rules - one row per rule.
The Word style for all cells in the data rows is I_TableText. ​This is necessary for reliable navigation by DoxRunner operations.