PlayNicely.Projects 1.0.4-prerelease-20240226-104112

Play Nicely Case Packer

The Play Nicely Case Packer project supports the definition and packaging (for reading or writing) of MSBuild Projects for use in release test cases. While this NuGet package can be used independently its development is a result of the Play Nicely MSBuild tools packages, e.g. NpmNpx or Sass.

Getting Started

This base package supports the definition of a TestCaseProject via a generic FileSystem interface. This interface allows for the definition of directories and files, and also the contents of those files.

The other artefacts support reading or writing of a TestCaseProject to media. At time of writing, the project supports reading from .NET assembly resources and writing to the physical file system. Implement concrete versions of IProjectPackageReader and IProjectPackageWriter if you have a specific media that you wish to support.

Defining Projects

The TestCaseProject class represents a virtual project, you can create a FileSystem by adding directories and files via the FileSystem object using it's fluent interface. You can also specify the ProjectFile from the same file system. Once defined the TestCaseProject doesn't do much on its own, but it is used by the PlayNicely.Executor package to run test cases.

var testCaseProject = new TestCaseProject("my-project");
var projectFile = testCaseProject.AddDirectory("project1")
                                 .AddFile("proj.csproj");

testCaseProject.ProjectFile = projectFile;

using(var writer = new StreamWriter(projectFile.OpenWriteStream()))
{
    writer.WriteLine("<Project Sdk=\"Microsoft.NET.Sdk\">");
    writer.WriteLine("  <PropertyGroup>");
    writer.WriteLine("    <TargetFramework>netstandard2.0</TargetFramework>");
    writer.WriteLine("  </PropertyGroup>");
    writer.WriteLine("</Project>");
}

Using Resource (resx) files

Building test case projects in code is fine, but there is already a tool to easily define and edit MSBuild projects, the IDE. To support this, Case Packer provides a IProjectPackageReader implementation for .NET resources. The basic idea is to add file resources to the resx file with names equivalent to the project file structure. The ResourceSetPackageReader can then be used to read a package into a test case project, including the file contents.

Example

If you have the following project structure...

solution-dir
|-- my-project.Specs           # BDD Specifications for your project
|   |-- TestCases.Projects     # Define your test case 'packages' in resx files
|       |-- Project1.resx
|-- TestCase.Projects          # Define your test case projects in here using familiar tools.
|   |-- Project1
|       |-- Project1.csproj
|       |-- Program.cs
|-- my-solution.sln

The .resx file should have the following resources defined

<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="Project1/Project1.csproj" type="System.Resources.ResXFileRef, System.Windows.Forms">
    <value>Project1/Project1.csproj;System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089;utf-8</value>
  </data>
  <data name="Project1/Program.cs" type="System.Resources.ResXFileRef, System.Windows.Forms">
    <value>Project1/Program.cs;System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089;utf-8</value>
  </data>
</root>

And then to load these resources into a TestCaseProject you can...

internal static class TestCases
{
    // Where projectName is the same as the resx file name without the extension
    public static async Task<TestCaseProject> LoadAsync(string projectName, CancellationToken cancel)
    {
        ArgumentException.ThrowIfNullOrEmpty(projectName);
        cancel.ThrowIfCancellationRequested();

        var resourceManager = new ResourceManager($"{ResourceNamespace}.{projectName}", ResourceAssembly);

        using var resourceSet = resourceManager.GetResourceSet(CultureInfo.InvariantCulture, true, true)
            ?? throw new TestCaseException(string.Format(ContentRes.Error_ProjectNameDoesNotExist, projectName));
        using var reader = new ResourceSetBlobReader(resourceSet);

        var result = new TestCaseProject(projectName);

        await result.LoadFromAsync(reader, cancel);
        cancel.ThrowIfCancellationRequested();

        return result;
    }

    public static Assembly ResourceAssembly => _resourceAssembly.Value;
    public static string ResourceNamespace => _resourceNamespace.Value;

    private static readonly Lazy<Assembly> _resourceAssembly = new(() => typeof(TestCases).Assembly);
    private static readonly Lazy<string> _resourceNamespace = new(() => typeof(TestCases).Namespace ?? string.Empty);
}