PlayNicely.Projects 1.0.4-prerelease-20240229-103250

Play Nicely Projects

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, in these repositories.

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

This package, and others, are in use in these tools:

• 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 its 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 it would be helpful if we could define them declaritively as well. The base package supports this by defining projects in resx files and loading them into a TestCaseProject at runtime.

You would typically use this concept within the IDE, see next section, but you don't have to, you can declare the project using raw XML within a resx file.

Example

This example defines a TestCaseProject within a resx file. Using item keys and values (for the file content).

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 represent paths), and also the special ProjectFile key which sets the TestCaseProject.ProfileFile property (if present).

<?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>...Excluded for bereveity...</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>

Using the IDE

Ok, so defining test case projects in code isn't ideal, neither is creating raw resx files, ideally we want to use a familiar tool, i.e. the IDE. Rather than specify file content using raw strings, as in the example above, we can define projects in Visual Studio as normal, Add Project..., New Item..., etc., and then reference them in the resx file for packaging.

Our recomended setup for tools projects that require test cases for packaging, is to create a solution structure like this.

solution-dir
|-- Project.UnderTest.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
|-- Project.UnderTest          # The package project that needs to be tested before release
|   |-- Project.UnderTest.csproj
|   |-- SomeCode.cs
|-- solution.sln

Key points to consider:

• The Project.UnderTest is the actual payload project of this repository.
• Project.UnderTest.Specs is a BDD project that tests the capabilities of Project.UnderTest.
  • The Project1.resx resource includes the files from TestCase.Projects/Project1 directory with ResXFileRef items (see here).
• The TestCase.Projects directory is a space to define the test case projects, within the IDE. You can add new projects, new classes, interfaces, whatever you need in a familiar environment. Be aware, if this is an unhappy path test, that you need to exclude it from the solution build.

<a id="use-files-in-resx"></a>

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

Example

The best examples, are real uses, you can find them in these dependent projects.

• PlayNicely.NpmNpx
• PlayNicely.Sass