Merge branch 'maintenance/SqlTopicRepository-Load-tests' into develop

It's not practical to unit test the `SqlTopicRepository` currently without first investing into more sophisticated testing infrastructure in order to e.g. mock the all of the complex objects that are involved, such as `SqlConnection`, `SqlCommand`, `SqlDataReader`, &c.

That said, much of the complex logic is part of the `Load()` method, and that is largely handled by a series of `SqlDataReader` extensions. It's still difficult to test a `SqlDataReader`, since it doesn't have a public constructor and can only be created by a `SqlCommand`. But the `SqlDataReader` implements the `IDataReader` interface, which is shared by the `DataTableReader` class. As such, we generalize (most of*) the extension methods to work against `IDataReader`, and use that to test the extension methods against `DataTable` instances which mimic the data we'd expect to get back from an actual SQL query.

To support this, we've created a series of `DataTable` derivatives which map to each of the SQL tables we wish to create a stub for. These include e.g. `TopicsDataTable`, `AttributesDataTable`, `RelationshipsDataTable`, &c. Each one not only defines the schema for each column, but also includes a strongly typed `AddRow()` method to simplify adding records.

Using this, we're able to successfully write unit tests to evaluate (most of*) the extension methods. This allows us to confirm not only that topics, attributes, relationships, and references can be created, but also more nuanced behavior such as `referenceTopic` (for identifying relationships within the existing topic graph) and the new `IsFullyLoaded` tracking (for determining if any relationships failed to be identified).

**Note:** Most of the extension methods are actually private. As a result, we test them indirectly by passing the tables to the main `LoadTopicGraph()` extension method, which composites the calls to the private extensions. If empty data tables are passed to it, it skips calls for the associated record set, thus keeping the unit tests focused on the relevant methods. The `LoadTopicGraph()` extension method itself is still `internal`, but the internals of `SqlTopicRepository` are exposed to the `OnTopic.Tests` project.

* The `SetExtendedAttributes()` extension method is not able to be correctly tested since it relies upon the `GetSqlXml()` method, which is specific to the `SqlDataReader`, and thus cannot be mimicked with a `DataTableReader`. All other extensions methods are evaluated.

Author: JeremyCaney

OnTopic.Data.Sql/Properties/AssemblyInfo.cs

@@ -4,6 +4,7 @@
 | Project       Topics Library
 \=============================================================================================================================*/
 using System;
+using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
 /*==============================================================================================================================
@@ -13,4 +14,5 @@
 \-----------------------------------------------------------------------------------------------------------------------------*/
 [assembly: ComVisible(false)]
 [assembly: CLSCompliant(true)]
+[assembly: InternalsVisibleTo("OnTopic.Tests")]
 [assembly: Guid("1de1f923-c7c2-435b-b49a-975acbcb5ff0")]

OnTopic.Data.Sql/SqlDataReaderExtensions.cs

@@ -5,6 +5,7 @@
 \=============================================================================================================================*/
 using System;
 using System.Collections.Generic;
+using System.Data;
 using System.Diagnostics;
 using System.Linq;
 using System.Net;
