Incorrect documentation in roslyn/docs/features /source-generators.cookbook.md

[AnderssonPeter]

The Source Generators Cookbook has some outdated documentation regarding the unit testing nugets.

It contains the following:

Unit Testing of Generators

User scenario: As a generator author, I want to be able to unit test my generators to make development easier and ensure correctness.

Solution A:

The recommended approach is to use Microsoft.CodeAnalysis.Testing packages:

• Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing.MSTest
• Microsoft.CodeAnalysis.VisualBasic.SourceGenerators.Testing.MSTest
• Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing.NUnit
• Microsoft.CodeAnalysis.VisualBasic.SourceGenerators.Testing.NUnit
• Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing.XUnit
• Microsoft.CodeAnalysis.VisualBasic.SourceGenerators.Testing.XUnit

This works in the same way as analyzers and codefix testing. You add a class like the following:

using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Testing;
using Microsoft.CodeAnalysis.Testing.Verifiers;

public static class CSharpSourceGeneratorVerifier<TSourceGenerator>
    where TSourceGenerator : ISourceGenerator, new()
{
    public class Test : CSharpSourceGeneratorTest<TSourceGenerator, XUnitVerifier>
    {
        public Test()
        {
        }

        protected override CompilationOptions CreateCompilationOptions()
        {
           var compilationOptions = base.CreateCompilationOptions();
           return compilationOptions.WithSpecificDiagnosticOptions(
                compilationOptions.SpecificDiagnosticOptions.SetItems(GetNullableWarningsFromCompiler()));
        }

        public LanguageVersion LanguageVersion { get; set; } = LanguageVersion.Default;

        private static ImmutableDictionary<string, ReportDiagnostic> GetNullableWarningsFromCompiler()
        {
            string[] args = { "/warnaserror:nullable" };
            var commandLineArguments = CSharpCommandLineParser.Default.Parse(args, baseDirectory: Environment.CurrentDirectory, sdkDirectory: Environment.CurrentDirectory);
            var nullableWarnings = commandLineArguments.CompilationOptions.SpecificDiagnosticOptions;

            return nullableWarnings;
        }

        protected override ParseOptions CreateParseOptions()
        {
            return ((CSharpParseOptions)base.CreateParseOptions()).WithLanguageVersion(LanguageVersion);
        }
    }
}

Then, in your test file:

using VerifyCS = CSharpSourceGeneratorVerifier<YourGenerator>;

And use the following in your test method:

var code = "initial code";
var generated = "expected generated code";
await new VerifyCS.Test
{
    TestState = 
    {
        Sources = { code },
        GeneratedSources =
        {
            (typeof(YourGenerator), "GeneratedFileName", SourceText.From(generated, Encoding.UTF8, SourceHashAlgorithm.Sha256)),
        },
    },
}.RunAsync();

---

But the Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing.XUnit.SourceGeneratorVerifier class has been marked as obsolete:

[Obsolete("https://github.com/dotnet/roslyn-sdk/blob/main/src/Microsoft.CodeAnalysis.Testing/README.md#obsolete-packages")]

The link above tells me to use Microsoft.CodeAnalysis.CSharp.Analyzer.Testing instead.

[333fred]

The very first line of the document states:

Warning: Source generators implementing ISourceGenerator have been deprecated in favor of incremental generators. The incremental version of this document is here. You should implement IIncrementalGenerator instead of ISourceGenerator.

While we would likely accept a PR updating the content of that section, the document itself covers techniques that have been obsoleted. This isn't particularly different in that respect.

[AnderssonPeter]

The very first line of the document states:

Warning: Source generators implementing ISourceGenerator have been deprecated in favor of incremental generators. The incremental version of this document is here. You should implement IIncrementalGenerator instead of ISourceGenerator.

While we would likely accept a PR updating the content of that section, the document itself covers techniques that have been obsoleted. This isn't particularly different in that respect.

Sorry I missed the link to the cookbook for incremental generators.

But that being said the document contains the same nuget packages and examples, while I would be more than happy to provide a PR, I'm a bit unsure how to modify the first code example to use the new package.