From 4b8185a490410e4a965ae94c884e32d3780cb0cd Mon Sep 17 00:00:00 2001
From: Youssef1313 <youssefvictor00@gmail.com>
Date: Sun, 17 Nov 2024 06:16:17 +0100
Subject: [PATCH] Document MSTEST0037 analyzer

---
 .../testing/mstest-analyzers/mstest0037.md    | 59 +++++++++++++++++++
 .../testing/mstest-analyzers/usage-rules.md   |  1 +
 docs/navigate/devops-testing/toc.yml          |  2 +
 3 files changed, 62 insertions(+)
 create mode 100644 docs/core/testing/mstest-analyzers/mstest0037.md

diff --git a/docs/core/testing/mstest-analyzers/mstest0037.md b/docs/core/testing/mstest-analyzers/mstest0037.md
new file mode 100644
index 0000000000000..cccd224175ec1
--- /dev/null
+++ b/docs/core/testing/mstest-analyzers/mstest0037.md
@@ -0,0 +1,59 @@
+---
+title: "Use proper 'Assert' methods"
+description: "Learn about code analysis rule MSTEST0037: Use proper 'Assert' methods."
+ms.date: 11/17/2024
+f1_keywords:
+- MSTEST0037
+- UseProperAssertMethodsAnalyzer
+helpviewer_keywords:
+- UseProperAssertMethodsAnalyzer
+- MSTEST0037
+author: Youssef1313
+ms.author: ygerges
+---
+# MSTEST0037: Use proper 'Assert' methods
+
+| Property                            | Value                                                                  |
+|-------------------------------------|------------------------------------------------------------------------|
+| **Rule ID**                         | MSTEST0037                                                             |
+| **Title**                           | Use proper 'Assert' methods                                            |
+| **Category**                        | Usage                                                                  |
+| **Fix is breaking or non-breaking** | Non-breaking                                                           |
+| **Enabled by default**              | No                                                                     |
+| **Default severity**                | Info                                                                   |
+| **Introduced in version**           | 3.7.0                                                                  |
+| **There is a code fix**             | No                                                                     |
+
+## Cause
+
+The use of <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> methods in a specific way when there is a better alternative.
+
+## Rule description
+
+There are multiple cases where you get this warning:
+
+- The use of `Assert.IsTrue(<expression> == null)` (with all combinations, like `IsFalse`, `!= null`, `is null`, or `is not null`).
+
+    Using `Assert.IsNull(<expression>)` or `Assert.IsNotNull(<expression>)` is a better alternative.
+
+- The use of `Assert.IsTrue(<expression1> == <expression2>)` (with all combinations, like `IsFalse` or `!=`).
+
+    Using `Assert.AreEqual(<expression1>, <expression2>)` or `Assert.AreNotEqual(<expression1>, <expression2>)` is a better alternative.
+
+- The use of `Assert.AreEqual(true, <expression>)` or `Assert.AreEqual(false, <expression>)`.
+
+    Using `Assert.IsTrue(<expression>)` or `Assert.IsFalse(<expression>)` is a better alternative.
+
+- The use of `Assert.AreEqual(null, <expression>)` or `Assert.AreNotEqual(null, <expression>)`.
+
+    Using `Assert.IsNull(<expression>)` or `Assert.IsNotNull<expression>` is a better alternative.
+
+In many cases, the better alternative provides better messages when they fail and are also easier to read.
+
+## How to fix violations
+
+Use the better alternative method.
+
+## When to suppress warnings
+
+You usually don't want to suppress warnings from this rule if you decided to opt-in for it.
diff --git a/docs/core/testing/mstest-analyzers/usage-rules.md b/docs/core/testing/mstest-analyzers/usage-rules.md
index 6d2777c2cc68b..c8a742fc973af 100644
--- a/docs/core/testing/mstest-analyzers/usage-rules.md
+++ b/docs/core/testing/mstest-analyzers/usage-rules.md
@@ -27,3 +27,4 @@ Identifier | Name | Description
 [MSTEST0023](mstest0023.md) | DoNotNegateBooleanAssertionAnalyzer | Do not negate boolean assertions
 [MSTEST0024](mstest0024.md) | DoNotStoreStaticTestContextAnalyzer | Do not store TestContext in a static member
 [MSTEST0026](mstest0026.md) | AssertionArgsShouldAvoidConditionalAccessRuleId | Avoid conditional access in assertions
+[MSTEST0037](mstest0037.md) | UseProperAssertMethodsAnalyzer | Use proper `Assert` methods
diff --git a/docs/navigate/devops-testing/toc.yml b/docs/navigate/devops-testing/toc.yml
index ac14d5b67b0c9..e43d2517ee665 100644
--- a/docs/navigate/devops-testing/toc.yml
+++ b/docs/navigate/devops-testing/toc.yml
@@ -187,6 +187,8 @@ items:
                     href: ../../core/testing/mstest-analyzers/mstest0034.md
                   - name: MSTEST0035
                     href: ../../core/testing/mstest-analyzers/mstest0035.md
+                  - name: MSTEST0037
+                    href: ../../core/testing/mstest-analyzers/mstest0037.md
       - name: Microsoft Testing Platform
         items:
           - name: Overview