EasyTdd 0.4.0 Release: Introducing the Incremental Builder

I'm excited to announce the release of EasyTdd 0.4.0! The major highlight of this release is the introduction of the Incremental Builder, implemented using the IIncrementalGenerator technology.

The Builder Pattern is a creational design pattern that provides a way to construct complex objects step by step. It allows for the creation of different representations of an object using the same construction process. This pattern is particularly useful in test-driven development (TDD) because it simplifies the creation of test data and makes tests more readable and maintainable by providing a clear and fluent interface for constructing test objects.

One of the biggest benefits of using a builder in TDD is the ability to predefine specific valid setups, such as "Default" or "Typical," along with other specific cases. In a test, you can use these predefined setups or modify just one or two fields as needed. This approach ensures that your tests are consistent and easy to understand, focusing on the behavior being tested rather than the details of object creation.

IIncrementalGenerator is a powerful feature in C# supported in .NET 6.0 and later. It enhances source generation by processing and updating only the parts of the code that have changed, with the code being generated in the background.

How to use it?

Let's say we have a sample class:

namespace EasyTdd.CodeSource.CodeProject1.ForIncrementalBuilder
{
    public class SampleWithGeneric<T>
        where T: class, IEnumerable
    {
        public SampleWithGeneric(T someProperty, string someString)
        {
            SomeProperty = someProperty;
            SomeString = someString;
        }

        public T SomeProperty { get; }
        public string SomeString { get; set; }
        public int SomeInt { get; set; }
        public DateTime SomeDateTime { get; set; }
    }
}

In Visual Studio with EasyTdd installed, place the cursor on the class for which you want to create a builder. Open the Quick Action menu (either by clicking the light bulb with the mouse or pressing Ctrl+. on the keyboard) and select "Generate Incremental Builder."

This action will produce a partial builder class with the BuilderFor attribute set:

namespace EasyTdd.CodeSource.CodeProject1.TestDoubles.Builders.ForIncrementalBuilder
{
    [EasyTdd.Generators.BuilderFor(typeof(SampleWithGeneric<>))]
    public partial class SampleWithGenericBuilder<T>
    {
        public static SampleWithGenericBuilder<T> Default()
        {
            return new SampleWithGenericBuilder<T>(
                () => default, // Set default someProperty value
                () => default, // Set default someString value
                () => default, // Set default someInt value
                () => default  // Set default someDateTime value
            );
        }
    }
}

This file is where the default and other known setups of the class can be defined. The templates only define the "default" setup, so feel free to change the default values and define as many setups as you need. This file is protected from regeneration and will not be affected by changes in the target class.

namespace EasyTdd.CodeSource.CodeProject1.TestDoubles.Builders.ForIncrementalBuilder
{
    [EasyTdd.Generators.BuilderFor(typeof(SampleWithGeneric<>))]
    public partial class SampleWithGenericBuilder<T>
    {
        public static SampleWithGenericBuilder<T> Default()
        {
            return new SampleWithGenericBuilder<T>(
                () => default,
                () => "",
                () => 0, 
                () => DateTime.Now
            );
        }
        public static SampleWithGenericBuilder<T> SomeSpecificCase(T value)
        {
            return new SampleWithGenericBuilder<T>(
                () => value,
                () => "some specific string",
                () => 782,
                () => DateTime.Parse("2024-05-20")
            );
        }
    }
}

The rest of the class is generated by Roslyn, the .NET compiler platform. You can see the outcome by pressing F12 (or checking Edit > Go To Definition if your shortcut scheme has changed) on the SampleWithGenericBuilder<T>:

The code in SampleWithGenericBuilder.g.cs looks as following:

