DoxRunner
​
Getting Started
​​​​
​This page takes you up to your first Test Case. The goal is to be able to prepare a semi-structured Solution document containing at least one Test Case, ready to document the solution's performance testing attributes and apply them to a raw script that is based on that test case, automating many steps that a scripter would need to do.
The procedures documented here use Microsoft Word 2019 and VUGen CE 25.1.
​
If you use other versions, the goal can be achieved, but you may need to vary some steps to suit.
The examples use an organisation called DoxRunner and a solution called Cane View.
​
Prepare PC
​
Prerequisites
You must use a Windows PC suitable for Microsoft Word.
​​
On all PCs that you intend to use for DoxRunner:
-
Ensure Microsoft Word (or Office) is installed;
-
Ensure you have the access to be able to install a Microsoft Word template that contains macros - more on this later;
-
Ensure that you have the ability to execute the macros in a template - more on this later;
​
Although VUGen isn't critical, it would be difficult to develop scripts managed by DoxRunner without it, in which case:
-
Ensure you have local admin access;
-
Ensure VUGen is installed.
​
Folders
​
Manually create four folders for the following:
-
One to hold the solution's support documents;
-
One to hold the scripts;
- One to hold included files;
-
One to hold the DoxRunner application.
​
The name of the path for the first four must be integrated into DocRunner's Configuration CIs section of the Solution document when it is downloaded.
The folder names in the examples below are suggestions only. They can be anything you like, but make sure they are registered into DocRunner's Configuration CIs section of the Solution document.
​
Create other folders as appropriate. The others shown in the examples below are not used by DoxRunner, but are useful.
​
The folder structure can be on a network drive, which is the preferred method for a team.
​
Example folders
It's useful to create one folder for the solution, as shown in the illustration below, where Cane View is the name of the example solution.
​
If you need to manage multiple solutions, then you should create one folder structure for each solution and save a separate Solution document document into each.
Then manually create a support and script sub-folder within the solution folder. The following illustrations are suggestions only.
​
Regardless of where you put xxx and xxx , the folder CIs must be configured to inform DoxRunner of their location. *
​
* you will be able to do this once the solution document is downloaded.
​
The support folder
​
The Support folder contains the DoxRunner documentation, as shown in the illustration below.
​
The Solution document and the Test Case Template should be placed here. It is useful to rename each Solution.docx document to reflect the name of the solution (Cane View Solution.docx in the illustration below). Make sure the support folder contains a Test Case Template.docx file. Do not rename it.
Although the application can be located elsewhere, it can be included in the Support folder. In either case, DoxRunner knows its location only when you integrate it into the Solution document.
​​
Solution document;​
​​
Checked-out test case;
​​
DoxRunner application;
​​
Test Case Template.
​
​ One script is shown here.
More are expected.
​
​​
The script folder
​​
DoxRunner expects all scripts for the solution to be located in the Script folder, as specified in the Script Folder CI in the configuration section. *
​
Folder '_ArchivedScripts' is automatically created within the scripts folder when the Process Raw operation is first initiated.
​​
Once you know what files you want to be included into the scripts, you are expected to place them into a folder specified by the Included Files Folder CI in the configuration section. *
The Process Raw operation copies specific files from Included Files Folder into the script's folder. See next illustration..​​​
​
* you will be able to do this once the solution document is downloaded.
​
The included files folder
​
The included files folder contains all extra files that may be copied into a script by the Process Raw operation.
​
The illustration below shows an example only. It shows four .dat files. Only those referenced by a text data file rule will be copied into the script. For example, if Estimates.dat is not referenced by a text data file rule in CEP001, then it won't be copied into the CEP001 script. It is expected that maybe other scripts reference it, so it will be copied into those scripts as required when the Process Raw operation is applied to them.
​​​
All .c files are integrated into the script as Action files.
​
The SessionManagement.c file is constructed to facilitate error recovery.
It is integrated into the script as an Action file.
​
These four files are copied into the script only when LoadTest Database parameters are needed.
The two .dll files are placed into the script as Extra Files.
The two .c files are integrated into the script as Action files.
​​​​
Register with DoxRunner
​
​
Before downloading the DoxRunner files, please register using this link:​​
Download Documents
​The following four files are to be downloaded and placed into the folders described above:
Test Case Template.docx
Solution.docx
SessionManagement.doc (optional)
DoxRunner.doc
If the instructions below are followed, the DoxRunner.doc file will be renamed to DoxRunner.dotm.
Once downloaded and in their correct place, it is advisable to create a backup before proceeding.
​Download each one by clicking on its respective symbol below.
​​​​
Solution.docx
Click on the Solution.docx icon on the right.
Save it to the support folder that you created earlier under Prerequisites.
​
You may choose to rename it to anything you want, so long as the extension remains .docx.
​
Use the solution name is suggested.​​​
​
Archive a copy of the original. Where you put it is not important, however the Archive folder shown in the above illustration is suggested.
​​​
Solution.docx
Test Case Template.docx
​
Click on the Test Case Template.docx icon on the right.
Save it to the Support folder that you created earlier under Prerequisites.
Do not rename it.​
​
Archive a copy of the original template. Where you put it is not important, however the Archive folder shown in the above illustration is suggested.
Test Case Template.docx
​
DoxRunner.dotm
Click on the DoxRunner.doc icon on the right.
Save it into the folder you reserved for the application under Prerequisites.
​​
Rename it to DoxRunner.dotm.
​​​
DoxRunner.doc
​
​
​
​
​
​
​
Download and rename to:
DoxRunner.dotm
SessionManagement.c
Only download this file if you want to use the error recovery facility of DoxRunner.
Click on the SessionManagement.doc icon on the right.
Save it into the folder you reserved for included files.
​​
Rename it to SessionManagement.c.
​​
It contains three C functions: Login(), ToIteration(), and LogOut().
​
Each function contains one of these three templates that are used in the error recovery process. The LI, TI, and LO letters refer to the values you place in the Phase column of the Transaction Timers table of all test cases:
// <Transfer phase LI to here>;
// <Transfer phase TI to here>;
// <Transfer phase LO to here>;
​
Navigate to the file, open it, and update it if necessary (make sure you understand the error recovery process).
​
The three function names should not change, nor should the template text. Everything else can change.
​​​
SessionManagement.doc
​
​
​
​
​
​
​
​​
Activate DoxRunner
​
After you have downloaded and renamed DoxRunner.dotm, you need to activate it.
​
Open it.
​
It will appear empty.
​
Even though it appears to be empty, initiate Save As and choose the folder that you created for the application.
Select Word Macro-Enabled Template as shown in the illustration below.
​
The extension must remain as .dotm.
​
Close it.
Integrate DoxRunner
​
DoxRunner's Test Case and Script operations rely heavily on a series of complex Microsoft Word VB macros contained in DoxRunner.dotm, that you should have downloaded onto your PC earlier. They treat the VUgen script files as Microsoft Word documents, even though they are simple text files. By approaching it this way the extensive functionality built into Word can be used to manipulate them.
​
It is assumed that you have downloaded the Solution document into the Support folder and DoxRunner.dotm. into either the Support folder or its own application folder.
​​
This section explains how to activate DoxRunner.dotm into the Solution document.
​​
​Activating DoxRunner involves four major steps when the Solution document is open:
-
Configure the Developer tab;
-
Configure security;
-
Attach the macro template to Word;
-
Add an icon to the Quick Access Toolbar.
Make sure you save the Solution document when finished.
​​​​
Developer tab​​
​
The Developer's tab is required to instrument your instance of Microsoft Word for DoxRunner.
​
It is one of the ribbon tabs. If it's already visible, ignore this.
​
The illustration below shows how it is done, however you must open word options first.
​​​
Press Customize Ribbon​
​​
Select Main Tabs in both
​​
Select Developer
​​
Press Add
​​​
The Developer tab is opened
​​
Press OK
Security
Because macros can be a security risk, they will most likely be disabled. You will need to enable them.
From the Developer tab, select Macro Security.
​​
Until the macro is signed, you will need to enable all macros, then press OK.
Select the Developer tab
​​​
Select Macro Security
​​​
Select Macro Settings
​​​
Select 'Enable all macros...'
​​​
Select 'Trust...'
Attach the Word template
The DoxRunner VB macro DoxRunner.dotm must be attached to the Solution document for DoxRunner operations to work.
Remember where you downloaded the DoxRunner.dotm file.
The below instructions show how to attach it to the Solution document.
​
​
Open the Solution document and select the Developer tab;
​
Press the Document Template icon;
Press the Attach button;
Navigate to the DoxRunner.dotm file;
Select it;
​
Open it;
​
Press the Add button;
​
Again, navigate to DoxRunner.dotm;
​
Press OK;
​
Make sure its checkbox is selected;
Press the OK button again.
​
The DoxRunner macro will now be attached to the Solution document, and can be executed if you have configured security correctly.
​
Repeat this for each Solution document you need.
​
Execution of DoxRunner's Test Case and Script operations is facilitated by the Quick Access Toolbar as described below.
​​
Create a Quick Access Toolbar icon
​​
To make it easier to initiate DoxRunner's Test Case and Script operations, add an icon to the quick access toolbar.
The illustrations below show how it is done, however you must open word options first.
Select the Quick Access Toolbar;
​
Select Macros;
​​
Scroll down;
​
Select:
TemplateProject.ProcessLR.ProcessLR;
Press Add;
The macro name will appear on the right.
​
Select it;
Press Modify;
A selection of icons is displayed.
Choose any icon;
Press OK.
The icon is assigned to the macro;
​
Press OK;
The icon appears on the Quick Access toolbar.
​
Make sure you save the document.
​
Test it by pressing the icon.
​
If you haven't created any test cases yet, the following form should display with the warning that there are no test cases.
You are now almost ready to use it to create your first test case.
But not yet. You should press the Cancel button, then save the Solution document to lock the changes in.
Then review the Solution document.
​​​​​​
Review the Test Case Template
The Test Case Template is designed to save time when creating test cases.
Once it is downloaded into the Support folder, follow the More details link for advice on those elements that should be reviewed and updated.
Some elements may not be appropriate for your solution, and not all elements need be updated immediately - many items can be updated as as you gain experience in how the application works and how test cases look once created.
​
​​​