feat: Add MsTest analyzer to suggest DisplayName and Description attributes for commented tests

Documentation/Diagnostics/PH2146.md

@@ -0,0 +1,59 @@
+# PH2146: Test should use DisplayName or Description attribute instead of comments
+
+| Property | Value  |
+|--|--|
+| Package | [Philips.CodeAnalysis.MsTestAnalyzers](https://www.nuget.org/packages/Philips.CodeAnalysis.MsTestAnalyzers) |
+| Diagnostic ID | PH2146 |
+| Category  | [MsTest](../MsTest.md) |
+| Analyzer | [TestShouldUseDisplayNameAnalyzer](https://github.com/philips-software/roslyn-analyzers/blob/main/Philips.CodeAnalysis.MsTestAnalyzers/TestShouldUseDisplayNameAnalyzer.cs)
+| CodeFix  | No |
+| Severity | Info |
+| Enabled By Default | Yes |
+
+## Introduction
+
+Test methods and DataRow attributes often contain inline comments that describe their purpose, but these comments are not visible in test runners. MSTest provides better alternatives: `Description` attribute for test methods and `DisplayName` parameter for DataRow attributes.
+
+## How to solve
+
+For test methods with meaningful comments, add a `Description` attribute instead of using inline comments.
+
+For DataRow attributes with meaningful comments, add a `DisplayName` parameter instead of using inline comments.
+
+## Example
+
+Code that triggers a diagnostic:
+``` cs
+[TestClass]
+public class TestClass
+{
+    // This test verifies that addition works correctly
+    [TestMethod]
+    public void TestAddition() { }
+
+    [DataTestMethod]
+    [DataRow(1, 2)] // Should add positive numbers
+    [DataRow(-1, 1)] // Should handle negative numbers
+    public void TestAdditionWithData(int a, int b) { }
+}
+```
+
+And the replacement code:
+``` cs
+[TestClass]
+public class TestClass
+{
+    [TestMethod]
+    [Description("This test verifies that addition works correctly")]
+    public void TestAddition() { }
+
+    [DataTestMethod]
+    [DataRow(1, 2, DisplayName = "Should add positive numbers")]
+    [DataRow(-1, 1, DisplayName = "Should handle negative numbers")]
+    public void TestAdditionWithData(int a, int b) { }
+}
+```
+
+## Configuration
+
+This analyzer does not offer any special configuration. The general ways of [suppressing](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings) diagnostics apply.

Philips.CodeAnalysis.Common/DiagnosticId.cs

@@ -137,5 +137,6 @@ public enum DiagnosticId
 		AvoidEmptyRegions = 2141,
 		AvoidCastToString = 2142,
 		AvoidAssemblyGetEntryAssembly = 2143,
+		UseDisplayNameOrDescription = 2146,
 	}
 }

Philips.CodeAnalysis.MsTestAnalyzers/TestShouldUseDisplayNameAnalyzer.cs

