v4.1 (#11)

- Add `Json` module to return JSON strings and write JSON as it's read to a `PipeWriter`
- Add `docfx`-based documentation to allow how-to docs and API docs to be generated on the same site

Reviewed-on: #11

src/Tests.CSharp/CommonCSharpTests.cs

@@ -1,3 +1,4 @@
+using System.IO.Pipelines;
 using Expecto.CSharp;
 using Expecto;
 using Microsoft.FSharp.Core;
@@ -16,7 +17,7 @@ internal class TestSerializer : IDocumentSerializer
 }
 
 /// <summary>
-/// C# Tests for common functionality in <tt>BitBadger.Documents</tt>
+/// C# Tests for common functionality in <c>BitBadger.Documents</c>
 /// </summary>
 public static class CommonCSharpTests
 {
@@ -417,7 +418,7 @@ public static class CommonCSharpTests
             })
         ])
     ]);
-    
+
     /// <summary>
     /// Unit tests for the Configuration static class
     /// </summary>
@@ -647,7 +648,115 @@ public static class CommonCSharpTests
             })
         ])
     ]);
-    
+
+    private static string StreamText(Stream stream)
+    {
+        stream.Position = 0L;
+        using StreamReader reader = new(stream);
+        return reader.ReadToEnd();
+    }
+
+    /// <summary>Unit tests for the PipeWriter module</summary>
+    private static readonly Test PipeWriterTests = TestList("PipeWriterModule",
+    [
+        TestList("WriteString",
+        [
+            TestCase("succeeds when writer is open", async () =>
+            {
+                await using MemoryStream stream = new();
+                var writer = PipeWriter.Create(stream, new StreamPipeWriterOptions(leaveOpen: true));
+                try
+                {
+                    var result = await PipeWriterModule.WriteString(writer, "abc");
+                    Expect.isTrue(result, "The write operation should have been successful");
+                    Expect.equal(StreamText(stream), "abc", "The string was not written correctly");
+                }
+                finally
+                {
+                    await writer.CompleteAsync();
+                }
+            }),
+            TestCase("succeeds when writer is completed", async () =>
+            {
+                await using MemoryStream stream = new();
+                var writer = PipeWriter.Create(stream, new StreamPipeWriterOptions(leaveOpen: true));
+                await writer.CompleteAsync();
+
+                var result = await PipeWriterModule.WriteString(writer, "abc");
+                Expect.isFalse(result, "The write operation should have returned false");
+                Expect.equal(StreamText(stream), "", "No text should have been written");
+            })
+        ]),
+        TestList("WriteStrings",
+        [
+            TestCase("succeeds with no strings", async () =>
+            {
+                await using MemoryStream stream = new();
+                var writer = PipeWriter.Create(stream, new StreamPipeWriterOptions(leaveOpen: true));
+                try
+                {
+                    await PipeWriterModule.WriteStrings(writer, []);
+                    Expect.equal(StreamText(stream), "[]", "An empty sequence of strings was not written correctly");
+                }
+                finally
+                {
+                    await writer.CompleteAsync();
+                }
+            }),
+            TestCase("succeeds with one strings", async () =>
+            {
+                await using MemoryStream stream = new();
+                var writer = PipeWriter.Create(stream, new StreamPipeWriterOptions(leaveOpen: true));
+                try
+                {
+                    await PipeWriterModule.WriteStrings(writer, ["le-test"]);
+                    Expect.equal(StreamText(stream), "[le-test]", "A sequence of one string was not written correctly");
+                }
+                finally
+                {
+                    await writer.CompleteAsync();
+                }
+            }),
+            TestCase("succeeds with many strings", async () =>
+            {
+                await using MemoryStream stream = new();
+                var writer = PipeWriter.Create(stream, new StreamPipeWriterOptions(leaveOpen: true));
+                
+                try
+                {
+                    await PipeWriterModule.WriteStrings(writer, ["z", "y", "x", "c", "b", "a"]);
+                    Expect.equal(StreamText(stream), "[z,y,x,c,b,a]",
+                        "A sequence of many strings was not written correctly");
+                }
+                finally
+                {
+                    await writer.CompleteAsync();
+                }
+            }),
+            TestCase("succeeds when the writer is completed early", async () =>
+            {
+                await using MemoryStream stream = new();
+                var writer = PipeWriter.Create(stream, new StreamPipeWriterOptions(leaveOpen: true));
+
+                await PipeWriterModule.WriteStrings(writer, Items());
+                Expect.equal(StreamText(stream), "[a,b,c", "The writing should have stopped when the writer completed");
+                return;
+
+                IEnumerable<string> Items()
+                {
+                    yield return "a";
+                    yield return "b";
+                    yield return "c";
+                    writer.Complete();
+                    yield return "d";
+                    yield return "e";
+                    yield return "f";
+                }
+            })
+        ])
+    ]);
+
+
     /// <summary>
     /// Unit tests
     /// </summary>
@@ -660,6 +769,7 @@ public static class CommonCSharpTests
         ParameterNameTests,
         AutoIdTests,
         QueryTests,
+        PipeWriterTests,
         TestSequenced(ConfigurationTests)
     ]);
 }