Testing QuickDoc providers

You can test your QuickDoc providers by creating a test class that derives from QuickDocTestBase. This class derives from BaseTestWithTextControl, and will open a text file into an in-memory text control and place the text caret at the location indicated by the {caret} placeholder. It then uses the QuickDocManager class to ensure that at least one provider can generate documentation, and then generates the HTML and compares it to the expected value in the gold file for the test.

Invoking the test

The test can be invoked by calling DoNamedTest2() which will load a source file based on the name of the test method (minus any "Test" prefix or suffix, DoNamedTest will use the given name). Alternatively, the test can call DoOneTest() and explicitly pass the name of the file in.

In both cases, the file extension is added by the base class, which can be declaratively set by applying the TestFileExtensionAttribute to the test class, or by overriding the Extension property.

The test class should override the RelativeTestDataPath property to supply the location of the source and gold files.

Example

As an example, this test class will test the C# QuickDoc provider for XML Doc Comments defined in the source file. The two methods show both ways of invoking the test, using the same file as input.

test\src\QuickDoc\CSharpQuickDocTest.cs:

[TestFileExtension(CSharpProjectFileType.CS_EXTENSION)]
public class CSharpQuickDocTest : QuickDocTestBase
{
  protected override string RelativeTestDataPath
  {
    get { return @"QuickDoc\CSharp"; }
  }

  [Test]
  public void TestQuickDoc01()
  {
    DoNamedTest2();
  }

  [Test]
  public void TestSimpleCSharpDocComments()
  {
    DoOneTest("QuickDoc01");
  }
}

test\data\QuickDoc\CSharp\QuickDoc01.cs

Note the {caret} marker. This is used by the test's base class to position the text caret in the in-memory text control, ensuring the QuickDoc is for the class Foo.

/// <summary>Bar!</summary>
public class Fo{caret}o
{
}

test\data\QuickDoc\CSharp\QuickDoc01.cs.gold

This file is a dump of the HTML that is generated by the QuickDoc presenter. Even though the content of this file is HTML, the name still includes the .cs file extension - it is the gold file for the QuickDoc01.cs input file.

When the test is run, the QuickDoc is generated for the text caret position, and the generated HTML is compared against this file. If they differ, the test fails. If they're the same, the test passes.

<html>
  <head>
    <META http-equiv="Content-Type" content="text/html; charset=utf-8">
    <style type="text/css">
       body,tbody {font: normal 8pt verdana,arial,helvetica; color: InfoText; background-color: InfoBackground; margin: 0px; padding: 0px; overflow-y: expression(document.body.scrollHeight > document.body.clientHeight ? 'scroll' : 'hidden'); }
       h1 {margin: 5px 0px 0px 0px; font: bold 9pt verdana,arial,helvetica;}
       table.list {margin: 5px 0 5px 0}
       table.list tr th {font-size: 8pt; font-weight: bold;}
       table.list tr {font-size: 8pt; text-align: left;}
       td.pdef {white-space: nowrap; vertical-align: top;}
       pre.outline {margin: 5px 0 5px 0;}
       dl.headers {font-size: 10pt; margin: 5px 0 10px 0;}
       dl.headers dt {float:left;}
       dl.headers dd {padding-left: 50px;}
       dl.headers dt em {display:block; font:100% normal; padding-left: 15px;}
       br {clear:left;}
       a,a:visited{color:#06c;}
       a.ext,a.ext:visited{color:gray;}
    </style>
    <script language="JavaScript">function fixScrollBars(){document.body.style.overflowY = document.body.scrollHeight > document.body.clientHeight ? 'scroll' : 'hidden';}function showHide(elementid){if (document.getElementById(elementid).style.display == 'none'){document.getElementById(elementid).style.display = '';document.getElementById(elementid+"img").src='InlineCollapsPathJS';window.external.Expanded()} else {document.getElementById(elementid).style.display = 'none';document.getElementById(elementid+'img').src='InlineExpandPathJS';}; fixScrollBars();}function showAttributes(){var elements = document.getElementsByTagName('a');for (var i=0; i < elements.length; i++) {  var element = elements[i];  if (element.id == 'attrregion')    { element.style.display = 'none';  }};var elements = document.getElementsByTagName('div');for (var i=0; i < elements.length; i++) {  var element = elements[i];  if (element.id == 'attrdef')    { element.style.display = 'inline';  }};window.external.Expanded();fixScrollBars();}function handleClick(oEvent, oTarget) {if (oEvent.ctrlKey) {window.external.NavigateCtrl(oTarget); }else {window.external.Navigate(oTarget); }}</script>
    <div style="float:right" align="right"><a href="about:goto">go to</a></div>
  </head>
  <body>
    <dl class="headers"><dt>public class <b> Foo</b></dt><dd>&nbsp;</dd><dt></dt></dl><br /><h1>Summary:</h1>Bar!
  </body>
</html>

Last modified: 04 July 2023