Support assertions on System.Text.Json.JsonSerializerOptions based (de)serialization

.editorconfig

@@ -392,3 +392,5 @@ dotnet_diagnostic.MA0047.severity = none
 
 # Use an overload of 'GetHashCode' that has a StringComparison parameter
 dotnet_diagnostic.MA0074.severity = none
+
+dotnet_diagnostic.VSSpell001.severity = suggestion # Correct spelling.

Src/FluentAssertions/AssertionExtensions.cs

@@ -22,6 +22,10 @@
 #if !NETSTANDARD2_0
 using FluentAssertions.Events;
 #endif
+#if NET6_0_OR_GREATER
+using System.Text.Json;
+using FluentAssertions.Json;
+#endif
 
 namespace FluentAssertions;
 
@@ -467,6 +471,26 @@ public static NullableTimeOnlyAssertions Should(this TimeOnly? actualValue)
         return new NullableTimeOnlyAssertions(actualValue);
     }
 
+    /// <summary>
+    /// Returns an <see cref="JsonElementAssertions"/> object that can be used to assert the
+    /// current <see cref="JsonElement"/>.
+    /// </summary>
+    [Pure]
+    public static JsonElementAssertions Should(this JsonElement actualValue)
+    {
+        return new JsonElementAssertions(actualValue);
+    }
+
+    /// <summary>
+    /// Returns an <see cref="JsonSerializerOptionsAssertions"/> object that can be used to assert the
+    /// current <see cref="JsonSerializerOptions"/>.
+    /// </summary>
+    [Pure]
+    public static JsonSerializerOptionsAssertions Should(this JsonSerializerOptions actualValue)
+    {
+        return new JsonSerializerOptionsAssertions(actualValue);
+    }
+
 #endif
 
     /// <summary>

Src/FluentAssertions/FluentAssertions.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <!-- To reduce build times, we only enable analyzers for the newest TFM -->
   <PropertyGroup>
@@ -65,6 +65,7 @@
     <When Condition="'$(TargetFramework)' == 'netcoreapp3.0'">
       <ItemGroup>
         <Compile Remove="Common/NullConfigurationStore.cs" />
+        <Compile Remove="Json/*.cs" />
         <Compile Remove="SystemExtensions.cs" />
       </ItemGroup>
       <ItemGroup>
@@ -74,6 +75,7 @@
     <When Condition="'$(TargetFramework)' == 'netcoreapp2.1'">
       <ItemGroup>
         <Compile Remove="Common/NullConfigurationStore.cs" />
+        <Compile Remove="Json/*.cs" />
         <Compile Remove="SystemExtensions.cs" />
       </ItemGroup>
       <ItemGroup>
@@ -84,6 +86,7 @@
       <ItemGroup>
         <Compile Remove="Common/AppSettingsConfigurationStore.cs" />
         <Compile Remove="Common/ConfigurationStoreExceptionInterceptor.cs" />
+        <Compile Remove="Json/*.cs" />
         <Compile Remove="SystemExtensions.cs" />
       </ItemGroup>
     </When>
@@ -93,6 +96,7 @@
         <Compile Remove="Common/ConfigurationStoreExceptionInterceptor.cs" />
         <Compile Remove="Events/*.cs" />
         <Compile Remove="EventRaisingExtensions.cs" />
+        <Compile Remove="Json/*.cs" />
       </ItemGroup>
       <ItemGroup>
         <PackageReference Include="System.Threading.Tasks.Extensions" Version="4.5.0" />
@@ -101,6 +105,7 @@
     <When Condition="'$(TargetFramework)' == 'net47'">
       <ItemGroup>
         <Compile Remove="Common/NullConfigurationStore.cs" />
+        <Compile Remove="Json/*.cs" />
       </ItemGroup>
       <ItemGroup>
         <PackageReference Include="System.Threading.Tasks.Extensions" Version="4.5.0" />

Src/FluentAssertions/Json/JsonElementAssertions.cs