@@ -19,7 +20,7 @@ namespace OnTopic.Data.Sql {
   | CLASS: SQL DATA READER EXTENSIONS
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Extension methods for the <see cref="SqlDataReader"/> class.
+  ///   Extension methods for the <see cref="IDataReader"/> class.
   /// </summary>
   /// <remarks>
   ///   Most of the extensions are optimized for reading the data returned from the <c>GetTopics</c> and <c>GetTopicVersion</c>
@@ -36,10 +37,10 @@ internal static class SqlDataReaderExtensions {
     | METHOD: LOAD TOPIC GRAPH
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Given a <see cref="SqlDataReader"/> from a call to the <c>GetTopics</c> stored procedure, will extract a list of
+    ///   Given a <see cref="IDataReader"/> from a call to the <c>GetTopics</c> stored procedure, will extract a list of
     ///   topics and populate their attributes, relationships, and children.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
     /// <param name="referenceTopic">
     ///   When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic references
     ///   and relationships, including <see cref="Topic.Parent"/>, are integrated with existing entities.
@@ -56,7 +57,7 @@ internal static class SqlDataReaderExtensions {
     ///   thus external references aren't likely to be available.
     /// </param>
     internal static Topic LoadTopicGraph(
-      this SqlDataReader reader,
+      this IDataReader reader,
       Topic? referenceTopic = null,
       bool? markDirty = null,
       bool includeExternalReferences = true
@@ -65,6 +66,7 @@ internal static Topic LoadTopicGraph(
       /*----------------------------------------------------------------------------------------------------------------------
       | Establish topic index
       \---------------------------------------------------------------------------------------------------------------------*/
+      var sqlDataReader         = reader as SqlDataReader;
       var topics                = referenceTopic is not null? referenceTopic.GetRootTopic().GetTopicIndex() : new();
       var rootTopicId           = -1;
 
@@ -101,7 +103,9 @@ internal static Topic LoadTopicGraph(
 
       // Loop through each extended attribute record associated with a specific topic
       while (reader.Read()) {
-        reader.SetExtendedAttributes(topics, markDirty);
+        if (sqlDataReader is not null) {
+          sqlDataReader.SetExtendedAttributes(topics, markDirty);
+        }
       }
 
       /*----------------------------------------------------------------------------------------------------------------------
@@ -162,15 +166,15 @@ internal static Topic LoadTopicGraph(
     ///   Given the primary topic attributes from the <c>TopicIndex</c> view, establishes a barebones <see cref="Topic"/>
     ///   instance and adds it to the <paramref name="topics"/> collection.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
     /// <param name="topics">A <see cref="Dictionary{Int32, Topic}"/> of topics to be loaded.</param>
     /// <param name="markDirty">
     ///   Specified whether the target collection value should be marked as dirty, assuming the value changes. By default, it
     ///   will be marked dirty if the value is new or has changed from a previous value. By setting this parameter, that
     ///   behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update
     ///   from being persisted to the data store on <see cref="Repositories.ITopicRepository.Save(Topic, Boolean)"/>.
     /// </param>
-    private static void AddTopic(this SqlDataReader reader, TopicIndex topics, bool? markDirty) {
+    private static void AddTopic(this IDataReader reader, TopicIndex topics, bool? markDirty) {
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Identify attributes
@@ -217,15 +221,15 @@ private static void AddTopic(this SqlDataReader reader, TopicIndex topics, bool?
     ///   Given an attribute record from the <c>AttributeIndex</c> view, finds the associated <see cref="Topic"/> in the
     ///   <paramref name="topics"/> collection, and sets the corresponding <see cref="Topic.Attributes"/> value.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
     /// <param name="topics">A <see cref="Dictionary{Int32, Topic}"/> of topics to be loaded.</param>
     /// <param name="markDirty">
     ///   Specified whether the target collection value should be marked as dirty, assuming the value changes. By default, it
     ///   will be marked dirty if the value is new or has changed from a previous value. By setting this parameter, that
     ///   behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update
     ///   from being persisted to the data store on <see cref="Repositories.ITopicRepository.Save(Topic, Boolean)"/>.
     /// </param>
-    private static void SetIndexedAttributes(this SqlDataReader reader, TopicIndex topics, bool? markDirty) {
+    private static void SetIndexedAttributes(this IDataReader reader, TopicIndex topics, bool? markDirty) {
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Identify attributes
@@ -335,15 +339,15 @@ private static void SetExtendedAttributes(this SqlDataReader reader, TopicIndex
     ///   Topics can be cross-referenced with each other via a many-to-many relationships. Once the topics are populated in
     ///   memory, loop through the data to create these associations.
     /// </remarks>
-    /// <param name="reader">The <see cref="SqlDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
     /// <param name="topics">A <see cref="Dictionary{Int32, Topic}"/> of topics to be loaded.</param>
     /// <param name="markDirty">
     ///   Specified whether the target collection value should be marked as dirty, assuming the value changes. By default, it
     ///   will be marked dirty if the value is new or has changed from a previous value. By setting this parameter, that
     ///   behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update
     ///   from being persisted to the data store on <see cref="Repositories.ITopicRepository.Save(Topic, Boolean)"/>.
     /// </param>
-    private static void SetRelationships(this SqlDataReader reader, TopicIndex topics, bool? isDirty = false) {
+    private static void SetRelationships(this IDataReader reader, TopicIndex topics, bool? isDirty = false) {
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Identify attributes
@@ -392,15 +396,15 @@ private static void SetRelationships(this SqlDataReader reader, TopicIndex topic
     ///   Topics can be cross-referenced with each other topics via a one-to-one relationships. Once the topics are populated in
     ///   memory, loop through the data to create these associations.
     /// </remarks>
-    /// <param name="reader">The <see cref="SqlDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
     /// <param name="topics">A <see cref="Dictionary{Int32, Topic}"/> of topics to be loaded.</param>
     /// <param name="markDirty">
     ///   Specified whether the target collection value should be marked as dirty, assuming the value changes. By default, it
     ///   will be marked dirty if the value is new or has changed from a previous value. By setting this parameter, that
     ///   behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update
     ///   from being persisted to the data store on <see cref="Repositories.ITopicRepository.Save(Topic, Boolean)"/>.
     /// </param>
-    private static void SetReferences(this SqlDataReader reader, TopicIndex topics, bool? markDirty) {
+    private static void SetReferences(this IDataReader reader, TopicIndex topics, bool? markDirty) {
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Identify attributes
@@ -444,9 +448,9 @@ private static void SetReferences(this SqlDataReader reader, TopicIndex topics,
     ///   version history is aggregated per topic to allow topic information to be rolled back to a specific date.While version
     ///   content is not exposed directly via the Load() method, the metadata is.
     /// </remarks>
-    /// <param name="reader">The <see cref="SqlDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
     /// <param name="topics">A <see cref="Dictionary{Int32, Topic}"/> of topics to be loaded.</param>
-    private static void SetVersionHistory(this SqlDataReader reader, TopicIndex topics) {
+    private static void SetVersionHistory(this IDataReader reader, TopicIndex topics) {
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Identify attributes
@@ -474,9 +478,9 @@ private static void SetVersionHistory(this SqlDataReader reader, TopicIndex topi
     /// <summary>
     ///   Retrieves a string value by column name.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> object.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> object.</param>
     /// <param name="columnName">The name of the column to retrieve the value from.</param>
-    private static string GetString(this SqlDataReader reader, string columnName) =>
+    private static string GetString(this IDataReader reader, string columnName) =>
       reader.GetString(reader.GetOrdinal(columnName));
 
     /*==========================================================================================================================
@@ -485,9 +489,9 @@ private static string GetString(this SqlDataReader reader, string columnName) =>
     /// <summary>
     ///   Retrieves a boolean value by column name.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> object.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> object.</param>
     /// <param name="columnName">The name of the column to retrieve the value from.</param>
-    private static bool GetBoolean(this SqlDataReader reader, string columnName) =>
+    private static bool GetBoolean(this IDataReader reader, string columnName) =>
       reader.GetBoolean(reader.GetOrdinal(columnName));
 
     /*==========================================================================================================================
@@ -496,9 +500,9 @@ private static bool GetBoolean(this SqlDataReader reader, string columnName) =>
     /// <summary>
     ///   Retrieves an integer value by column name.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> object.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> object.</param>
     /// <param name="columnName">The name of the column to retrieve the value from.</param>
-    private static int GetInteger(this SqlDataReader reader, string columnName) =>
+    private static int GetInteger(this IDataReader reader, string columnName) =>
       Int32.TryParse(reader.GetValue(reader.GetOrdinal(columnName)).ToString(), out var output)? output : -1;
 
     /*==========================================================================================================================
@@ -507,9 +511,9 @@ private static int GetInteger(this SqlDataReader reader, string columnName) =>
     /// <summary>
     ///   Retrieves a <see cref="Topic.Id"/> value by column name.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> object.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> object.</param>
     /// <param name="columnName">The name of the column to retrieve the value from.</param>
-    private static int GetTopicId(this SqlDataReader reader, string columnName = "TopicID") =>
+    private static int GetTopicId(this IDataReader reader, string columnName = "TopicID") =>
       reader.GetInt32(reader.GetOrdinal(columnName));
 
     /*==========================================================================================================================
@@ -518,9 +522,9 @@ private static int GetTopicId(this SqlDataReader reader, string columnName = "To
     /// <summary>
     ///   Retrieves a <see cref="Topic.Id"/> value by column name, while accepting null values.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> object.</param>
+    /// <param name="reader">The <see cref="IDataReader"/> object.</param>
     /// <param name="columnName">The name of the column to retrieve the value from.</param>
-    private static int? GetNullableTopicId(this SqlDataReader reader, string columnName = "TopicID") =>
+    private static int? GetNullableTopicId(this IDataReader reader, string columnName = "TopicID") =>
       reader.IsDBNull(reader.GetOrdinal(columnName))? null : reader.GetInt32(reader.GetOrdinal(columnName));
 
     /*==========================================================================================================================
@@ -529,8 +533,8 @@ private static int GetTopicId(this SqlDataReader reader, string columnName = "To
     /// <summary>
     ///   Retrieves the version column, with precisions appropriate for setting the <see cref="Topic.VersionHistory"/>.
     /// </summary>
-    /// <param name="reader">The <see cref="SqlDataReader"/> object.</param>
-    private static DateTime GetVersion(this SqlDataReader reader) =>
+    /// <param name="reader">The <see cref="IDataReader"/> object.</param>
+    private static DateTime GetVersion(this IDataReader reader) =>
       reader.GetDateTime(reader.GetOrdinal("Version"));
 
   } //Class

OnTopic.Tests/OnTopic.Tests.csproj

@@ -40,6 +40,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\OnTopic.Data.Caching\OnTopic.Data.Caching.csproj" />
+    <ProjectReference Include="..\OnTopic.Data.Sql\OnTopic.Data.Sql.csproj" />
     <ProjectReference Include="..\OnTopic.TestDoubles\OnTopic.TestDoubles.csproj" />
     <ProjectReference Include="..\OnTopic.ViewModels\OnTopic.ViewModels.csproj" />
     <ProjectReference Include="..\OnTopic\OnTopic.csproj" />