docs: add mstest docs (#323)

Meir017 · web-flow · commit 6396e088a370 · 2024-04-16T15:20:14.000+03:00
* docs: add mstest docs
diff --git a/README.md b/README.md
@@ -31,6 +31,7 @@ dotnet add package FluentAssertions.Analyzers
 ## Docs
 
 - [FluentAssertions Analyzer Docs](docs/FluentAssertionsAnalyzer.md)
+- [MsTest Analyzer Docs](docs/MsTestAnalyzer.md)
 
 ## Getting Started
 
diff --git a/docs/MsTestAnalyzer.md b/docs/MsTestAnalyzer.md
@@ -0,0 +1,63 @@
+<!--
+This is a generated file, please edit src\FluentAssertions.Analyzers.FluentAssertionAnalyzerDocsGenerator\DocsGenerator.cs to change the contents
+-->
+
+# MsTest Analyzer Docs
+
+- [BooleanAssertIsTrue](#scenario-booleanassertistrue) - `flag.Should().BeTrue();`
+- [BooleanAssertIsFalse](#scenario-booleanassertisfalse) - `flag.Should().BeFalse();`
+
+
+## Scenarios
+
+### scenario: BooleanAssertIsTrue
+
+```cs
+// arrange
+var flag = true;
+
+// old assertion:
+Assert.IsTrue(flag);
+
+// new assertion:
+flag.Should().BeTrue();
+```
+
+#### Failure messages
+
+```cs
+var flag = false;
+
+// old assertion:
+Assert.IsTrue(flag); 	// fail message: Assert.IsTrue failed. 
+
+// new assertion:
+flag.Should().BeTrue(); 	// fail message: Expected flag to be true, but found False.
+```
+
+### scenario: BooleanAssertIsFalse
+
+```cs
+// arrange
+var flag = false;
+
+// old assertion:
+Assert.IsFalse(flag);
+
+// new assertion:
+flag.Should().BeFalse();
+```
+
+#### Failure messages
+
+```cs
+var flag = true;
+
+// old assertion:
+Assert.IsFalse(flag); 	// fail message: Assert.IsFalse failed. 
+
+// new assertion:
+flag.Should().BeFalse(); 	// fail message: Expected flag to be false, but found True.
+```
+
+
diff --git a/scripts/run-docs-tests.ps1 b/scripts/run-docs-tests.ps1
@@ -11,7 +11,7 @@ Pop-Location
 if ($FormatAndExecuteTestsAgain) {
     Push-Location src
     Push-Location FluentAssertions.Analyzers.FluentAssertionAnalyzerDocs
-    dotnet format analyzers --diagnostics FAA0001 --severity info --verbosity normal
+    dotnet format analyzers --diagnostics FAA0001 FAA0003 --severity info --verbosity normal
     Pop-Location
     Pop-Location
 
diff --git a/src/FluentAssertions.Analyzers.FluentAssertionAnalyzerDocs/MsTestAnalyzerTests.cs b/src/FluentAssertions.Analyzers.FluentAssertionAnalyzerDocs/MsTestAnalyzerTests.cs
@@ -0,0 +1,79 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using FluentAssertions;
+using FluentAssertions.Execution;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace FluentAssertions.Analyzers.FluentAssertionAnalyzerDocs;
+
+[TestClass]
+public class MsTestAnalyzerTests
+{
+    [TestMethod]
+    public void BooleanAssertIsTrue()
+    {
+        // arrange
+        var flag = true;
+
+        // old assertion:
+        Assert.IsTrue(flag);
+
+        // new assertion:
+        flag.Should().BeTrue();
+    }
+
+    [TestMethod, ExpectedException(typeof(AssertFailedException))]
+    public void BooleanAssertIsTrue_Failure_OldAssertion()
+    {
+        // arrange
+        var flag = false;
+
+        // old assertion:
+        Assert.IsTrue(flag);
+    }
+
+    [TestMethod, ExpectedException(typeof(AssertFailedException))]
+    public void BooleanAssertIsTrue_Failure_NewAssertion()
+    {
+        // arrange
+        var flag = false;
+
+        // new assertion:
+        flag.Should().BeTrue();
+    }
+
+    [TestMethod]
+    public void BooleanAssertIsFalse()
+    {
+        // arrange
+        var flag = false;
+
+        // old assertion:
+        Assert.IsFalse(flag);
+
+        // new assertion:
+        flag.Should().BeFalse();
+    }
+
+    [TestMethod, ExpectedException(typeof(AssertFailedException))]
+    public void BooleanAssertIsFalse_Failure_OldAssertion()
+    {
+        // arrange
+        var flag = true;
+
+        // old assertion:
+        Assert.IsFalse(flag);
+    }
+
+    [TestMethod, ExpectedException(typeof(AssertFailedException))]
+    public void BooleanAssertIsFalse_Failure_NewAssertion()
+    {
+        // arrange
+        var flag = true;
+
+        // new assertion:
+        flag.Should().BeFalse();
+    }
+    
+}
diff --git a/src/FluentAssertions.Analyzers.FluentAssertionAnalyzerDocsGenerator/DocsGenerator.cs b/src/FluentAssertions.Analyzers.FluentAssertionAnalyzerDocsGenerator/DocsGenerator.cs
@@ -22,37 +22,41 @@ public async Task Execute()
         var compilation = await FluentAssertionAnalyzerDocsUtils.GetFluentAssertionAnalyzerDocsCompilation();
         var compilationWithAnalyzers = compilation.WithAnalyzers(ImmutableArray.Create(analyzer));
 
-        var docs = new StringBuilder();
-        var toc = new StringBuilder();
-        var scenarios = new StringBuilder();
+        var testAssembly = typeof(FluentAssertionAnalyzerDocs.FluentAssertionsAnalyzerTests).Assembly;
 
-        docs.AppendLine("<!--");
-        docs.AppendLine("This is a generated file, please edit src\\FluentAssertions.Analyzers.FluentAssertionAnalyzerDocsGenerator\\DocsGenerator.cs to change the contents");
-        docs.AppendLine("-->");
-        docs.AppendLine();
+        foreach (var tree in compilationWithAnalyzers.Compilation.SyntaxTrees.Where(t => t.FilePath.EndsWith("Tests.cs")))
+        {
+            Console.WriteLine($"File: {Path.GetFileName(tree.FilePath)}");
 
-        docs.AppendLine("# FluentAssertions Analyzer Docs");
-        docs.AppendLine();
+            var docsName = Path.GetFileNameWithoutExtension(tree.FilePath).Replace("Tests", ".md");
 
-        scenarios.AppendLine("## Scenarios");
-        scenarios.AppendLine();
+            var docs = new StringBuilder();
+            var toc = new StringBuilder();
+            var scenarios = new StringBuilder();
 
-        var testAssembly = typeof(FluentAssertions.Analyzers.FluentAssertionAnalyzerDocs.FluentAssertionsAnalyzerTests).Assembly;
+            docs.AppendLine("<!--");
+            docs.AppendLine("This is a generated file, please edit src\\FluentAssertions.Analyzers.FluentAssertionAnalyzerDocsGenerator\\DocsGenerator.cs to change the contents");
+            docs.AppendLine("-->");
+            docs.AppendLine();
 
-        foreach (var tree in compilationWithAnalyzers.Compilation.SyntaxTrees.Where(t => t.FilePath.EndsWith("Tests.cs")))
-        {
-            Console.WriteLine($"File: {Path.GetFileName(tree.FilePath)}");
+            var subject = Path.GetFileNameWithoutExtension(tree.FilePath).Replace("AnalyzerTests", string.Empty);
+            docs.AppendLine($"# {subject} Analyzer Docs");
+            docs.AppendLine();
 
+            scenarios.AppendLine("## Scenarios");
+            scenarios.AppendLine();
 
             var root = await tree.GetRootAsync();
             var classDef = root.DescendantNodes().OfType<ClassDeclarationSyntax>().First();
             var methods = root.DescendantNodes().OfType<MethodDeclarationSyntax>();
+            var methodsMap = methods.ToDictionary(m => m.Identifier.Text);
 
             var classType = testAssembly.GetType($"FluentAssertions.Analyzers.FluentAssertionAnalyzerDocs.{classDef.Identifier.Text}");
             var classInstance = Activator.CreateInstance(classType);
 
             foreach (var method in methods.Where(m => m.AttributeLists.Any(list => list.Attributes.Count is 1 && list.Attributes[0].Name.ToString() is "TestMethod")))
             {
+                // success scenario:
                 {
                     scenarios.AppendLine($"### scenario: {method.Identifier}");
                     scenarios.AppendLine();
@@ -67,8 +71,10 @@ public async Task Execute()
 
                     toc.AppendLine($"- [{method.Identifier}](#scenario-{method.Identifier.Text.ToLower()}) - `{newAssertion}`");
                 }
+
+                // FluentAssertion failures scenario:
+                if (methodsMap.TryGetValue($"{method.Identifier.Text}_Failure", out var testWithFailure))
                 {
-                    var testWithFailure = methods.FirstOrDefault(m => m.Identifier.Text == $"{method.Identifier.Text}_Failure");
                     var testMethodWithFailure = classType.GetMethod(testWithFailure.Identifier.Text);
 
                     var exceptionMessageLines = GetMethodExceptionMessageLines(classInstance, testMethodWithFailure);
@@ -88,8 +94,6 @@ public async Task Execute()
                     var arrange = bodyLines.TakeWhile(x => !string.IsNullOrEmpty(x))
                         .Select(l => l.Length > paddingToRemove ? l.Substring(paddingToRemove) : l).Aggregate((a, b) => $"{a}{Environment.NewLine}{b}");
 
-                    var methodBody = $"```cs{Environment.NewLine}{arrange}{Environment.NewLine}```";
-
                     scenarios.AppendLine($"#### Failure messages");
                     scenarios.AppendLine();
                     scenarios.AppendLine("```cs");
@@ -106,6 +110,43 @@ public async Task Execute()
                     scenarios.AppendLine("```");
                     scenarios.AppendLine();
                 }
+
+                // Testing Libraries failures scenarios:
+                if (methodsMap.TryGetValue($"{method.Identifier.Text}_Failure_OldAssertion", out var testWithFailureOldAssertion)
+                && methodsMap.TryGetValue($"{method.Identifier.Text}_Failure_NewAssertion", out var testWithFailureNewAssertion))
+                {
+                    var testMethodWithFailureOldAssertion = classType.GetMethod(testWithFailureOldAssertion.Identifier.Text);
+                    var testMethodWithFailureNewAssertion = classType.GetMethod(testWithFailureNewAssertion.Identifier.Text);
+
+                    var exceptionMessageLinesOldAssertion = GetMethodExceptionMessage(classInstance, testMethodWithFailureOldAssertion);
+                    var exceptionMessageLinesNewAssertion = GetMethodExceptionMessage(classInstance, testMethodWithFailureNewAssertion);
+
+                    var oldAssertionComment = testWithFailureOldAssertion.DescendantTrivia().First(x => x.IsKind(SyntaxKind.SingleLineCommentTrivia) && x.ToString().Equals("// old assertion:"));
+                    var newAssertionComment = testWithFailureNewAssertion.DescendantTrivia().First(x => x.IsKind(SyntaxKind.SingleLineCommentTrivia) && x.ToString().Equals("// new assertion:"));
+
+                    var bodyLines = testWithFailureNewAssertion.Body.ToFullString().Split(Environment.NewLine)[2..^2];
+                    var paddingToRemove = bodyLines[0].IndexOf(bodyLines[0].TrimStart());
+
+                    var oldAssertion = testWithFailureOldAssertion.Body.Statements.OfType<ExpressionStatementSyntax>().Single(x => x.Span.CompareTo(oldAssertionComment.Span) > 0).ToString().TrimStart() + " \t// fail message: " + exceptionMessageLinesOldAssertion;
+                    var newAssertion = testWithFailureNewAssertion.Body.Statements.OfType<ExpressionStatementSyntax>().Single(x => x.Span.CompareTo(newAssertionComment.Span) > 0).ToString().TrimStart() + " \t// fail message: " + exceptionMessageLinesNewAssertion;
+
+                    var arrange = bodyLines.TakeWhile(x => !string.IsNullOrEmpty(x))
+                        .Select(l => l.Length > paddingToRemove ? l.Substring(paddingToRemove) : l).Aggregate((a, b) => $"{a}{Environment.NewLine}{b}");
+
+                    scenarios.AppendLine($"#### Failure messages");
+                    scenarios.AppendLine();
+                    scenarios.AppendLine("```cs");
+                    scenarios.AppendLine(arrange);
+                    scenarios.AppendLine();
+                    scenarios.AppendLine($"// old assertion:");
+                    scenarios.AppendLine(oldAssertion);
+                    scenarios.AppendLine();
+                    scenarios.AppendLine($"// new assertion:");
+                    scenarios.AppendLine(newAssertion);
+                    scenarios.AppendLine("```");
+                    scenarios.AppendLine();
+                }
+
             }
 
             var diagnostics = await compilationWithAnalyzers.GetAllDiagnosticsAsync();
@@ -114,26 +155,28 @@ public async Task Execute()
                 Console.WriteLine($"source: {root.FindNode(diagnostic.Location.SourceSpan)}");
                 Console.WriteLine($"  diagnostic: {diagnostic}");
             }
-        }
 
-        docs.AppendLine(toc.ToString());
-        docs.AppendLine();
-        docs.AppendLine(scenarios.ToString());
+            docs.AppendLine(toc.ToString());
+            docs.AppendLine();
+            docs.AppendLine(scenarios.ToString());
 
-        var docsPath = Path.Combine(Environment.CurrentDirectory, "..", "..", "docs", "FluentAssertionsAnalyzer.md");
-        Directory.CreateDirectory(Path.GetDirectoryName(docsPath));
-        await File.WriteAllTextAsync(docsPath, docs.ToString());
+            var docsPath = Path.Combine(Environment.CurrentDirectory, "..", "..", "docs", docsName);
+            Directory.CreateDirectory(Path.GetDirectoryName(docsPath));
+            await File.WriteAllTextAsync(docsPath, docs.ToString());
+        }
     }
 
-    private string[] GetMethodExceptionMessageLines(object instnace, MethodInfo method)
+    private string[] GetMethodExceptionMessageLines(object instance, MethodInfo method)
+        => GetMethodExceptionMessage(instance, method).Split(Environment.NewLine, StringSplitOptions.RemoveEmptyEntries);
+    private string GetMethodExceptionMessage(object instance, MethodInfo method)
     {
         try
         {
-            method.Invoke(instnace, null);
+            method.Invoke(instance, null);
         }
         catch (Exception ex) when (ex.InnerException is AssertFailedException exception)
         {
-            return exception.Message.Split(Environment.NewLine, StringSplitOptions.RemoveEmptyEntries);
+            return exception.Message;
         }
 
         throw new InvalidOperationException("Method did not throw an exception");
diff --git a/src/FluentAssertions.Analyzers.FluentAssertionAnalyzerDocsGenerator/DocsVerifier.cs b/src/FluentAssertions.Analyzers.FluentAssertionAnalyzerDocsGenerator/DocsVerifier.cs
