Writing and running NUnit tests for .NET Core projects

comments

What is actual state of .NET Core development for those who write NUnit tests?

Can we write cross-platform applications testing them with NUnit?

Is there are project templates like xUnit has?

Is there a tooling support for NUnit on par with xUnit and MSTest?

Couple days ago I asked myself these three questions. Here I'll show the results of exploration on the first day of summer 2017.

Post will contain many links, they are here just for me for memory.

.NET Core project system

There was some perturbations in .NET Core tooling world.

Initially .NET Core team implemented package.json-based project system . Many efforts the community made to implement tooling support for this ecosystem (test runners, IDE tooling etc). Rob Prouse written post about using dotnet-test-nunit package to support running NUnit tests with dotnet test command. This test runner can run your NUnit tests if you have package.json-based project.

Then .NET Core team decided to throw away package.json-based projects (they are deprecated now) in favor to well-known MSBuild-based format (aka csproj). Good news, they are simplified csproj files significantly. Bad news, all the tooling for package.json projects will not work with it (like dotnet-test-nunit) and will never be updated in future.

To the future, when you start writing a new project, choose csproj-based project.

NUnit support for .NET Core

To support .NET Core, libraries should be targeted to .NET Core App or .NET Standard. .NET Standard is promising, all new cross-platform development should be targeted to it.

.NET Standard 1.6 and lower has many missing parts. .NET Standard 2 will be released in the fall and will implement many familiar APIs to the place. You can try now .NET Standard 2 preview, the future is at hand. I tried it and was pleasantly surprised that I can now use XslCompiledTransform class in .NET Core!

NUnit has been targeted to run in .NET Core (DNX, actually) since start and to .NET Standard 1.6 since v3.6.0. You can use latest version and be confident it will work with .NET Core.

NUnit Test Project Template

There is xUnit Test Project template for dotnet new command out of the box. There was efforts to implement such support for NUnit too, PR was merged by .NET Core CLI team. But since then dotnet new command has changed its templating engine and the team forgot to create new templates for NUnit.

Fortunately, that's was not so hard to add similar project template for NUnit. I've created github repository and nuget package NUnit3.DotNetNew.Template. It is mostly based on xUnit Test Project template from dotnet/cli repository.

To install this NUnit Test Project template you can run:

dotnet new -i NUnit3.DotNetNew.Template

Get additional info is as easy as:

> dotnet new nunit -h

NUnit 3 Test Project (C#)
Description: A project that contains NUnit tests that can run on .NET Core on Windows, Linux and macOS
Options:
  -f|--framework    The target framework for the project.
                        netcoreapp1.0    - Target netcoreapp1.0
                        netcoreapp1.1    - Target netcoreapp1.1
                        netcoreapp2.0    - Target netcoreapp2.0
                    Default: netcoreapp2.0

  -p|--enable-pack  Whether or not to enable packaging (via ("dotnet pack") for the project.
                    bool - Optional
                    Default: false

  --no-restore      If specified, skips the automatic restore of the project on create.
                    bool - Optional
                    Default: false

To create new NUnit Test Project, simply run:

dotnet new nunit

Running NUnit tests

There is dotnet test command to running unit tests. This command will work with Visual Studio Test Runner Adapters which targeted to .NET Standard or .NET Core App. There is efforts to do this for NUnit, NUnit3TestAdapter v3.8.0-alpha1 now has .NETCoreApp 1.0 targeting and can be used with dotnet test command.

To add such support for your test project you should add following packages to your csproj:

<ItemGroup>
    <PackageReference Include="nunit" Version="3.7.0" />
    <PackageReference Include="NUnit3TestAdapter" Version="3.8.0-*" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.0.0" />
</ItemGroup>

Now we can run our tests:

> dotnet test
Build started, please wait...
Build completed.

Test run for tests.dll (.NETCoreApp,Version=v2.0)
Microsoft (R) Test Execution Command Line Tool Version 15.3.0-preview-20170502-03
Copyright (c) Microsoft Corporation.  All rights reserved.

Starting test execution, please wait...
NUnit Adapter 3.8.0.0: Test execution started
Running all tests in tests.dll
NUnit3TestExecutor converted 1 of 1 NUnit test cases
NUnit Adapter 3.8.0.0: Test execution complete

Total tests: 1. Passed: 1. Failed: 0. Skipped: 0.
Test Run Successful.
Test execution time: 1.4135 Seconds

Continuous testing

There is promising dotnet watch tool which will run dotnet build or dotnet test command when files are get changed. To add support for this tool, add these lines to your csproj:

<ItemGroup>
 <DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="1.0.1" />
</ItemGroup>

Note that Watcher Tool v2.0.0 preview already exists. You can use it if you targeted to .NET Standard 2 or to .NET Core App 2.

Try it out! Below I have one passing test then I have changed it to fail. Watcher rebuilds project and rerun all the tests. We see that second run has one failed test, watcher works just like Swiss clock :)

> dotnet watch test
watch : Started
Build started, please wait...
Build completed.

Test run for tests.dll(.NETCoreApp,Version=v2.0)
Starting test execution, please wait...
NUnit Adapter 3.8.0.0: Test execution started
Running all tests in tests.dll
NUnit3TestExecutor converted 1 of 1 NUnit test cases
NUnit Adapter 3.8.0.0: Test execution complete

Total tests: 1. Passed: 1. Failed: 0. Skipped: 0.
Test Run Successful.
Test execution time: 1.4240 Seconds
watch : Exited
watch : Waiting for a file to change before restarting dotnet...
watch : Started
Build started, please wait...
Build completed.

Starting test execution, please wait...
NUnit Adapter 3.8.0.0: Test execution started
Running all tests in tests.dll
NUnit3TestExecutor converted 1 of 1 NUnit test cases
NUnit Adapter 3.8.0.0: Test execution complete
Failed   Test1
Stack Trace:
at Tests.Tests.Test1() in /home/hal/git/tests/UnitTest1.cs:line 15

Total tests: 1. Passed: 0. Failed: 1. Skipped: 0.
Test Run Failed.
Test execution time: 1.4234 Seconds
watch : Exited with error code 1
watch : Waiting for a file to change before restarting dotnet...

Conclusion

Despite preview status of the .NET Core 2, .NET Standard 2 and NUnit3TestAdapter, I think that the tooling is ready for real tasks. I'm glad to see that with .NET Standard 2 targeting I can compile my friend's reflection-heavy project without any change of source code! Now we can fully use NUnit tests for .NET Core projects, and we have same tooling support like other unit-tests frameworks supported by Microsoft.

Happy testing!

Comments