Source Generator 单元测试

2023-11-26 10:25:22

大家好，我是本期的实验室研究员——李卫涵。今天我将向大家介绍如何基于针对 Source Generator 来进行单元测试。接下来就让我们一起到实验室中一探究竟吧！

Source Generator 单元测试

Intro

Source Generator 是 .NET 5.0 以后引入的一个在编译期间动态生成代码的一个机制，介绍可以参考 C# 强大的新特性 Source Generator，但是很长时间以来 Source Generator 的测试都是有一些麻烦的，写单元测试来验证会比较麻烦，前几天参与了一个 Source Generator 相关的项目，发现微软现在有提供一套用于简化 Source Generator 单元测试的测试组件，今天我们就以两个 Source Generator 示例来介绍一下使用。

GetStarted

使用起来还算比较简单的，我平时一般用 xunit，所以下面的示例也是使用 xunit 来写单元测试，微软提供的测试组件也有针对 MsTest 和 NUnit 的，可以根据自己需要进行选择。

https://www.nuget.org/packages?q=Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing

我的项目是 xunit , 所以首先需要在测试项目中引用
Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing.XUnit 这个 NuGet 包，如果不是 xunit 选择对应的 NuGet 包即可。

如果在还原包的时候有包版本的警告可以显式指定对应包的版本来消除警告。

Sample1

首先来看一个最简单的 Source Generator 示例：

[Generator]
public class HelloGenerator : ISourceGenerator
{
    public void Initialize(GeneratorInitializationContext context)
    {
        // for debugging
        // if (!Debugger.IsAttached) Debugger.Launch();
    }

    public void Execute(GeneratorExecutionContext context)
    {
        var code = @"namespace HelloGenerated
{
  public class HelloGenerator
  {
    public static void Test() => System.Console.WriteLine(""Hello Generator"");
  }
}";
        context.AddSource(nameof(HelloGenerator), code);
    }
}

这个 Source Generator 就是一个比较简单的生成一个 HelloGenerator 的类，这个类里只有一个 Test 的静态方法，单元测试方法如下：

[Fact]
public async Task HelloGeneratorTest()
{
    var code = string.Empty;
    var generatedCode = @"namespace HelloGenerated
{
  public class HelloGenerator
  {
    public static void Test() => System.Console.WriteLine(""Hello Generator"");
  }
}";
    var tester = new CSharpSourceGeneratorTest<HelloGenerator, XUnitVerifier>()
    {
        TestState =
            {
                Sources = { code },
                GeneratedSources =
                {
                    (typeof(HelloGenerator), $"{nameof(HelloGenerator)}.cs", SourceText.From(generatedCode, Encoding.UTF8)),
                }
            },
    };

    await tester.RunAsync();
}

通常来说 Source Generator 的测试分为两部分，一部分是源代码，一部分 Generator 生成的代码。

而这个示例比较简单，其实和源代码没有关系，可以没有源代码，上面是给了一个空，也可以不配置 Sources

而 Generated Sources 则是由我们的 Generator 生成的代码。

首先我们需要创建一个 CSharpSourceGeneratorTest 有两个泛型类型，第一个是 Generator 类型，第二个是验证器，这和你使用哪个测试框架有关系，xunit 就固定是 XUnitVerifier ，在 test 中指定 TestState 中的源代码和生成的源代码，之后调用 RunAsync 方法就可以了。

上面有一个生成的示例，

第一个参数是 Generator 的类型，会根据 Generator 的类型获取生成代码的位置，

第二个参数是在 Generator 里 AddSource 时指定的名称，但是这里需要注意的是，即使指定的名称不是 .cs 结尾的需要也需要在这里添加 .cs 后缀，这个地方感觉可以优化一下，自动加 .cs 后缀。

第三个参数就是实际生成的代码了。

Sample2

接着我们来看一个稍微复杂一些的，和源代码有关系并且有依赖项。

Generator 定义如下：

[Generator]
public class ModelGenerator : ISourceGenerator
{
    public void Initialize(GeneratorInitializationContext context)
    {
        // Debugger.Launch();
        context.RegisterForSyntaxNotifications(() => new CustomSyntaxReceiver());
    }