@@ -0,0 +1,150 @@
+using System.Diagnostics;
+using System.Text.Json;
+using FluentAssertions.Execution;
+
+namespace FluentAssertions.Json;
+
+/// <summary>
+/// Contains a number of methods to assert that an <see cref="JsonElement" /> is in the expected state.
+/// </summary>
+[DebuggerNonUserCode]
+public class JsonElementAssertions
+{
+    public JsonElement Subject { get; }
+
+    /// <summary>
+    ///     Initializes a new instance of the <see cref="JsonElementAssertions" /> class.
+    /// </summary>
+    /// <param name="subject">The subject.</param>
+    public JsonElementAssertions(JsonElement subject)
+    {
+        Subject = subject;
+    }
+
+    /// <summary>
+    ///     Asserts that the current <see cref="JsonElement"/> has the specified <see cref="JsonValueKind"/>.
+    /// </summary>
+    /// <param name="valueKind">The JSON string.</param>
+    /// <param name="because">
+    ///     A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
+    ///     is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
+    /// </param>
+    /// <param name="becauseArgs">
+    ///     Zero or more objects to format using the placeholders in <see paramref="because" />.
+    /// </param>
+    public AndConstraint<JsonElementAssertions> HaveValueKind(JsonValueKind valueKind, string because = "", params object[] becauseArgs)
+    {
+        Execute.Assertion
+            .BecauseOf(because, becauseArgs)
+            .ForCondition(Subject.ValueKind == valueKind)
+            .FailWith("Expected {context:JSON} to have value kind {0}{reason}, but found {1}.", valueKind, Subject.ValueKind);
+
+        return new(this);
+    }
+
+    /// <summary>
+    ///     Asserts that the current <see cref="JsonElement"/> is the JSON null node.
+    /// </summary>
+    /// <param name="because">
+    ///     A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
+    ///     is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
+    /// </param>
+    /// <param name="becauseArgs">
+    ///     Zero or more objects to format using the placeholders in <see paramref="because" />.
+    /// </param>
+    public AndConstraint<JsonElementAssertions> BeNull(string because = "", params object[] becauseArgs)
+    {
+        Execute.Assertion
+            .BecauseOf(because, becauseArgs)
+            .ForCondition(Subject.ValueKind == JsonValueKind.Null)
+            .FailWith("Expected {context:JSON} to be a JSON null{reason}, but found {0}.", Subject);
+
+        return new(this);
+    }
+
+    /// <summary>
+    ///     Asserts that the current <see cref="JsonElement"/> is the JSON string node.
+    /// </summary>
+    /// <param name="value">The value of the JSON string node.</param>
+    /// <param name="because">
+    ///     A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
+    ///     is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
+    /// </param>
+    /// <param name="becauseArgs">
+    ///     Zero or more objects to format using the placeholders in <see paramref="because" />.
+    /// </param>
+    public AndConstraint<JsonElementAssertions> BeString(string value, string because = "", params object[] becauseArgs)
+    {
+        Execute.Assertion
+            .BecauseOf(because, becauseArgs)
+            .ForCondition(Subject.ValueKind == JsonValueKind.String && Subject.GetString() == value)
+            .FailWith("Expected {context:JSON} to be a JSON string {0}{reason}, but found {1}.", value, Subject);
+
+        return new(this);
+    }
+
+    /// <summary>
+    ///     Asserts that the current <see cref="JsonElement"/> is the JSON number node.
+    /// </summary>
+    /// <param name="value">The value of the JSON number node.</param>
+    /// <param name="because">
+    ///     A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
+    ///     is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
+    /// </param>
+    /// <param name="becauseArgs">
+    ///     Zero or more objects to format using the placeholders in <see paramref="because" />.
+    /// </param>
+    public AndConstraint<JsonElementAssertions> BeNumber(decimal value, string because = "", params object[] becauseArgs)
+    {
+        Execute.Assertion
+            .BecauseOf(because, becauseArgs)
+            .ForCondition(Subject.ValueKind == JsonValueKind.Number && Subject.GetDecimal() == value)
+            .FailWith("Expected {context:JSON} to be a JSON string {0}{reason}, but found {1}.", value, Subject);
+
+        return new(this);
+    }
+
+    /// <inheritdoc cref="BeNumber(decimal, string, object[])"/>
+    public AndConstraint<JsonElementAssertions> BeNumber(long value, string because = "", params object[] becauseArgs)
+        => BeNumber((decimal)value, because, becauseArgs);
+
+    /// <summary>
+    ///     Asserts that the current <see cref="JsonElement"/> is the JSON true node.
+    /// </summary>
+    /// <param name="because">
+    ///     A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
+    ///     is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
+    /// </param>
+    /// <param name="becauseArgs">
+    ///     Zero or more objects to format using the placeholders in <see paramref="because" />.
+    /// </param>
+    public AndConstraint<JsonElementAssertions> BeTrue(string because = "", params object[] becauseArgs)
+    {
+        Execute.Assertion
+            .BecauseOf(because, becauseArgs)
+            .ForCondition(Subject.ValueKind == JsonValueKind.True)
+            .FailWith("Expected {context:JSON} to be a JSON true{reason}, but found {0}.", Subject);
+
+        return new(this);
+    }
+
+    /// <summary>
+    ///     Asserts that the current <see cref="JsonElement"/> is the JSON false node.
+    /// </summary>
+    /// <param name="because">
+    ///     A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
+    ///     is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
+    /// </param>
+    /// <param name="becauseArgs">
+    ///     Zero or more objects to format using the placeholders in <see paramref="because" />.
+    /// </param>
+    public AndConstraint<JsonElementAssertions> BeFalse(string because = "", params object[] becauseArgs)
+    {
+        Execute.Assertion
+            .BecauseOf(because, becauseArgs)
+            .ForCondition(Subject.ValueKind == JsonValueKind.False)
+            .FailWith("Expected {context:JSON} to be JSON false{reason}, but found {0}.", Subject);
+
+        return new(this);
+    }
+}

Src/FluentAssertions/Json/JsonSerializerOptionsAssertions.cs

