PlayNicely.Executor 1.0.2-beta-227

This is a prerelease version of PlayNicely.Executor.
There is a newer version of this package available.
See the version list below for details.
dotnet add package PlayNicely.Executor --version 1.0.2-beta-227                
NuGet\Install-Package PlayNicely.Executor -Version 1.0.2-beta-227                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="PlayNicely.Executor" Version="1.0.2-beta-227" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add PlayNicely.Executor --version 1.0.2-beta-227                
#r "nuget: PlayNicely.Executor, 1.0.2-beta-227"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install PlayNicely.Executor as a Cake Addin
#addin nuget:?package=PlayNicely.Executor&version=1.0.2-beta-227&prerelease

// Install PlayNicely.Executor as a Cake Tool
#tool nuget:?package=PlayNicely.Executor&version=1.0.2-beta-227&prerelease                

Play Nicely Executor

The Play Nicely Executor project depends on the PlayNicely.Projects package, extending it to support execution of programs, against test case projects, within a pre-defined environment. Executor then collects program output so that test assertion can be made.

The Executor package, provides a fluent interface to define an ITestEnvironment, within which, some programs can be defined as unavailable, other programs as required. A test environment can also define what NuGet package sources are available, so that BDD projects can test new functionality. If a test case project is specified, the file system of that project will be 'materialized' and the working directory for the executed process.

Getting Started

The main artefacts are the ITestEnvironment, TestEnvironmentBuilder, and ITestEnvironmentRunner. An ITestEnvironment specifies the target project and ensures a side effect free environment in which any testing can run. You create an ITestEnvironment using the fluent interface of TestEnvironmentBuilder. With this class you define the desired context for your ITestEnvironmentRunner.

Tests run using the ITestEnvironmentRunner, this package defines a basic ProcessRunner which runs an executable with arguments, much like a command line, and returns a basic ExecutionResult, which includes whether the command succeeded and the stdout and stderr streams. The DotNetRunner class, defined in PlayNicely.Executor.DotNet executes a dotnet subcommand, with arguments, and returns a ExecutionResult<DotNetExecutionContext>. This includes detailed information about the dotnet command results, build context, targets ran, projects built, lists of errors, etc.

If you have a specific process you'd like to support, you can define a concrete implementation derived from ITestEnvironmentRunner.

Getting Started

Here we are using the generic ProcessRunner to execute a dotnet build process on a pre-defined test case project, within a side effect free test environment. The purpose of this getting started is to demonstrate how to set up a test environment, execute a runner and assert the result.

ℹ️ I'm using ProcessRunner here with dotnet to illustrate getting started. The PlayNicely.Executor.DotNet package provides a specific implementation for dotnet that includes important context information after execution. If you are running dotnet tests, we recommend using that runner instead.

This getting started is code-first, in a typical configuration you would likely use the IDE to define test case projects and SpecFlow (or some other BDD framework) to define the environment.

Define the test case project

Let's build a scenario to test for a failing build, because the .NET target framework is invalid. First, define the test case project and file system.

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

testCaseProject.ProjectFile = projectFile;

