Deprecates That property and suggest Instance instead (#5811)

Author: Evangelink

src/TestFramework/TestFramework/Assertions/Assert.cs

@@ -14,6 +14,17 @@ private Assert()
     {
     }
 
+    /// <summary>
+    /// Gets the singleton instance of the Assert functionality.
+    /// </summary>
+    /// <remarks>
+    /// Users can use this to plug-in custom assertions through C# extension methods.
+    /// For instance, the signature of a custom assertion provider could be "public static void IsOfType&lt;T&gt;(this Assert assert, object obj)"
+    /// Users could then use a syntax similar to the default assertions which in this case is "Assert.Instance.IsOfType&lt;Dog&gt;(animal);"
+    /// More documentation is at "https://github.com/Microsoft/testfx/docs/README.md".
+    /// </remarks>
+    public static Assert Instance { get; } = new Assert();
+
     /// <summary>
     /// Gets the singleton instance of the Assert functionality.
     /// </summary>
@@ -23,7 +34,12 @@ private Assert()
     /// Users could then use a syntax similar to the default assertions which in this case is "Assert.That.IsOfType&lt;Dog&gt;(animal);"
     /// More documentation is at "https://github.com/Microsoft/testfx/docs/README.md".
     /// </remarks>
-    public static Assert That { get; } = new Assert();
+#if NET6_0_OR_GREATER
+    [Obsolete(FrameworkConstants.ThatPropertyObsoleteMessage, DiagnosticId = "MSTESTOBS")]
+#else
+    [Obsolete(FrameworkConstants.ThatPropertyObsoleteMessage)]
+#endif
+    public static Assert That { get; } = Instance;
 
     /// <summary>
     /// Replaces null characters ('\0') with "\\0".

src/TestFramework/TestFramework/Assertions/CollectionAssert.cs

@@ -16,6 +16,17 @@ private CollectionAssert()
     {
     }
 
+    /// <summary>
+    /// Gets the singleton instance of the CollectionAssert functionality.
+    /// </summary>
+    /// <remarks>
+    /// Users can use this to plug-in custom assertions through C# extension methods.
+    /// For instance, the signature of a custom assertion provider could be "public static void AreEqualUnordered(this CollectionAssert customAssert, ICollection expected, ICollection actual)"
+    /// Users could then use a syntax similar to the default assertions which in this case is "CollectionAssert.Instance.AreEqualUnordered(list1, list2);"
+    /// More documentation is at "https://github.com/Microsoft/testfx/docs/README.md".
+    /// </remarks>
+    public static CollectionAssert Instance { get; } = new CollectionAssert();
+
     /// <summary>
     /// Gets the singleton instance of the CollectionAssert functionality.
     /// </summary>
@@ -25,7 +36,12 @@ private CollectionAssert()
     /// Users could then use a syntax similar to the default assertions which in this case is "CollectionAssert.That.AreEqualUnordered(list1, list2);"
     /// More documentation is at "https://github.com/Microsoft/testfx/docs/README.md".
     /// </remarks>
-    public static CollectionAssert That { get; } = new CollectionAssert();
+#if NET6_0_OR_GREATER
+    [Obsolete(FrameworkConstants.ThatPropertyObsoleteMessage, DiagnosticId = "MSTESTOBS")]
+#else
+    [Obsolete(FrameworkConstants.ThatPropertyObsoleteMessage)]
+#endif
+    public static CollectionAssert That { get; } = Instance;
 
     #endregion
 

src/TestFramework/TestFramework/Assertions/StringAssert.cs

@@ -16,6 +16,17 @@ private StringAssert()
     {
     }
 
+    /// <summary>
+    /// Gets the singleton instance of the StringAssert functionality.
+    /// </summary>
+    /// <remarks>
+    /// Users can use this to plug-in custom assertions through C# extension methods.
+    /// For instance, the signature of a custom assertion provider could be "public static void ContainsWords(this StringAssert customAssert, string value, ICollection substrings)"
+    /// Users could then use a syntax similar to the default assertions which in this case is "StringAssert.Instance.ContainsWords(value, substrings);"
+    /// More documentation is at "https://github.com/Microsoft/testfx/docs/README.md".
+    /// </remarks>
+    public static StringAssert Instance { get; } = new StringAssert();
+
     /// <summary>
     /// Gets the singleton instance of the StringAssert functionality.
     /// </summary>
@@ -25,7 +36,12 @@ private StringAssert()
     /// Users could then use a syntax similar to the default assertions which in this case is "StringAssert.That.ContainsWords(value, substrings);"
     /// More documentation is at "https://github.com/Microsoft/testfx/docs/README.md".
     /// </remarks>
-    public static StringAssert That { get; } = new StringAssert();
+#if NET6_0_OR_GREATER
+    [Obsolete(FrameworkConstants.ThatPropertyObsoleteMessage, DiagnosticId = "MSTESTOBS")]
+#else
+    [Obsolete(FrameworkConstants.ThatPropertyObsoleteMessage)]
+#endif
+    public static StringAssert That { get; } = Instance;
 
     #endregion
 

src/TestFramework/TestFramework/FrameworkConstants.cs

@@ -9,4 +9,5 @@ namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 internal static class FrameworkConstants
 {
     internal const string PublicTypeObsoleteMessage = "We will remove or hide this type starting with v4. If you are using this type, reach out to our team on https://github.com/microsoft/testfx.";
+    internal const string ThatPropertyObsoleteMessage = "The 'That' property is obsolete and will be removed in a future version. Use the 'Instance' property instead.";
 }

src/TestFramework/TestFramework/PublicAPI/PublicAPI.Unshipped.txt

@@ -7,6 +7,7 @@ static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsGreaterThan<T>(T lo
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsGreaterThanOrEqualTo<T>(T lowerBound, T value) -> void
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsGreaterThanOrEqualTo<T>(T lowerBound, T value, string? message) -> void
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsGreaterThanOrEqualTo<T>(T lowerBound, T value, string? message, params object?[]? parameters) -> void
+static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.Instance.get -> Microsoft.VisualStudio.TestTools.UnitTesting.Assert!
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsInRange<T>(T minValue, T maxValue, T value) -> void
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsInRange<T>(T minValue, T maxValue, T value, string? message) -> void
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsInRange<T>(T minValue, T maxValue, T value, string? message, params object?[]? parameters) -> void
@@ -26,3 +27,5 @@ static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsPositive<T>(T value
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsPositive<T>(T value, string? message) -> void
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsPositive<T>(T value, string? message, params object?[]? parameters) -> void
 static Microsoft.VisualStudio.TestTools.UnitTesting.Assert.Throws<TException>(System.Func<object?>! action, ref Microsoft.VisualStudio.TestTools.UnitTesting.Assert.AssertNonStrictThrowsInterpolatedStringHandler<TException!> message) -> TException!
+static Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.Instance.get -> Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert!
+static Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.Instance.get -> Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert!

test/IntegrationTests/TestAssets/FxExtensibilityTestProject/AssertExTest.cs

@@ -11,16 +11,16 @@ namespace FxExtensibilityTestProject;
 public class AssertExTest
 {
     [TestMethod]
-    public void BasicAssertExtensionTest() => Assert.That.IsOfType<ArgumentException>(new ArgumentOutOfRangeException());
+    public void BasicAssertExtensionTest() => Assert.Instance.IsOfType<ArgumentException>(new ArgumentOutOfRangeException());
 
     [TestMethod]
     [MethodImpl(MethodImplOptions.NoInlining | MethodImplOptions.NoOptimization)]
-    public void BasicFailingAssertExtensionTest() => Assert.That.IsOfType<FormatException>(new ArgumentNullException());
+    public void BasicFailingAssertExtensionTest() => Assert.Instance.IsOfType<FormatException>(new ArgumentNullException());
 
     [TestMethod]
-    public void ChainedAssertExtensionTest() => Assert.That.Is().Divisor(120, 5);
+    public void ChainedAssertExtensionTest() => Assert.Instance.Is().Divisor(120, 5);
 
     [TestMethod]
     [MethodImpl(MethodImplOptions.NoInlining | MethodImplOptions.NoOptimization)]
-    public void ChainedFailingAssertExtensionTest() => Assert.That.Is().Positive(-10);
+    public void ChainedFailingAssertExtensionTest() => Assert.Instance.Is().Positive(-10);
 }

test/UnitTests/TestFramework.UnitTests/Assertions/AssertTests.cs

@@ -5,10 +5,10 @@ namespace Microsoft.VisualStudio.TestPlatform.TestFramework.UnitTests;
 
 public partial class AssertTests
 {
-    #region That tests
-    public void ThatShouldReturnAnInstanceOfAssert() => Verify(Assert.That is not null);
+    #region Instance tests
+    public void InstanceShouldReturnAnInstanceOfAssert() => Verify(Assert.Instance is not null);
 
-    public void ThatShouldCacheAssertInstance() => Verify(ReferenceEquals(Assert.That, Assert.That));
+    public void InstanceShouldCacheAssertInstance() => Verify(ReferenceEquals(Assert.Instance, Assert.Instance));
     #endregion
 
     #region ReplaceNullChars tests

test/UnitTests/TestFramework.UnitTests/Assertions/CollectionAssertTests.cs

@@ -9,9 +9,9 @@ namespace Microsoft.VisualStudio.TestPlatform.TestFramework.UnitTests.Assertions
 
 public class CollectionAssertTests : TestContainer
 {
-    public void ThatShouldReturnAnInstanceOfCollectionAssert() => Verify(CollectionAssert.That is not null);
+    public void InstanceShouldReturnAnInstanceOfCollectionAssert() => Verify(CollectionAssert.Instance is not null);
 
-    public void ThatShouldCacheCollectionAssertInstance() => Verify(CollectionAssert.That == CollectionAssert.That);
+    public void InstanceShouldCacheCollectionAssertInstance() => Verify(CollectionAssert.Instance == CollectionAssert.Instance);
 
     public void CollectionAssertContainsNullabilityPostConditions()
     {

test/UnitTests/TestFramework.UnitTests/Assertions/StringAssertTests.cs

@@ -7,9 +7,9 @@ namespace Microsoft.VisualStudio.TestPlatform.TestFramework.UnitTests.Assertions
 
 public class StringAssertTests : TestContainer
 {
-    public void ThatShouldReturnAnInstanceOfStringAssert() => Verify(StringAssert.That is not null);
+    public void InstanceShouldReturnAnInstanceOfStringAssert() => Verify(StringAssert.Instance is not null);
 
-    public void ThatShouldCacheStringAssertInstance() => Verify(StringAssert.That == StringAssert.That);
+    public void InstanceShouldCacheStringAssertInstance() => Verify(StringAssert.Instance == StringAssert.Instance);
 
     public void StringAssertContains()
     {