PlayNicely.Projects 1.0.4-prerelease-20240228-095702

Play Nicely Projects

The Play Nicely Projects supports the definition and packaging (for reading or writing) of MSBuild Projects. These projects can be used to release test NuGet tool projects that you may be developing. This package provides foundation artefacts for tool project testing, however, the actual test execution code and supporting BDD extensions are developed separately.

• PlayNicely.Executor
• PlayNicely.Executor.DotNet
• PlayNicely.SpecFlow.Executor
• PlayNicely.SpecFlow.DotNet

In use in these tools packages:

• PlayNicely.NpmNpx
• PlayNicely.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 this time, 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 define a FileSystem by adding directories and files 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 when combined with PlayNicely.Executor, or other dependent packages, it can have commands executed against it and any output collected for assertions.

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, Projects provides a IProjectPackageReader implementation for .NET resources. The basic idea is to add files to the resx 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 want a TestCaseProject with the following structure...

solution-dir
|-- Project1
|   |-- Project1.csproj
|   |-- Program.cs
|-- Project2
|   |-- Project2.csproj
|   |-- Program.cs
|   |-- Consts.cs
|-- my-solution.sln

The .resx file should have the following resources defined (note the item keys).

<?xml version="1.0" encoding="utf-8"?>
<root>
  
  <data name="ProjectFile" xml:space="preserve">
    <value>my-solution.sln</value>
  </data>
  <data name="my-solution.sln" xml:space="preserve">
    <value></value>
  </data>

  <data name="Project1/Project1.csproj" xml:space="preserve">
    <value>
&lt;Project Sdk="Microsoft.NET.Sdk"&gt;
  &lt;PropertyGroup&gt;
    &lt;TargetFramework&gt;net6.0&lt;/TargetFramework&gt;
  &lt;/PropertyGroup&gt;
&lt;/Project&gt;
    </value>
  </data>
  <data name="Project1/Program.cs" xml:space="preserve">
    <value>
using System;

namespace Project1
{
    public static class Program
    {
        public static int Main(params string[] args)
        {
            Console.WriteLine("Project1");

            return 0;
        }
    }
}
    </value>
  </data>

  <data name="Project2/Project2.csproj" xml:space="preserve">
    <value>
&lt;Project Sdk="Microsoft.NET.Sdk"&gt;
  &lt;PropertyGroup&gt;
    &lt;TargetFramework&gt;net6.0&lt;/TargetFramework&gt;
  &lt;/PropertyGroup&gt;
&lt;/Project&gt;
    </value>
  </data>
  <data name="Project2/Program.cs" xml:space="preserve">
    <value>
using System;

namespace Project1
{
    public static class Program
    {
        public static int Main(params string[] args)
        {
            Console.WriteLine("Project2: {0}", Consts.Version);

            return 0;
        }
    }
}
    </value>
  </data>
  <data name="Project2/Consts.cs" xml:space="preserve">
    <value>
using System;

namespace Project1
{
    public static class Consts
    {
        public const string Version = "1.2.3";
    }
}
    </value>
  </data>
</root>

Note the special key ProjectFile which defines the TestCaseProject.ProjectFile path.

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 (note the item keys).

<?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);
}