using(var writer = new StreamWriter(projectFile.OpenWriteStream())
{
    writer.WriteLine("<Project Sdk=\"Microsoft.NET.Sdk\">");
    writer.WriteLine("  <PropertyGroup>");
    // Note invalid target framework...
    writer.WriteLine("    <TargetFramework>my-net9.0</TargetFramework>");
    writer.WriteLine("  </PropertyGroup>");
    writer.WriteLine("</Project>");
}

Define the environment

Use the TestEnvironmentBuilder to specify:

  • RequiredCommands - any command that must be available in the test environment. Using this method ensures commands can always be executed, by finding them in the current $PATH, and creating a temporary bin directory with symbolic links to the actual executables. This bin directory is prepended to the $PATH in the subsequent environment. On Windows this is less likely to be required, but on Linux, most commands are in shared directories like /usr/bin or /usr/local/bin, if something is excluded (see next bullet point), by removing one of these paths, it is likely to exclude a lot of other commands, RequiredCommands ensures the essential commands can still be executed from the $PATH.
  • ExcludeCommandFromPath - it is often neccesary, in a negative test case, to assume a program is not installed. This method locates a command on the current $PATH and removes any directories where it is found. The result of this, when running in the ITestEnvironment is that any attempt to run an excluded command will fail (because it isn't found on the $PATH).
  • AddPackageSource - often, the usage of this package is to test another NuGet package project. So that the test environment can run release tests using the under development version of a package, this method allows overriding NuGet.Config in the test environment. When attempting to locate packages, dotnet will only look in these locations.
  • SetProject - the target project for this test environment, the project's file system will be materialized and set as the working directory for the process.
Example for clarity

Continuing context from here. We need to ensure dotnet is always available, and specify the test case target project.

var builder = new TestEnvironmentBuilder();
var testEnv = await builder.RequiredCommands("dotnet")
                           .SetProject(testCaseProject)
                           .BuildAsync();

Run the test

With the environment built, simply construct the runner and assert the result (which we expect to fail).

var runner = new ProcessRunner("dotnet", "build"); // Don't need to specify project path,
                                                   // process working dir is root of project
var testResult = await runner.ExecuteAsync(testEnv);

Assert.That(testResult.Succeeded, Is.False);

Why?

This project came about to support the use of NodeJS packages within .NET projects in a .NET first way. You can achieve the integration of NodeJS tools using plugins or other tooling. The problem with this (using plugins) is, these can often become out of date or stale. Most of the NodeJS packages are developed by an actively community, so accessing the latest npm packages directly makes the most sense (we get latest features and security updates).

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on PlayNicely.Executor:

Package Downloads
PlayNicely.Executor.DotNet

A framework that facilitates testing of Play Nicely functionality. Provides capability to execute dotnet commands, in a controlled environment, against test case projects.

PlayNicely.SpecFlow.Executor

SpecFlow bindings that allow you to run tests by executing programs against a pre-configured test environment.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.3.2-beta-550 97 4 months ago
1.3.2-beta-543 102 4 months ago
1.3.2-beta-535 106 4 months ago
1.3.2-beta-529 98 4 months ago
1.3.2-beta-518 113 4 months ago
1.3.2-beta-511 97 4 months ago
1.3.2-beta-509 103 4 months ago
1.3.2-beta-507 92 4 months ago
1.3.2-beta-505 99 4 months ago
1.3.2-beta-501 109 4 months ago
1.3.2-beta-499 101 4 months ago
1.3.2-beta-496 105 4 months ago
1.3.2-beta-494 110 4 months ago
1.3.2-beta-492 123 4 months ago
1.3.1 158 4 months ago
1.3.1-beta-487 114 4 months ago
1.3.0 144 4 months ago
1.3.0-beta-479 112 4 months ago
1.3.0-beta-472 126 4 months ago
1.2.0 121 6 months ago
1.2.0-beta-465 127 5 months ago
1.2.0-beta-450 111 6 months ago
1.2.0-beta-442 111 6 months ago
1.1.1 146 8 months ago
1.1.1-beta-432 108 6 months ago
1.1.1-beta-418 119 8 months ago
1.1.1-beta-398 117 8 months ago
1.1.0 288 9 months ago
1.1.0-beta-393 121 8 months ago
1.1.0-beta-382 134 8 months ago
1.1.0-beta-370 104 9 months ago
1.1.0-beta-355 125 9 months ago
1.1.0-beta-349 125 9 months ago
1.1.0-beta-346 129 9 months ago
1.1.0-beta-340 134 9 months ago
1.1.0-beta-323 127 9 months ago
1.1.0-beta-312 129 9 months ago
1.1.0-beta-299 124 9 months ago
1.1.0-beta-296 136 9 months ago
1.0.4 178 9 months ago
1.0.4-beta-287 126 9 months ago
1.0.4-beta-282 139 9 months ago
1.0.4-beta-280 136 9 months ago
1.0.4-beta-278 135 9 months ago
1.0.4-beta-276 123 9 months ago
1.0.4-beta-274 145 9 months ago
1.0.4-beta-272 135 9 months ago
1.0.3 176 3/21/2024
1.0.3-beta-266 133 3/21/2024
1.0.3-beta-260 131 3/21/2024
1.0.2 197 3/10/2024
1.0.2-prerelease-20240301-0... 123 3/1/2024
1.0.2-beta-227 131 3/10/2024
1.0.2-beta-221 143 3/9/2024
1.0.2-beta-214 133 3/9/2024
1.0.2-beta-208 139 3/1/2024
1.0.2-beta-206 129 3/1/2024
1.0.1 129 2/29/2024
1.0.1-prerelease-20240229-1... 96 2/29/2024
1.0.1-prerelease-20240228-0... 98 2/28/2024
1.0.1-prerelease-20240226-1... 54 2/26/2024
1.0.1-prerelease-20240225-0... 60 2/25/2024
1.0.1-prerelease-20240225-0... 58 2/25/2024
1.0.0 501 2/10/2024
1.0.0-prerelease-20240210-1... 257 2/10/2024
1.0.0-prerelease-20240210-1... 237 2/10/2024
1.0.0-prerelease-20240209-1... 223 2/9/2024
1.0.0-prerelease-20240209-1... 243 2/9/2024
1.0.0-prerelease-20240209-1... 240 2/9/2024