namespace EasyTdd.CodeSource.CodeProject1.TestDoubles.Builders.ForIncrementalBuilder
{
    public partial class SampleWithGenericBuilder<T>
        where T : class, System.Collections.IEnumerable
    {
        private Func<T> _someProperty;
        private Func<string> _someString;
        private Func<int> _someInt;
        private Func<System.DateTime> _someDateTime;

        public static implicit operator EasyTdd.CodeSource.CodeProject1.ForIncrementalBuilder.SampleWithGeneric<T>(SampleWithGenericBuilder<T> builder) => builder.Build();

        public SampleWithGenericBuilder(
            Func<T> someProperty,
            Func<string> someString,
            Func<int> someInt,
            Func<System.DateTime> someDateTime)
        {
            _someProperty = someProperty;
            _someString = someString;
            _someInt = someInt;
            _someDateTime = someDateTime;
        }

        public SampleWithGenericBuilder(
            T someProperty,
            string someString,
            int someInt,
            System.DateTime someDateTime)
        {
            _someProperty = () => someProperty;
            _someString = () => someString;
            _someInt = () => someInt;
            _someDateTime = () => someDateTime;
        }

        public EasyTdd.CodeSource.CodeProject1.ForIncrementalBuilder.SampleWithGeneric<T> Build()
        {
            return new EasyTdd.CodeSource.CodeProject1.ForIncrementalBuilder.SampleWithGeneric<T>(
                _someProperty(),
                _someString())
            {
                SomeInt = _someInt(),
                SomeDateTime = _someDateTime()
            };
        }

        public SampleWithGenericBuilder<T> WithSomeProperty(Func<T> value)
        {
            _someProperty = value;
            return this;
        }

        public SampleWithGenericBuilder<T> WithSomeProperty(T value)
        {
            return WithSomeProperty(() => value);
        }

        public SampleWithGenericBuilder<T> WithSomeString(Func<string> value)
        {
            _someString = value;
            return this;
        }

        public SampleWithGenericBuilder<T> WithSomeString(string value)
        {
            return WithSomeString(() => value);
        }

        public SampleWithGenericBuilder<T> WithSomeInt(Func<int> value)
        {
            _someInt = value;
            return this;
        }

        public SampleWithGenericBuilder<T> WithSomeInt(int value)
        {
            return WithSomeInt(() => value);
        }

        public SampleWithGenericBuilder<T> WithSomeDateTime(Func<System.DateTime> value)
        {
            _someDateTime = value;
            return this;
        }

        public SampleWithGenericBuilder<T> WithSomeDateTime(System.DateTime value)
        {
            return WithSomeDateTime(() => value);
        }
    }
}

I want to note that generic constraints are added automatically. The generator takes into account which properties are set using the constructor and which have only setter properties.

Usage of the builder

The beauty and power of the builder pattern lie in its flexibility and simplicity. When using a builder, I do not need to specify all the properties—only the ones relevant to a test—even when the constructor of the type is complex and requires many fields to be set. This makes the builder especially useful in scenarios where the type has a heavy constructor with numerous parameters. By using a builder, I can create objects with only the necessary properties, making my tests more focused and easier to read. This approach not only reduces boilerplate code but also enhances the maintainability and clarity of the test suite.

public void Demo()
{
    var orderSample = SampleWithGenericBuilder<List<Order>>
        .SomeSpecificCase(new List<Order>())
        .WithSomeString("Order list case");

    var defaultSample = SampleWithGenericBuilder<List<Item>>
        .Default();

    var listOfSamples = new List<SampleWithGenericBuilder<List<Item>>>
    {
        SampleWithGenericBuilder<List<Item>>
            .Default()
            .WithSomeInt(1),
        SampleWithGenericBuilder<List<Item>>
            .Default()
            .WithSomeInt(2),
        SampleWithGenericBuilder<List<Item>>
            .Default()
            .WithSomeInt(3),
        SampleWithGenericBuilder<List<Item>>
            .Default()
            .WithSomeInt(4),
    };
}

How it works?

The solution consists of three parts: EasyTdd, the Visual Studio extension itself; the settings and template files; and the EasyTdd.Generators NuGet package. When you click "Generate Incremental Builder," EasyTdd considers the settings to determine where the builder needs to be placed, creates the file, and renders the content using a template specified in the settings. If the EasyTdd.Generators NuGet package is not already installed in the target project, EasyTdd installs it. EasyTdd.Generators contains the logic to create the BuilderFor attribute class and generate the builder class for a type defined in the BuilderFor parameter. The rest is accomplished by Roslyn, the .NET compiler platform.

Configuration

The default placement, naming, and location of the generated builder may not suit everyone's preferences and requirements. Fortunately, all of these aspects can be easily customized to better align with your needs and tastes. Now, I will provide the settings one by one. Settings for the incremental builder, as well as for all other tools, are located in the settings.json file under the IncrementalTestDoubleForConcrete section. Here are the descriptions:

• ClassSuffix: The default value is Builder. This value determines the suffix added to the target class's corresponding builder class name. In the previous example, for SampleWithGeneric, the builder class name was SampleWithGenericBuilder.

• NameInMenu: The default value is Generate Incremental Builder. This setting allows you to modify the name displayed in the Quick Actions menu. By default, it is Generate Incremental Builder, but you can rename it to whatever you prefer.

• AssemblySpecificTargetProjectSuffix: The default value is TestDoubles. This setting instructs EasyTdd to place the generated builder in a project corresponding to the project of the target class. It searches for a project with the same name plus the predefined suffix. For example, if SampleWithGeneric is in the project EasyTdd.CodeSource.CodeProject1, the corresponding project for the builder would be EasyTdd.CodeSource.CodeProject1.TestDoubles. This can be customized to suit individual preferences and requirements, such as using a different suffix for the test doubles project. Within the test doubles project, EasyTdd maintains the original folder hierarchy.

• TargetProjectNameForAssembliesWithoutSpecificTargetProject: The default value is null. This setting specifies a project name where a test double will be placed when the project of a target class doesn't have a corresponding test double project. For example, if you want to place all test doubles from all projects into a single test doubles project called EasyTdd.CodeSource.TestDoubles, you would set this setting to EasyTdd.CodeSource.TestDoubles. In this case, you can leave AssemblySpecificTargetProjectSuffix with its default value, as EasyTdd will first try to find a project with the predefined suffix and then fall back to the value in TargetProjectNameForAssembliesWithoutSpecificTargetProject if it doesn't find one. If EasyTdd doesn't locate the project specified in TargetProjectNameForAssembliesWithoutSpecificTargetProject, it will place the test double class next to the target class.

• Folder: The default value is Builders. This setting allows you to organize test doubles, such as builders and mocks, into corresponding folders. For example, if you choose to have a single project for all test doubles and set TargetProjectNameForAssembliesWithoutSpecificTargetProject to EasyTdd.CodeSource.TestDoubles and Folder to "Builders," then the builder for EasyTdd.CodeSource.CodeProject1\Models\SampleWithGeneric.cs will be placed in EasyTdd.CodeSource.TestDoubles\Builders\CodeProject1\Models\SampleWithGeneric.cs.

• FileTemplates: This section contains settings for the specific files that will be generated.

  • NameTemplate: The default value is {{className}}.cs for the EasyTdd-generated part, and {{className}}.g.cs for the EasyTdd.Generators-generated part. Here, className refers to the name of the builder class.
  • ContentTemplateFile: The default value for the EasyTdd-generated part is DefaultTemplates\incremental.builder.tpl. The default value for the EasyTdd.Generators part is DefaultTemplates\incremental.builder.g.tpl.
  • Recreate: Files marked with true are generated by the incremental generator, EasyTdd.Generators, while files marked with false are generated by the EasyTdd Visual Studio extension. The files generated by EasyTdd are intended for modifications, such as builder setups. In contrast, the files generated by EasyTdd.Generators will be regenerated whenever changes are made to the target class.

• ToolingNamespaces: By default, this contains a list of namespaces to support the tooling used in the default test template. EasyTdd adds target class-related namespaces to the generated class, but it is not aware of the tooling used in the template itself. This is where you can define those namespaces. By default, the System namespace is added to support Func in the template.

Feel free to update the templates to match your taste and needs. Remember to copy and paste them outside of the DefaultTemplates folder, as the templates in this folder are overridden with each new release.

Summary

In this blog post, I introduced the new version of EasyTdd. This new version includes a powerful tool—the incremental builder—which is automatically updated whenever the target class changes. The code generation is highly configurable and easily changeable, allowing you to tailor it to your specific needs. Additionally, I discussed how the builder pattern and IIncrementalGenerator enhance the test-driven development experience by streamlining the creation of test data and improving build performance. This tool takes types with generic parameters into account and works seamlessly with classes where values are set using constructors, setter properties, or a mix of both. With these new features, EasyTdd offers a more efficient and scalable approach to managing test doubles and supporting large projects.