@@ -0,0 +1,143 @@
+// © 2025 Koninklijke Philips N.V. See License.md in the project root for license information.
+
+using System.Collections.Immutable;
+using System.Linq;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+using Microsoft.CodeAnalysis.Diagnostics;
+using Philips.CodeAnalysis.Common;
+
+namespace Philips.CodeAnalysis.MsTestAnalyzers
+{
+	[DiagnosticAnalyzer(LanguageNames.CSharp)]
+	public class TestShouldUseDisplayNameAnalyzer : TestMethodDiagnosticAnalyzer
+	{
+		private const string Title = @"Test should use DisplayName or Description attribute instead of comments";
+		public const string MessageFormat = @"Consider using DisplayName parameter for DataRow or Description attribute for test method instead of inline comments";
+		private const string Description = @"Using DisplayName parameter for DataRow attributes or Description attribute for test methods makes test purpose more visible in test runners and provides better documentation.";
+		private const string Category = Categories.MsTest;
+
+		private static readonly DiagnosticDescriptor Rule = new(DiagnosticId.UseDisplayNameOrDescription.ToId(), Title, MessageFormat, Category, DiagnosticSeverity.Error, isEnabledByDefault: true, description: Description);
+
+		public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics => ImmutableArray.Create(Rule);
+
+		protected override TestMethodImplementation OnInitializeTestMethodAnalyzer(AnalyzerOptions options, Compilation compilation, MsTestAttributeDefinitions definitions)
+		{
+			return new TestShouldUseDisplayName(definitions, Helper);
+		}
+
+		public class TestShouldUseDisplayName : TestMethodImplementation
+		{
+			public TestShouldUseDisplayName(MsTestAttributeDefinitions definitions, Helper helper) : base(definitions, helper)
+			{ }
+
+			protected override void OnTestMethod(SyntaxNodeAnalysisContext context, MethodDeclarationSyntax methodDeclaration, IMethodSymbol methodSymbol, bool isDataTestMethod)
+			{
+				if (isDataTestMethod)
+				{
+					CheckDataTestMethodForDisplayName(context, methodDeclaration);
+				}
+				else
+				{
+					CheckTestMethodForDescription(context, methodDeclaration);
+				}
+			}
+
+			private void CheckDataTestMethodForDisplayName(SyntaxNodeAnalysisContext context, MethodDeclarationSyntax methodDeclaration)
+			{
+				// Check for DataRow attributes with comments but no DisplayName
+				foreach (AttributeListSyntax attributeList in methodDeclaration.AttributeLists)
+				{
+					foreach (AttributeSyntax attribute in attributeList.Attributes)
+					{
+						if (Helper.ForAttributes.IsDataRowAttribute(attribute, context))
+						{
+							// Check if this DataRow has a comment but no DisplayName
+							var hasDisplayName = attribute.ArgumentList?.Arguments.Any(arg =>
+								arg.NameEquals?.Name.Identifier.ValueText == "DisplayName") == true;
+
+							if (!hasDisplayName)
+							{
+								// Look for trailing comment on the same line
+								var comment = GetTrailingComment(attribute);
+								if (!string.IsNullOrWhiteSpace(comment))
+								{
+									var diagnostic = Diagnostic.Create(Rule, attribute.GetLocation());
+									context.ReportDiagnostic(diagnostic);
+								}
+							}
+						}
+					}
+				}
+			}
+
+			private void CheckTestMethodForDescription(SyntaxNodeAnalysisContext context, MethodDeclarationSyntax methodDeclaration)
+			{
+				// Check if test method has Description attribute
+				var hasDescription = Helper.ForAttributes.HasAttribute(methodDeclaration.AttributeLists, context, MsTestFrameworkDefinitions.DescriptionAttribute, out _, out _);
+
+				if (!hasDescription)
+				{
+					// Look for leading comment before the method
+					var comment = GetLeadingComment(methodDeclaration);
+					if (!string.IsNullOrWhiteSpace(comment))
+					{
+						var diagnostic = Diagnostic.Create(Rule, methodDeclaration.Identifier.GetLocation());
+						context.ReportDiagnostic(diagnostic);
+					}
+				}
+			}
+
+			private string GetTrailingComment(AttributeSyntax attribute)
+			{
+				SyntaxToken token = attribute.GetLastToken();
+				SyntaxTrivia trivia = token.TrailingTrivia.FirstOrDefault(t => t.IsKind(SyntaxKind.SingleLineCommentTrivia));
+
+				if (trivia.IsKind(SyntaxKind.SingleLineCommentTrivia))
+				{
+					return ExtractCommentText(trivia.ToString());
+				}
+
+				return string.Empty;
+			}
+
+			private string GetLeadingComment(MethodDeclarationSyntax methodDeclaration)
+			{
+				SyntaxTriviaList leadingTrivia = methodDeclaration.GetLeadingTrivia();
+
+				// Look for single-line comment immediately before the method
+				SyntaxTrivia comment = leadingTrivia.LastOrDefault(t => t.IsKind(SyntaxKind.SingleLineCommentTrivia));
+				if (comment.IsKind(SyntaxKind.SingleLineCommentTrivia))
+				{
+					return ExtractCommentText(comment.ToString());
+				}
+
+				return string.Empty;
+			}
+
+			private string ExtractCommentText(string commentTrivia)
+			{
+				if (string.IsNullOrWhiteSpace(commentTrivia))
+				{
+					return string.Empty;
+				}
+
+				// Remove // and trim whitespace
+				var text = commentTrivia.Trim();
+				if (text.StartsWith("//"))
+				{
+					text = text.Substring(2).Trim();
+				}
+
+				// Only consider meaningful comments (more than just a few characters)
+				if (text.Length > 5)
+				{
+					return text;
+				}
+
+				return string.Empty;
+			}
+		}
+	}
+}