@@ -0,0 +1,124 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using System.Text;
+using System.Text.Json;
+using FluentAssertions.Common;
+using FluentAssertions.Execution;
+using FluentAssertions.Primitives;
+
+namespace FluentAssertions.Json;
+
+/// <summary>
+///     Contains a number of methods to assert that an <see cref="JsonSerializerOptions" /> is in the expected state.
+/// </summary>
+[DebuggerNonUserCode]
+public class JsonSerializerOptionsAssertions : ReferenceTypeAssertions<JsonSerializerOptions, JsonSerializerOptionsAssertions>
+{
+    /// <summary>
+    ///     Initializes a new instance of the <see cref="JsonSerializerOptionsAssertions" /> class.
+    /// </summary>
+    /// <param name="subject">The subject.</param>
+    public JsonSerializerOptionsAssertions(JsonSerializerOptions subject)
+        : base(subject)
+    {
+    }
+
+    protected override string Identifier => "options";
+
+    /// <summary>
+    ///     Asserts that the current <see cref="JsonSerializerOptions"/> can be used to deserialize the specified JSON string.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize to.</typeparam>
+    /// <param name="json">The JSON string.</param>
+    /// <param name="because">
+    ///     A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
+    ///     is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
+    /// </param>
+    /// <param name="becauseArgs">
+    ///     Zero or more objects to format using the placeholders in <see paramref="because" />.
+    /// </param>
+    /// <exception cref="ArgumentNullException"><paramref name="json"/> is <see langword="null"/>.</exception>
+    public AndWhichConstraint<JsonSerializerOptionsAssertions, T> Deserialize<T>(Stream json, string because = "", params object[] becauseArgs)
+    {
+        Guard.ThrowIfArgumentIsNull(json);
+
+        Execute.Assertion
+            .ForCondition(Subject is { })
+            .FailWith("Can not use {context} to deserialize from JSON as it is <null>.");
+
+        T deserialzed = TryDeserialize<T>(json, out Exception failure);
+
+        Execute.Assertion
+            .BecauseOf(because, becauseArgs)
+            .ForCondition(failure is null)
+            .FailWith("Expected {context:the options} to deserialize {0}{reason}, but it failed: {1}.", json, failure?.Message);
+
+        return new AndWhichConstraint<JsonSerializerOptionsAssertions, T>(this, deserialzed);
+    }
+
+    /// <inheritdoc cref="Deserialize{T}(Stream, string, object[])"/>
+    public AndWhichConstraint<JsonSerializerOptionsAssertions, T> Deserialize<T>(string json, string because = "", params object[] becauseArgs)
+    {
+        Stream stream = json is null ? null : new MemoryStream(Encoding.UTF8.GetBytes(json));
+        return Deserialize<T>(stream, because, becauseArgs);
+    }
+
+    /// <summary>
+    ///     Asserts that the current <see cref="JsonSerializerOptions"/> can be used to serialize the specified value.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize to.</typeparam>
+    /// <param name="value">The value to serialize.</param>
+    /// <param name="because">
+    ///     A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
+    ///     is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
+    /// </param>
+    /// <param name="becauseArgs">
+    ///     Zero or more objects to format using the placeholders in <see paramref="because" />.
+    /// </param>
+    public AndWhichConstraint<JsonSerializerOptionsAssertions, JsonElement> Serialize<T>(T value, string because = "", params object[] becauseArgs)
+    {
+        Execute.Assertion
+            .ForCondition(Subject is { })
+            .FailWith("Can not use {context} to serialize to JSON as it is <null>.");
+
+        JsonElement serialized = TrySerialize(value, out Exception failure);
+
+        Execute.Assertion
+            .BecauseOf(because, becauseArgs)
+            .ForCondition(failure is null)
+            .FailWith("Expected {context:the options} to serialize {0}{reason}, but it failed: {1}.", value, failure?.Message);
+
+        return new AndWhichConstraint<JsonSerializerOptionsAssertions, JsonElement>(this, serialized);
+    }
+
+    private T TryDeserialize<T>(Stream json, out Exception failure)
+    {
+        try
+        {
+            failure = null;
+            return JsonSerializer.Deserialize<T>(json, Subject);
+        }
+        catch (Exception exception)
+        {
+            failure = exception;
+            return default;
+        }
+    }
+
+    private JsonElement TrySerialize<T>(T value, out Exception failure)
+    {
+        try
+        {
+            failure = null;
+            var bytes = JsonSerializer.SerializeToUtf8Bytes(value, Subject);
+            using var doc = JsonDocument.Parse(bytes);
+            return doc.RootElement.Clone();
+        }
+        catch (Exception exception)
+        {
+            failure = exception;
+            return default;
+        }
+    }
+}

Tests/FluentAssertions.Specs/FluentAssertions.Specs.csproj

@@ -13,6 +13,10 @@
     <Compile Remove="Events\*.cs" />
   </ItemGroup>
 
+  <ItemGroup Condition="'$(TargetFramework)' != 'net6.0' ">
+    <Compile Remove="Json\*.cs" />
+  </ItemGroup>
+
   <ItemGroup Condition="'$(TargetFramework)' == 'net47'">
     <!--
       (SRCU = System.Runtime.CompilerServices.Unsafe)