test: Add comprehensive unit tests for BUNIT0002 analyzer

Co-authored-by: linkdotnet <[email protected]>

Author: Copilot

Directory.Packages.props

@@ -102,5 +102,6 @@
 		<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.14.0"/>
 		<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.14.0"/>
 		<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing" Version="1.1.2" />
+		<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing.XUnit" Version="1.1.2" />
 	</ItemGroup>
 </Project>

docs/site/docs/extensions/bunit-analyzers.md

@@ -0,0 +1,132 @@
+---
+uid: bunit-analyzers
+title: bUnit Analyzers
+---
+
+# bUnit Analyzers
+
+The `bunit.analyzers` package contains a set of Roslyn analyzers that help identify common mistakes and anti-patterns when writing bUnit tests. The analyzers are designed to provide early feedback during development, catching issues before tests are run. To use the analyzers, install the `bunit.analyzers` NuGet package in your test project.
+
+This page describes the available analyzers and their usage.
+
+## Installation
+
+Install the package via NuGet:
+
+```bash
+dotnet add package bunit.analyzers
+```
+
+The analyzers will automatically run during compilation and provide warnings or suggestions in your IDE and build output.
+
+## Available Analyzers
+
+### BUNIT0002: Prefer Find<T> over casting
+
+**Severity**: Info  
+**Category**: Usage
+
+This analyzer detects when you cast the result of `Find(selector)` and suggests using the generic `Find<T>(selector)` method instead. Using the generic method is more concise, type-safe, and expresses intent more clearly.
+
+#### Examples
+
+**❌ Incorrect** - triggers BUNIT0002:
+```csharp
+using AngleSharp.Dom;
+
+var cut = RenderComponent<MyComponent>();
+IHtmlAnchorElement link = (IHtmlAnchorElement)cut.Find("a");
+```
+
+**✅ Correct**:
+```csharp
+using AngleSharp.Dom;
+
+var cut = RenderComponent<MyComponent>();
+var link = cut.Find<IHtmlAnchorElement>("a");
+```
+
+#### When to Use
+
+Use `Find<T>()` whenever you need a specific element type:
+- When working with AngleSharp element interfaces (`IHtmlAnchorElement`, `IHtmlButtonElement`, etc.)
+- When you need to access type-specific properties or methods
+- When you want clearer, more maintainable test code
+
+### BUNIT0001: Razor test files should inherit from BunitContext
+
+**Status**: 🚧 Planned for future release
+
+This analyzer will detect when Razor test files (`.razor` files) use variables or event callbacks from the test code without inheriting from `BunitContext`. Without the proper inheritance, you may encounter the error "The render handle is not yet assigned."
+
+#### Planned Examples
+
+**❌ Incorrect** - will trigger BUNIT0001 in the future:
+```razor
+@code
+{
+    [Fact]
+    public void Test()
+    {
+        using var ctx = new BunitContext();
+        
+        Action<MouseEventArgs> onClickHandler = _ => { Assert.True(true); };
+        
+        var cut = ctx.Render(@<MyComponent OnClick="onClickHandler" />);
+        cut.Find("button").Click();
+    }
+}
+```
+
+**✅ Correct**:
+```razor
+@inherits BunitContext
+@code
+{
+    [Fact]
+    public async Task Test()
+    {
+        var wasInvoked = false;
+        
+        Action<MouseEventArgs> onClick = _ => { wasInvoked = true; };
+        
+        var cut = Render(@<MyComponent OnClick="onClick" />);
+        var button = cut.Find("button");
+        await button.ClickAsync(new MouseEventArgs());
+        
+        cut.WaitForAssertion(() => Assert.True(wasInvoked));
+    }
+}
+```
+
+## Configuration
+
+The analyzers can be configured in your project's `.editorconfig` file or using ruleset files. For example, to change the severity of BUNIT0002:
+
+```ini
+# .editorconfig
+[*.cs]
+# Change BUNIT0002 from Info to Warning
+dotnet_diagnostic.BUNIT0002.severity = warning
+
+# Or disable it entirely
+dotnet_diagnostic.BUNIT0002.severity = none
+```
+
+## Contributing
+
+We welcome contributions! If you have ideas for additional analyzers that could help bUnit users, please:
+
+1. Check existing [issues](https://github.com/bunit-dev/bUnit/issues) for similar suggestions
+2. Open a new issue describing the problem the analyzer would solve
+3. Submit a pull request with your implementation
+
+Common areas for improvement include:
+- Detecting incorrect usage of `WaitFor` methods
+- Identifying missing or incorrect component parameter bindings
+- Catching improper service injection patterns
+- Finding opportunities to use helper methods
+
+## Feedback
+
+If you encounter issues with the analyzers or have suggestions for improvements, please [open an issue](https://github.com/bunit-dev/bUnit/issues/new) on GitHub.

docs/site/docs/extensions/index.md

@@ -7,4 +7,5 @@ title: Extensions for bUnit
 
 This section covers the various extensions available for bUnit. These extensions are not part of the core bUnit package, but are instead available as separate NuGet packages. The extensions are listed below, and each has its own documentation page.
 
+ * **[bunit.analyzers](xref:bunit-analyzers)** - A set of Roslyn analyzers that help identify common mistakes and anti-patterns when writing bUnit tests
  * **[bunit.generators](xref:bunit-generators)** - A set of source generators that can be used to generate code like stubs for Blazor components

src/bunit.analyzers/DiagnosticDescriptors.cs

@@ -5,7 +5,7 @@ namespace Bunit.Analyzers;
 /// <summary>
 /// Diagnostic descriptors for bUnit analyzers.
 /// </summary>
-internal static class DiagnosticDescriptors
+public static class DiagnosticDescriptors
 {
 	private const string Category = "Usage";
 

tests/bunit.analyzers.tests/AnalyzerTests.cs

@@ -0,0 +1,217 @@
+using System.Threading.Tasks;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Testing;
+using Xunit;
+using VerifyCS = Microsoft.CodeAnalysis.CSharp.Testing.XUnit.AnalyzerVerifier<Bunit.Analyzers.PreferGenericFindAnalyzer>;
+
+namespace Bunit.Analyzers.Tests;
+
+public class PreferGenericFindAnalyzerTests
+{
+	[Fact]
+	public async Task NoDiagnostic_WhenUsingGenericFind()
+	{
+		const string code = @"
+namespace TestNamespace
+{
+	public class TestClass
+	{
+		public void TestMethod()
+		{
+			var cut = new TestHelper();
+			var elem = cut.Find<string>(""a"");
+		}
+	}
+
+	public class TestHelper
+	{
+		public T Find<T>(string selector) => default(T);
+	}
+}";
+
+		await VerifyCS.VerifyAnalyzerAsync(code);
+	}
+
+	[Fact]
+	public async Task NoDiagnostic_WhenCastingNonFindMethod()
+	{
+		const string code = @"
+namespace TestNamespace
+{
+	public class TestClass
+	{
+		public void TestMethod()
+		{
+			var obj = new TestHelper();
+			var elem = (string)obj.GetSomething();
+		}
+	}
+
+	public class TestHelper
+	{
+		public object GetSomething() => null;
+	}
+}";
+
+		await VerifyCS.VerifyAnalyzerAsync(code);
+	}
+
+	[Fact]
+	public async Task NoDiagnostic_WhenFindIsNotFromRenderedFragment()
+	{
+		const string code = @"
+namespace TestNamespace
+{
+	public class TestClass
+	{
+		public void TestMethod()
+		{
+			var helper = new UnrelatedHelper();
+			var result = (string)helper.Find(""test"");
+		}
+	}
+
+	public class UnrelatedHelper
+	{
+		public object Find(string selector) => null;
+	}
+}";
+
+		await VerifyCS.VerifyAnalyzerAsync(code);
+	}
+
+	[Fact]
+	public async Task Diagnostic_WhenCastingFindResultFromIRenderedFragment()
+	{
+		const string code = @"
+namespace TestNamespace
+{
+	public interface IMyElement { }
+
+	public class TestClass
+	{
+		public void TestMethod()
+		{
+			var cut = new MockRenderedFragment();
+			IMyElement elem = {|#0:(IMyElement)cut.Find(""a"")|};
+		}
+	}
+
+	public interface IRenderedFragment
+	{
+		object Find(string selector);
+	}
+
+	public class MockRenderedFragment : IRenderedFragment
+	{
+		public object Find(string selector) => null;
+	}
+}";
+
+		var expected = VerifyCS.Diagnostic(DiagnosticDescriptors.PreferGenericFind.Id)
+			.WithLocation(0)
+			.WithArguments("IMyElement", "\"a\"");
+
+		await VerifyCS.VerifyAnalyzerAsync(code, expected);
+	}
+
+	[Fact]
+	public async Task Diagnostic_WhenCastingFindResultFromRenderedComponent()
+	{
+		const string code = @"
+namespace TestNamespace
+{
+	public interface IMyElement { }
+
+	public class TestClass
+	{
+		public void TestMethod()
+		{
+			var cut = new MockRenderedComponent();
+			var elem = {|#0:(IMyElement)cut.Find(""div"")|};
+		}
+	}
+
+	public interface IRenderedComponent
+	{
+		object Find(string selector);
+	}
+
+	public class MockRenderedComponent : IRenderedComponent
+	{
+		public object Find(string selector) => null;
+	}
+}";
+
+		var expected = VerifyCS.Diagnostic(DiagnosticDescriptors.PreferGenericFind.Id)
+			.WithLocation(0)
+			.WithArguments("IMyElement", "\"div\"");
+
+		await VerifyCS.VerifyAnalyzerAsync(code, expected);
+	}
+
+	[Fact]
+	public async Task Diagnostic_WhenCastingFindResultFromRenderedFragmentType()
+	{
+		const string code = @"
+namespace TestNamespace
+{
+	public interface IMyElement { }
+
+	public class TestClass
+	{
+		public void TestMethod()
+		{
+			var cut = new RenderedFragment();
+			var button = {|#0:(IMyElement)cut.Find(""button"")|};
+		}
+	}
+
+	public class RenderedFragment
+	{
+		public object Find(string selector) => null;
+	}
+}";
+
+		var expected = VerifyCS.Diagnostic(DiagnosticDescriptors.PreferGenericFind.Id)
+			.WithLocation(0)
+			.WithArguments("IMyElement", "\"button\"");
+
+		await VerifyCS.VerifyAnalyzerAsync(code, expected);
+	}
+
+	[Fact]
+	public async Task Diagnostic_WithComplexSelector()
+	{
+		const string code = @"
+namespace TestNamespace
+{
+	public interface IMyElement { }
+
+	public class TestClass
+	{
+		public void TestMethod()
+		{
+			var cut = new MockRenderedFragment();
+			var link = {|#0:(IMyElement)cut.Find(""a.nav-link[href='/home']"")|};
+		}
+	}
+
+	public interface IRenderedFragment
+	{
+		object Find(string selector);
+	}
+
+	public class MockRenderedFragment : IRenderedFragment
+	{
+		public object Find(string selector) => null;
+	}
+}";
+
+		var expected = VerifyCS.Diagnostic(DiagnosticDescriptors.PreferGenericFind.Id)
+			.WithLocation(0)
+			.WithArguments("IMyElement", "\"a.nav-link[href='/home']\"");
+
+		await VerifyCS.VerifyAnalyzerAsync(code, expected);
+	}
+}