DoxRunner
Macquarie University Student Accommodation
Overview
A section is one of the building blocks of the documents described in this site. Although the focus of this page will be on the sections in the test cases, the Solution document contains a similar set of sections, plus some important extras. The Test Case Template contains empty versions of the test case sections.
​
Description
​
DoxRunner operations need to be able to navigate the Solution document and the test cases it contains. To do that reliably the sections are semi-structured.
They consist of a bookmark, a title, body text, and, often, a table. The paragraphs below describe these components in detail.
Bookmark
​
The bookmark is the principal mechanism for DoxRunner operations to navigate to any section since it provides more certainty than mere text alone. Using bookmarks also allows the person documenting to have some freedom with the text. All bookmarks conform to Microsoft Word rules and are placed immediately in front of the section's heading.
Despite the benefit of bookmarks, there are some drawbacks. Manually editing a section, especially copying and pasting, may relocate its bookmark, causing DoxRunner operations to read the document incorrectly. Refer to the instructions here to visualize bookmarks, essential to making sure the bookmarks are in their correct location.
​
All Solution document section bookmarks, start with V_ which is followed by the section name.
Example: V_TextDataFiles
All Test Case section bookmarks start with P_ which is followed by the Test Case ID then followed by the section name.
Example: P_TSK005_TextDataFiles (where TSK005 is the Test Case ID)
​
Section Title
​
The section title can be any text, but the Microsoft Word style should begin with I_Heading n or I_Appendix n. where n is an integer from 1 to 5. It is immediately preceded by the bookmark.
Body Text
​
Each body text can be any text up to 1,000 characters. The Microsoft Word style should be I_BodyText.
Table
​
Most managed sections have a table that contains the actual rules. These tables have mandatory columns and may have ideal columns and/or user-defined columns.
​
Mandatory Columns
​
The mandatory columns have column heading text that must conform to the rules of the specific section. Refer to the specific section for more details.
​
Ideal Columns
​
Ideal columns are optional and also have column heading text that must conform to the rules of the specific section. Refer to the specific section for more details. Most ideal columns have heading text "Description" and contain a description of the rule in each row.
​
User Defined Columns
​
The scripter can add additional columns if they add value to the documentation. These columns are ignored by all DoxRunner operations.
Adding a section
All sections in the Solution document and the Test Case Template must be manually added.
​
Sections in a test case an be added manually also, but the best way is to use the DoxRunner Add Section operation.
Deleting a section
All sections in the Solution document and the Test Case Template must be manually deleted.
​
Sections in a test case an be added manually also, but the best way is to use the DoxRunner Delete Section operation.
Section operations
​
Despite the benefit of bookmarks, there are some drawbacks. Manually editing a section, especially copying and pasting, may relocate its bookmark, causing DoxRunner operations to read the document incorrectly.
Refer to the instructions here to visualize bookmarks, essential to making sure the bookmarks are in their correct location.
​
Described below are two methods of adding a section and two methods of deleting a section.
Using the DoxRunner operation is applicable only to the sections in a test case, and only those recognized by DoxRunner.
Sections in the Solution document and the Test Case Template must be managed manually.
How to add a test case section
A section in a test case can be added manually, but it's best to use DoxRunner. Follow the instructions below.
The DoxRunner operation takes the section's format from the Test Case Template and the CIs from the Configuration section (which may be only in the Solution document). If the Test Case Template doesn't contain the required section, a default structure is used.
Press the icon on the Quick Access toolbar that initiates the DoxRunner operations.
The DoxRunner application will load and display the current set of test cases from the Test Case Summary section.
Choose the test case(s) that you want to add the section(s) to.
Press the Test Case Operations button.
​
​
​
The dialog box illustrated on the right will display.
​
Select Manage Sections.
​
​
The dialog box extends to show the list of sections as shown in the bottom of the illustration on the right.
​
Select the sections you want to add.
​
Note that the word Add is displayed next to those you select. This is feedback indicating that it doesn't yet exist and you can only add it. If it said Delete then it will already be there and there is no need to add it.
​
Checking out the test case into a separate document beforehand is a form of backup in case something goes wrong.
Press Apply to initiate the operation.
The selected section(s) are inserted into the test case and a confirmation is displayed as illustrated on the right.
​
Press OK.
At this point the Solution document is not saved.
Review the result in the test case within the Solution document, including the Test Case Summary section, to make sure it's what you want before continuing. You may need to manually tailor its format and/or its location.
​
When satisfied, save the Solution document.
​
If not OK, investigate the reason, close the Solution document without saving, and try again. In particular check existing bookmarks and Word styles.
How to delete a test case section
A test case section in a test case can be deleted manually, or deleted using the DoxRunner Delete Section operation, as described in the steps below.
​
Press the icon on the Quick Access toolbar that initiates the DoxRunner operations.
DoxRunner will load and display the current set of test cases that are listed in the Test Case Summary section
Choose the test case that you want to delete the section from (if you choose multiple test cases, only the first one will be updated).
Press the Test Case Operations button.
​
The dialog box illustrated on the right will display.
​
Select Manage Sections.
​
​
The dialog box extends to show the list of sections as shown in the bottom of the the illustration on the right.
​
Select all of the sections you want to delete. The illustration on the right shows the Configuration section was the only one selected.
Note that the word Delete is displayed next to it. This is feedback indicating that it exists and you can delete it. If it said Add then it won't be there and continuing will add it instead.
​
Checking out the test case into a separate document beforehand is a form of backup in case something goes wrong.
Press Apply to initiate the process.
The selected sections are deleted from the test case and a confirmation is displayed.
Press OK.
At this point the Solution document is not saved.
Review the result in the Solution document (including the Test Case Summary section) to make sure it's what you want before continuing. Check to ensure that the bookmark is deleted too, and that the sections on either side are formatted OK, including the page orientation.
​
When satisfied, save the Solution document.
​
If not OK, investigate the reason, close the Solution document without saving, and try again. In particular check existing bookmarks and Word styles.
​
How to add a section manually
​
Although the DoxRunner Add Section operation automates the addition of a managed section in a test case, sections in the following two documents can only be added manually:
-
The Test Case Template;
-
The Solution document (outside of any test case).
​
The example illustrated in the steps below shows how a new Date / Time Parameter section is added manually.
First identify where you want the new section to be inserted and open up a new line.
Opening a new line may affect the location of the bookmark associated with the following section.
Restore the bookmark of the following section if necessary.
Type in the heading and make sure it's style is a recognized heading style.
It's important that an appropriately formatted bookmark is added in front of the heading text.
​
Most sections have a link at the end of the heading text for ease of navigation.
​
Type in any appropriate text (optional). Make sure its style is I_Body_Text.
Create a new table below the text. Make sure it has the correct number of columns and at least two rows. Make sure the cells all have the correct style (I_Table Text).
​
Populate the table's heading cells as appropriate, making sure the style is I_Table Heading.
​
Adjust the widths of the columns as appropriate, and delete any extra blank lines in accordance with your organisation's style.
​
Add rows and populate their cells as appropriate.
​
Don't forget to save.
​
How to delete a section manually
​
Although the DoxRunner Delete Section operation automates the deletion of a managed section in a test case, any section will need to be deleted manually in the following two documents:
-
The Test Case Template;
-
The Solution document (outside of any test case).
​
The example below shows how a LoadTest Database section can be deleted manually.
First select the section.
Then press the Delete key.
But it's not over yet.
The bookmark will remain. You must explicitly delete that too.
Don't forget to save.
​