Philips.CodeAnalysis.Test/MsTest/TestShouldUseDisplayNameAnalyzerTest.cs

@@ -0,0 +1,183 @@
+// © 2025 Koninklijke Philips N.V. See License.md in the project root for license information.
+
+using System.Threading.Tasks;
+using Microsoft.CodeAnalysis.Diagnostics;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using Philips.CodeAnalysis.Common;
+using Philips.CodeAnalysis.MsTestAnalyzers;
+using Philips.CodeAnalysis.Test.Helpers;
+using Philips.CodeAnalysis.Test.Verifiers;
+
+namespace Philips.CodeAnalysis.Test.MsTest
+{
+	[TestClass]
+	public class TestShouldUseDisplayNameAnalyzerTest : DiagnosticVerifier
+	{
+		protected override DiagnosticAnalyzer GetDiagnosticAnalyzer()
+		{
+			return new TestShouldUseDisplayNameAnalyzer();
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task DataRowWithCommentButNoDisplayNameShouldTriggerDiagnostic()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	[DataTestMethod]
+	[DataRow(1, 2)] // Should add numbers correctly
+	public void TestAddition(int a, int b) { }
+}";
+
+			await VerifyDiagnostic(testCode, DiagnosticId.UseDisplayNameOrDescription).ConfigureAwait(false);
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task DataRowWithDisplayNameShouldNotTriggerDiagnostic()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	[DataTestMethod]
+	[DataRow(1, 2, DisplayName = ""Should add numbers correctly"")]
+	public void TestAddition(int a, int b) { }
+}";
+
+			await VerifySuccessfulCompilation(testCode).ConfigureAwait(false);
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task DataRowWithoutCommentShouldNotTriggerDiagnostic()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	[DataTestMethod]
+	[DataRow(1, 2)]
+	public void TestAddition(int a, int b) { }
+}";
+
+			await VerifySuccessfulCompilation(testCode).ConfigureAwait(false);
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task TestMethodWithCommentButNoDescriptionShouldTriggerDiagnostic()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	// This test verifies that addition works correctly
+	[TestMethod]
+	public void TestAddition() { }
+}";
+
+			await VerifyDiagnostic(testCode, DiagnosticId.UseDisplayNameOrDescription).ConfigureAwait(false);
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task TestMethodWithDescriptionShouldNotTriggerDiagnostic()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	[TestMethod]
+	[Description(""This test verifies that addition works correctly"")]
+	public void TestAddition() { }
+}";
+
+			await VerifySuccessfulCompilation(testCode).ConfigureAwait(false);
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task TestMethodWithoutCommentShouldNotTriggerDiagnostic()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	[TestMethod]
+	public void TestAddition() { }
+}";
+
+			await VerifySuccessfulCompilation(testCode).ConfigureAwait(false);
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task TestMethodWithShortCommentShouldNotTriggerDiagnostic()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	// Test
+	[TestMethod]
+	public void TestAddition() { }
+}";
+
+			await VerifySuccessfulCompilation(testCode).ConfigureAwait(false);
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task TestMethodWithBoilerplateCommentShouldNotTriggerDiagnostic()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	// TODO: implement this test
+	[TestMethod]
+	public void TestAddition() { }
+}";
+
+			await VerifySuccessfulCompilation(testCode).ConfigureAwait(false);
+		}
+
+		[TestMethod]
+		[TestCategory(TestDefinitions.UnitTests)]
+		public async Task MultipleDataRowsWithCommentsShouldTriggerDiagnostics()
+		{
+			const string testCode = @"
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClass
+{
+	[DataTestMethod]
+	[DataRow(1, 2)] // Should add positive numbers
+	[DataRow(0, 0)] // Should handle zero values
+	public void TestAddition(int a, int b) { }
+}";
+
+			await VerifyDiagnostic(testCode, DiagnosticId.UseDisplayNameOrDescription).ConfigureAwait(false);
+		}
+	}
+}