Using xUnit with ASP.NET Core

Writing tests for ASP.NET Core applications can be done using xUnit. xUnit works on both.NET Framework and .NET Core. This post shows how to set up and use xUnit with ASP.NET Core applications in Visual Studio and on command-line. Targeting multiple frameworks is also covered.

Adding xUnit to solution

ASP.NET Core solution with test projectFor automated testing we need a project with reference to our favorite testing framework. For this post it’s xUnit. We have default ASP.NET Core project and one additional project for tests like shown on screenshot on right.

We want to run xUnit tests from command line using dotnet utility and we would also like to use Visual Studio Test Explorer for running tests in dev boxes. For this we have to add the following package references to project.json file of tests project:

  • xunit
  • xunit.runner.dnx
  • dotnet-test-xunit

In the beginning of project.json file we also have to specify the test runner to use. For this there’s testRunner attribute. Here’s my current project.json.


{
 
“version”: “1.0.0-*”
,
  “testRunner”: “xunit”
,

  “dependencies”: {
   
“Microsoft.NETCore.App”
: {
     
“version”: “1.0.1”
,
     
“type”: “platform”
    },
   
“xunit”: “2.1.0”
,
   
“xunit.runner.dnx”: “2.1.0-rc1-build204”
,
   
“dotnet-test-xunit”: “2.2.0-preview2-build1029”
,
   
“AdvancedAspNetCore.Testing”: “1.0.0”
,
   
“System.Runtime”: “4.1.0”
  },

  “frameworks”: {
   
“netcoreapp1.0”
: {
     
“imports”
: [
       
“dnxcore50”
,
       
“portable-net45+win8”
      ]
    }
  }
}


In dependencies section there is also reference to web application projectection. More about project.json can be found from project.json reference.

Writing simple tests

Now let’s write some simple dummy tests. I don’t focus here on what to test and how to do it in real scenarios. Here I just want to show how things work. So, here is my simple and primitive test class.


using System;
using AdvancedAspNetCore.Testing.Controllers;
using Microsoft.AspNetCore.Mvc;
using Xunit;

namespace AdvancedAspNetCore.Testing.Tests
{
   
public class HomeControllerTests
    {
       
public
HomeControllerTests()
        {
        }

        [Fact(DisplayName = “Index should return default view”)]
       
public void
Index_should_return_default_view()
        {
           
var controller = new HomeController
();
           
var viewResult = (ViewResult
)controller.Index();
           
var
viewName = viewResult.ViewName;

            Assert.True(string.IsNullOrEmpty(viewName) || viewName == “Index”);
        }

        [Fact(DisplayName = “Failing test”)]
       
public void
ShouldFail()
        {
           
throw new NotImplementedException();
        }
    }
}


The first test checks if Index() method of home controller returns view with empty name or with name “Index”. Second test just fails immediately with exception.

Running tests in Visual Studio

To run tests in Visual Studio we select Tests from top menu and then Run and All Tests like shown on image below.

Visual Studio: Running tests

Visual Studio Test ExplorerVisual Studio opens test explorer window and displays test results there. Test Explorer groups tests under failed and passed tests. If more information is needed about failed test then it’s possible to click on failed test to see exception or failed assertion and stack trace.

Note how Test Explorer is using nice names for tests. In code above we used DisplayName parameter with Fact attribute and this is where nice names of tests are taken.

Running xUnit tests on command-line

When building application on build server or some CI server or – why not – in Linux we want to run tests on command-line. For this we can use dotnet utility. To run tests on command-line we open console and move to tests project folder. There we run the following command:

dotnet test

It produces console output like this:

Running xUnit tests on command-line

It’s perhaps good enough if we run tests manually and read the results but it’s not enough if we want to get out something that is okay for reporting. This is specially the case with CI servers with web interface. We are lucky because xUnit supports also XML-output. All we need is the following command:

dotnet test –xml results.xml

As a result we get same console output but results are also written to results.xml file. Here’s the content of this file in our case.


<?xml version=1.0 encoding=utf-8?>
<
assemblies
>
  <
assembly name=AdvancedAspNetCore.Testing.Tests.dll 
           