    public void Execute(GeneratorExecutionContext context)
    {
        var codeBuilder = new StringBuilder(@"
using System;
using WeihanLi.Extensions;

namespace Generated
{
  public class ModelGenerator
  {
    public static void Test()
    {
      Console.WriteLine(""-- ModelGenerator --"");
");

        if (context.SyntaxReceiver is CustomSyntaxReceiver syntaxReceiver)
        {
            foreach (var model in syntaxReceiver.Models)
            {
                codeBuilder.AppendLine($@"      ""{model.Identifier.ValueText} Generated"".Dump();");
            }
        }

        codeBuilder.AppendLine("    }");
        codeBuilder.AppendLine("  }");
        codeBuilder.AppendLine("}");
        var code = codeBuilder.ToString();
        context.AddSource(nameof(ModelGenerator), code);
    }
}

internal class CustomSyntaxReceiver : ISyntaxReceiver
{
    public List<ClassDeclarationSyntax> Models { get; } = new();

    public void OnVisitSyntaxNode(SyntaxNode syntaxNode)
    {
        if (syntaxNode is ClassDeclarationSyntax classDeclarationSyntax)
        {
            Models.Add(classDeclarationSyntax);
        }
    }
}

单元测试方法如下：

 [Fact]
    public async Task ModelGeneratorTest()
    {
        var code = @"
public class TestModel123{}
";
        var generatedCode = @"
using System;
using WeihanLi.Extensions;

namespace Generated
{
  public class ModelGenerator
  {
    public static void Test()
    {
      Console.WriteLine(""-- ModelGenerator --"");
      ""TestModel123 Generated"".Dump();
    }
  }
}
";
        var tester = new CSharpSourceGeneratorTest<ModelGenerator, XUnitVerifier>()
        {
            TestState =
                {
                    Sources = { code },
                    GeneratedSources =
                    {
                        (typeof(ModelGenerator), $"{nameof(ModelGenerator)}.cs", SourceText.From(generatedCode, Encoding.UTF8)),
                    }
                },
        };
        // references
        // TestState.AdditionalReferences
        tester.TestState.AdditionalReferences.Add(typeof(DependencyResolver).Assembly);

        // ReferenceAssemblies
        //    WithAssemblies
        //tester.ReferenceAssemblies = tester.ReferenceAssemblies
        //    .WithAssemblies(ImmutableArray.Create(new[] { typeof(DependencyResolver).Assembly.Location.Replace(".dll", "", System.StringComparison.OrdinalIgnoreCase) }))
        //    ;
        //    WithPackages
        //tester.ReferenceAssemblies = tester.ReferenceAssemblies
        //    .WithPackages(ImmutableArray.Create(new PackageIdentity[] { new PackageIdentity("WeihanLi.Common", "1.0.46") }))
        //    ;

        await tester.RunAsync();
    }

大体上和前面的示例差不多，比较大的差异在于，这里需要处理依赖项，上面代码中提供的三种处理方式，其中 WithPackages 方式只支持 NuGet 包方式，如果是直接引用的 dll 可以使用前面两种方式来实现。

在之前的介绍文章中我们推荐在代码里添加一句 Debugger.Launch() 来调试 Source Generator，而有了单元测试之后，我们就可以不需要这个了，debug 我们的测试用例也可以调试我们的 Generator，很多时候就会比较方便，也不需要编译的时候触发选择 Debugger 了会更加高效一些，代码里可以少一些神奇的 Debugger.Launch() 了，更加推荐使用单元测试的方式来测试 Generator。

上面的第二个示例依赖项的处理，踩了好多坑，自己试了好多次都不行，Google/* 大法好。

除了上面的 WithXxx 方式，我们还可以用 AddXxx 方式，Add 是增量的方式，而 With 是完全的替换掉对应的依赖。

如果你的项目里也有用到 Source Generator，不妨试一下，上面示例的代码可以从 Github 上获取：

https://github.com/WeihanLi/SamplesInPractice/blob/master/SourceGeneratorSample/SourceGeneratorTest/GeneratorTest.cs

参考资料

https://*.com/questions/65550409/adding-reference-assemblies-to-roslyn-analyzer-code-fix-unit-tests
https://www.thinktecture.com/en/net/roslyn-source-generators-analyzers-code-fixes-testing/
https://github.com/dotnet/roslyn/blob/main/docs/features/source-generators.cookbook.md#unit-testing-of-generators
https://github.com/dotnet/roslyn-sdk/tree/main/src/Microsoft.CodeAnalysis.Testing
https://www.nuget.org/packages/Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing.XUnit/
https://github.com/WeihanLi/SamplesInPractice/blob/master/SourceGeneratorSample/SourceGeneratorTest/GeneratorTest.cs
C# 强大的新特性 Source Generator
使用 Source Generator 代替 T4 动态生成
使用 Source Generator 自动生成 WEB API

微软最有价值专家（MVP）

微软最有价值专家是微软公司授予第三方技术专业人士的一个全球奖项。28年来，世界各地的技术社区领导者，因其在线上和线下的技术社区中分享专业知识和经验而获得此奖项。

MVP是经过严格挑选的专家团队，他们代表着技术最精湛且最具智慧的人，是对社区投入极大的热情并乐于助人的专家。MVP致力于通过演讲、论坛问答、创建网站、撰写博客、分享视频、开源项目、组织会议等方式来帮助他人，并最大程度地帮助微软技术社区用户使用Microsoft技术。
更多详情请登录官方网站：https://mvp.microsoft.com/zh-cn

码农公寓

Source Generator 单元测试

Source Generator 单元测试

Intro

GetStarted

Sample1

Sample2

More

参考资料

码农公寓

Source Generator 单元测试

Intro

GetStarted

Sample1

Sample2

More

参考资料​

相关文章

参考资料