environment=64-bit .NET (unknown version) [collection-per-class, parallel (4 threads)] 
           
test-framework=xUnit.net 2.1.0.3179 run-date=2016-10-26 run-time=12:13:07 total=2 
           
passed=1 failed=1 skipped=0 time=0.208 errors=0
>
    <
errors
/>
    <
collection total=2 passed=1 failed=1 skipped=0 
               
name=Test collection for AdvancedAspNetCore.Testing.Tests.HomeControllerTests time=0.050
>
      <
test name=Index should return default view type=AdvancedAspNetCore.Testing.Tests.HomeControllerTests 
           
method=Index_should_return_default_view time=0.0493443 result=Pass
/>
      <
test name=Failing test type=AdvancedAspNetCore.Testing.Tests.HomeControllerTests method=ShouldFail 
           
time=0.0006822 result=Fail
>
        <
failure exception-type=System.NotImplementedException
>
          <
message><![CDATA[System.NotImplementedException : The method or operation is not implemented.]]></message
>
          <
stack-trace><![CDATA[   at AdvancedAspNetCore.Testing.Tests.HomeControllerTests.ShouldFail() in D:\Projects\AdvancedAspNetCore\AdvancedAspNetCore\AdvancedAspNetCore.Testing.Tests\HomeControllerTests.cs:line 28]]></stack-trace
>
        </
failure
>
      </
test
>
    </
collection
>
  </
assembly
>
</
assemblies
>

This XML is simple enough to generate HTML output of it.

Running xUnit tests for multiple runtimes

Now let’s see what happens if our web application targets multiple .NET Framework versions. Suppose we want application to run on .NET Core and .NET Framework 4.6. We have to add .NET Framework 4.6 to supported list of frameworks (in web application and test project). Here’s our new project.json for tests project.


{
 
“version”: “1.0.0-*”
,
  “testRunner”: “xunit”
,

  “dependencies”: {
   
“xunit”: “2.2.0-beta3-build3402”
,
   
“dotnet-test-xunit”: “2.2.0-preview2-build1029”
,
   
“AdvancedAspNetCore.Testing”: “1.0.0”

  },

  “frameworks”: {
   
“netcoreapp1.0”
: {
     
“dependencies”
: {
       
“Microsoft.NETCore.App”
: {
         
“version”: “1.0.1”
,
         
“type”: “platform”
        },
       
“xunit.runner.dnx”: “2.1.0-rc1-build204”
,
       
“System.Runtime”: “4.1.0”
      },
     
“imports”
: [
       
“dnxcore50”
,
       
“portable-net45+win8”
      ]
    },
   
“net46”
: {
     
“dependencies”
: {
       
“xunit.runner.visualstudio”: “2.2.0-beta3-build1187”
      }
    }
  }
}



 

Let’s run dotnet test again and see the console output.

Running xUnit tests on command-line

NB! When writing this post the XML-output of xUnit doesn’t reflect results for all tested frameworks. It seems like only the first one gets to XML-file.

Wrapping up

xUnit is matured testing framework that works also with ASP.NET Core and .NET Core. Although all work is not finished yet it seems most important parts of xUnit already work well with ASP.NET Core. It’s possible to run tests in Visual Studio Test Explorer and on command-line. For applications targeting multiple frameworks tests are run for every supported framework. Although XML-output doesn’t reflect it yet it works fine with console output. xUnit doesn’t come with any complex requirements and it is possible to run it also on build and CI servers.


4 thoughts on “Using xUnit with ASP.NET Core

  • wish says:

    It would be nice to have a viewer for OSX.

  • Gunnar says:

    If you are writing code on VS Code then please check out if OmniSharp extension for VS Code helps you.

  • wish says:

    oh, thank you!

  • Gunnar says:

    I played with VS Code on Linux last night. There is test runner for nUnit available. I found nothing for xUnit. To visualize xUnit tests you can write script that runs tests with XML-output, then applies XLS-transform to generate HTML and then opens HTML report in browser. Also it should not be hard to write VS Code extension for it.

Leave a Reply

Your email address will not be published. Required fields are marked *