Tutorial 05 01 Unit Testing Generated OData Services

Tutorial 5: Unit Testing Generated OData Services

In this tutorial, you will learn how to generate, configure, and run unit tests for the OData controllers and endpoints that you are generating.

In order to complete this tutorial, you must have an existing Harmony Core solution that contains code-generated OData services, that you created by following either the Creating a Demo Service or Building a Service From Scratch tutorials.

The unit testing environment produced by this tutorial also supports custom authentication, so if you have also followed the Authentication via Custom Code, that's OK, things should still work here.

Add and Configure a Unit Testing Project

The first step in the process of adding unit testing capabilities to your Harmony Core development environment is to add a new project to your solution. In .NET Core unit tests are typically defined in a console application, which is then executed from the command line.

To simplify this process we provide a project template that can be used to create the new console application to host your unit tests. The advantage of this approach is that all of the necessary project references and NuGet package references will already be in place.

As with many things in Harmony Core, we rely on various naming conventions, and adding a unit test project is no different. For everything to come together and work optimally, the name of the unit testing project should be Services.Test.

Open your existing Harmony Core solution in Visual Studio.
From the main menu, select Tools > Command Prompt (x64) top open a command prompt window.
In the command prompt window, change directory into your main solution directory (the one that contains your .sln file and the Common.props file), and set the value of the environment variable SolutionDir to the current folder by typing the following commands:
```
cd ..
set SolutionDir=%CD%\
```
Note the trailing back-slash, which is important.

The next step is to make sure that you have the latest Harmony Core Solution Templates installed:

Type the following command:
```
dotnet new install Harmony.Core.ProjectTemplates
```
After the latest templates are installed, you will see a list of all of the templates that are installed on your system.
Check that you have a Synergy template named harmonytest.

The harmonytest template is a project template that creates a Synergy Console application that is pre-configured for use as a unit testing environment. The template can only be used in the context of an existing Harmony Core development solution that was previously created from either the harmonycore or harmonydemo solution templates. This is because the new unit testing project will have various project references in place based on existing projects in your solution. The new project will also have all of the required NuGet package references already in place.

Now you can create the new Services.Test project:

In the same command prompt window, still in the main solution folder, type the following command to add a new unit testing project:
```
dotnet new harmonytest -o Services.Test
```
You should see the following message displayed:
```
The template "Harmony Core Unit Test Project" was created successfully.
```

Now you can add the newly created project to your solution.

Leave the command prompt window open, and switch back to Visual Studio.
In Solution Explorer, right-click on the main solution and select Add > Existing Project....
In the Add Existing Project dialog, browse to your main solution folder, then into the Services.Test folder, select the Services.Test.synproj file, and click the Open button.
To ensure that the changes to the solution file are saved, select File > Save All from the main menu.

If you examine the new project you will see that it already the project references and NuGet package references that were mentioned earlier, as well as several project folders and a sample main-line program named SelfHost.dbl. This source file doesn't actually contain any useful code, it is there simply to make sure the project builds out of the box. The content of this file will be replaced later when you generate your unit testing code.

Run the Project Upgrade Tool

Because it was necessary to download the latest version of the Harmony Core Solution Templates in order to install the harmonytest template, it is possible that the Services.Test project might be configured to use a more recent version of Harmony Core than the other projects in your solution. To ensure that everything is in sync, the next step will be to run the Harmony Core Project Upgrade Tool on your solution. To do so:

Switch back to the command prompt window and execute the Harmony Core upgrade tool command:

dotnet tool update -g Harmony.Core.CliTool
harmonycore upgrade-latest

The first command ensures that you have the latest version of the upgrade tool installed. If the project upgrade tool was already up to date you will see a message similar to this:

Tool 'harmony.core.clitool' was reinstalled with the latest stable version (version '3.1.33').

If not, you will see a message confirming the before and after version numbers.

The second command upgrades your solution to the latest version of Harmony Core. As it starts to run you will see output similar to this:

Scanning 'D:\HC_WEBINAR_MyDemoApi' for HarmonyCore project files
This utility will make significant changes to projects and other source files in your Harmony Core development 
environment. Before running this tool we recommend checking the current state of your development environment into your 
source code repository, taking a backup copy of the environment if you don't use source code control.

Type YES to proceed:

Enter YES to confirm that you are aware that your project and other files may be updated. You should then see output similar to this:

Updating template files in D:\HC_WEBINAR_MyDemoApi\Templates
Found template files in D:\HC_WEBINAR_MyDemoApi\Templates\SignalR
Found template files in D:\HC_WEBINAR_MyDemoApi\Templates\TraditionalBridge
Updating traditional bridge files in D:\HC_WEBINAR_MyDemoApi\TraditionalBridge\Bridge

Switch back to Visual Studio. If the project upgrade tool did make any changes to your projects then you will see a dialog similar to this:

If you do see this dialog, click the Reload All button to reload the projects that were externally altered.

Enable Unit Test Code Generation

As with many features in Harmony Core, most of the code required to implement basic unit testing can be generated using CodeGen and templates provided by Harmony Core. And, as usual, the generation of this code is enabled via an ENABLE_UNIT_TEST_GENERATION option in regen.bat.

Edit regen.bat then locate and remove the rem comment from the ENABLE_UNIT_TEST_GENERATION option, like this
```
set ENABLE_UNIT_TEST_GENERATION=YES
```
Save the changes to the file.

Generate Code

Switch back to your command prompt window and execute the regen.bat batch file.
As always, check the Output window and look for the DONE message to indicate that code generation was successful, then leave the command prompt window open.

What Changed

Enabling the ENABLE_UNIT_TEST_GENERATION option causes several new source files to be generated into various folders in your Services.Test project:

Self-hosting code was generated into the existing SelfHost.dbl source file

The code in the self hosting program is similar to the code in the main Services.Host project, except that it starts and configures a self-hosting instance specifically configured to support the execution of unit tests.

Several new source files were created in the Services.Test project folder:

TestConstants.Properties.dbl

This file defines various properties that are used by the unit tests to identify particular data entities during testing. All you will find here are the properties themselves. The values are defined in the next source file. The content of the file should look like this:

import Microsoft.VisualStudio.TestTools.UnitTesting
import Newtonsoft.Json
import System.Collections.Generic
import System.Net.Http

namespace Services.Test

    public static partial class TestConstants

        ;;------------------------------------------------------------
        ;;Test data for Customer
        ;;
        public static readwrite property GetCustomers_Count, int
        public static readwrite property GetCustomer_CustomerNumber, int
        public static readwrite property GetCustomer_Expand_REL_Orders_CustomerNumber, int
        public static readwrite property GetCustomer_Expand_REL_Item_CustomerNumber, int
        public static readwrite property GetCustomer_Expand_All_CustomerNumber, int
        public static readwrite property GetCustomer_ByAltKey_State_State, String
        public static readwrite property GetCustomer_ByAltKey_Zip_ZipCode, int
        public static readwrite property GetCustomer_ByAltKey_PaymentTerms_PaymentTermsCode, String
        public static readwrite property UpdateCustomer_CustomerNumber, int

        ;;------------------------------------------------------------
        ;;Test data for Item
        ;;
        public static readwrite property GetItems_Count, int
        public static readwrite property GetItem_ItemNumber, int
        public static readwrite property GetItem_Expand_REL_Vendor_ItemNumber, int
        public static readwrite property GetItem_Expand_REL_OrderItems_ItemNumber, int
        public static readwrite property GetItem_Expand_All_ItemNumber, int
        public static readwrite property GetItem_ByAltKey_VendorNumber_VendorNumber, int
        public static readwrite property GetItem_ByAltKey_Color_FlowerColor, String
        public static readwrite property GetItem_ByAltKey_Size_Size, int
        public static readwrite property GetItem_ByAltKey_Name_CommonName, String
        public static readwrite property UpdateItem_ItemNumber, int

        ;;------------------------------------------------------------
        ;;Test data for Order
        ;;
        public static readwrite property GetOrders_Count, int
        public static readwrite property GetOrder_OrderNumber, int
        public static readwrite property GetOrder_Expand_REL_OrderItems_OrderNumber, int
        public static readwrite property GetOrder_Expand_REL_Customer_OrderNumber, int
        public static readwrite property GetOrder_Expand_All_OrderNumber, int
        public static readwrite property GetOrder_ByAltKey_CustomerNumber_CustomerNumber, int
        public static readwrite property GetOrder_ByAltKey_DateOrdered_DateOrdered, DateTime
        public static readwrite property GetOrder_ByAltKey_DateCompleted_DateCompleted, DateTime
        public static readwrite property UpdateOrder_OrderNumber, int

        ;;------------------------------------------------------------
        ;;Test data for OrderItem
        ;;
        public static readwrite property GetOrderItems_Count, int
        public static readwrite property GetOrderItem_OrderNumber, int
        public static readwrite property GetOrderItem_ItemNumber, int
        public static readwrite property GetOrderItem_Expand_REL_Order_OrderNumber, int
        public static readwrite property GetOrderItem_Expand_REL_Order_ItemNumber, int
        public static readwrite property GetOrderItem_Expand_REL_Item_OrderNumber, int
        public static readwrite property GetOrderItem_Expand_REL_Item_ItemNumber, int
        public static readwrite property GetOrderItem_Expand_All_OrderNumber, int
        public static readwrite property GetOrderItem_Expand_All_ItemNumber, int
        public static readwrite property GetOrderItem_ByAltKey_ItemOrdered_ItemOrdered, int
        public static readwrite property GetOrderItem_ByAltKey_DateShipped_DateShipped, DateTime
        public static readwrite property GetOrderItem_ByAltKey_InvoiceNumber_InvoiceNumber, int
        public static readwrite property UpdateOrderItem_OrderNumber, int
        public static readwrite property UpdateOrderItem_ItemNumber, int

        ;;------------------------------------------------------------
        ;;Test data for Vendor
        ;;
        public static readwrite property GetVendors_Count, int
        public static readwrite property GetVendor_VendorNumber, int
        public static readwrite property GetVendor_Expand_REL_Items_VendorNumber, int
        public static readwrite property GetVendor_Expand_All_VendorNumber, int
        public static readwrite property GetVendor_ByAltKey_State_State, String
        public static readwrite property GetVendor_ByAltKey_Zip_ZipCode, int
        public static readwrite property GetVendor_ByAltKey_PaymentTerms_PaymentTermsCode, String
        public static readwrite property UpdateVendor_VendorNumber, int

    endclass

endnamespace

TestConstants.Values.dbl

This is a partial class with the TestConstants.Properties file, and contains assignment statements to actually assign values for the various data entities to be referenced when running unit tests. The code in the file should look like this:

import Microsoft.VisualStudio.TestTools.UnitTesting
import Newtonsoft.Json
import System.Collections.Generic
import System.Net.Http

namespace Services.Test

    public static partial class TestConstants

        static method TestConstants
        proc

            ;;------------------------------------------------------------
            ;;Test data for Customer
            ;;
            GetCustomers_Count = 0
            GetCustomer_CustomerNumber = 0
            GetCustomer_Expand_REL_Orders_CustomerNumber = 0
            GetCustomer_Expand_REL_Item_CustomerNumber = 0
            GetCustomer_Expand_All_CustomerNumber = 0
            GetCustomer_ByAltKey_State_State = ""
            GetCustomer_ByAltKey_Zip_ZipCode = 0
            GetCustomer_ByAltKey_PaymentTerms_PaymentTermsCode = ""
            UpdateCustomer_CustomerNumber = 0

            ;;------------------------------------------------------------
            ;;Test data for Item
            ;;
            GetItems_Count = 0
            GetItem_ItemNumber = 0
            GetItem_Expand_REL_Vendor_ItemNumber = 0
            GetItem_Expand_REL_OrderItems_ItemNumber = 0
            GetItem_Expand_All_ItemNumber = 0
            GetItem_ByAltKey_VendorNumber_VendorNumber = 0
            GetItem_ByAltKey_Color_FlowerColor = ""
            GetItem_ByAltKey_Size_Size = 0
            GetItem_ByAltKey_Name_CommonName = ""
            UpdateItem_ItemNumber = 0

            ;;------------------------------------------------------------
            ;;Test data for Order
            ;;
            GetOrders_Count = 0
            GetOrder_OrderNumber = 0
            GetOrder_Expand_REL_OrderItems_OrderNumber = 0
            GetOrder_Expand_REL_Customer_OrderNumber = 0
            GetOrder_Expand_All_OrderNumber = 0
            GetOrder_ByAltKey_CustomerNumber_CustomerNumber = 0
            GetOrder_ByAltKey_DateOrdered_DateOrdered = new DateTime()
            GetOrder_ByAltKey_DateCompleted_DateCompleted = new DateTime()
            UpdateOrder_OrderNumber = 0

            ;;------------------------------------------------------------
            ;;Test data for OrderItem
            ;;
            GetOrderItems_Count = 0
            GetOrderItem_OrderNumber = 0
            GetOrderItem_ItemNumber = 0
            GetOrderItem_Expand_REL_Order_OrderNumber = 0
            GetOrderItem_Expand_REL_Order_ItemNumber = 0
            GetOrderItem_Expand_REL_Item_OrderNumber = 0
            GetOrderItem_Expand_REL_Item_ItemNumber = 0
            GetOrderItem_Expand_All_OrderNumber = 0
            GetOrderItem_Expand_All_ItemNumber = 0
            GetOrderItem_ByAltKey_ItemOrdered_ItemOrdered = 0
            GetOrderItem_ByAltKey_DateShipped_DateShipped = new DateTime()
            GetOrderItem_ByAltKey_InvoiceNumber_InvoiceNumber = 0
            UpdateOrderItem_OrderNumber = 0
            UpdateOrderItem_ItemNumber = 0

            ;;------------------------------------------------------------
            ;;Test data for Vendor
            ;;
            GetVendors_Count = 0
            GetVendor_VendorNumber = 0
            GetVendor_Expand_REL_Items_VendorNumber = 0
            GetVendor_Expand_All_VendorNumber = 0
            GetVendor_ByAltKey_State_State = ""
            GetVendor_ByAltKey_Zip_ZipCode = 0
            GetVendor_ByAltKey_PaymentTerms_PaymentTermsCode = ""
            UpdateVendor_VendorNumber = 0

        endmethod

    endclass

endnamespace

The code in this file is only generated one time, and not then overwritten. The intention is that you edit this file and provide real values for the collection counts and keys to be used for each of the unit test methods.

UnitTestEnvironment.dbl

The code in this file is used to both establish a known consistent environment for the unit tests to run in at the beginning of each run, and also to tear down that environment after all tests have completed.

Similar to the main self-hosting program, what this code mainly does is create a fresh set of data files for each test run, and delete those files after all tests have completed.

A new folder named DataGenerators was created in the Services.Test project folder, and several source files were generated into the folder:
- CustomerLoader.dbl
- ItemLoader.dbl
- OrderItemLoader.dbl
- OrderLoader.dbl
- VendorLoader.dbl
  
  These data generator classes are used during the loading of data in the UnitTestEnvironment class described above.
A new folder named Models was created in the Services.Test project folder, and several source files were generated into the folder:
- Customer.dbl
- Item.dbl
- Order.dbl
- OrderItem.dbl
- Vendor.dbl
  
  These data model classes are simplified versions of the data model classes that are generated into the Services.Models project, they are used to define and represent data entities on the client side, as the various unit tests are essentially HTTP clients to your Harmony Core web services.
A new folder named UntTests was created in the Services.Test project folder, and several source files were generated into the folder:
- CustomerTests.dbl
- ItemTests.dbl
- OrderItemTests.dbl
- OrderTests.dbl
- VendorTests.dbl
  
  These classes are special unit test classes, and there is a unit test method generated to test each of the operational endpoints on your generated OData controllers. Each of the test methods is coded to perform a specific function, based on the key values that are defined in the TestConstants.Values.dbl file. For example, the Get a single customer test is configured to retrieve a specific customer, by primary key, and to verify that the correct entity is returned.
The test methods each use an HttpClient object, so they interact with your Harmony Core service the exact same way that any HTTP client would.

Add Code to Projects

Your next task is to add all of these new files to your Services.Test project:

Right-click on the Services.Test project, select Add > Existing Item…, then select all of the .dbl files and click the Add button.
Right-click on the DataGenerators folder, select Add > Existing Item…, then drill into the DataGenerators folder, select all of the .dbl files and click the Add button.
Repeat the process for the Models and UnitTests folders.

Set Test Values

Edit TestConstants.Values.dbl

Replace the assignment statements in the code with the following, which you will notice includes actual values:

;;------------------------------------------------------------
;;Test data for Customer
;;
GetCustomers_Count = 38
GetCustomer_CustomerNumber = 1
GetCustomer_Expand_REL_Orders_CustomerNumber = 1
GetCustomer_Expand_REL_Item_CustomerNumber = 1
GetCustomer_Expand_All_CustomerNumber = 1
GetCustomer_ByAltKey_State_State = "CA"
GetCustomer_ByAltKey_Zip_ZipCode = 94806
GetCustomer_ByAltKey_PaymentTerms_PaymentTermsCode = "01"
UpdateCustomer_CustomerNumber = 3

;;------------------------------------------------------------
;;Test data for Item
;;
GetItems_Count = 121
GetItem_ItemNumber = 1
GetItem_Expand_REL_Vendor_ItemNumber = 1
GetItem_Expand_REL_OrderItems_ItemNumber = 1
GetItem_Expand_All_ItemNumber = 6
GetItem_ByAltKey_VendorNumber_VendorNumber = 38
GetItem_ByAltKey_Color_FlowerColor = "white"
GetItem_ByAltKey_Size_Size = 10
GetItem_ByAltKey_Name_CommonName = "Paper Mulberry"
UpdateItem_ItemNumber = 22

;;------------------------------------------------------------
;;Test data for Order
;;
GetOrders_Count = 4724
GetOrder_OrderNumber = 3
GetOrder_Expand_REL_OrderItems_OrderNumber = 3
GetOrder_Expand_REL_Customer_OrderNumber = 3
GetOrder_Expand_All_OrderNumber = 3
GetOrder_ByAltKey_CustomerNumber_CustomerNumber = 1
GetOrder_ByAltKey_DateOrdered_DateOrdered = new DateTime(2018,03,07)
GetOrder_ByAltKey_DateCompleted_DateCompleted = new DateTime(2018,08,21)
UpdateOrder_OrderNumber = 10

;;------------------------------------------------------------
;;Test data for OrderItem
;;
GetOrderItems_Count = 14188
GetOrderItem_OrderNumber = 3
GetOrderItem_ItemNumber = 1
GetOrderItem_Expand_REL_Order_OrderNumber = 3
GetOrderItem_Expand_REL_Order_ItemNumber = 1
GetOrderItem_Expand_REL_Item_OrderNumber = 3
GetOrderItem_Expand_REL_Item_ItemNumber = 1
GetOrderItem_Expand_All_OrderNumber = 3
GetOrderItem_Expand_All_ItemNumber = 1
GetOrderItem_ByAltKey_ItemOrdered_ItemOrdered = 6
GetOrderItem_ByAltKey_DateShipped_DateShipped = new DateTime(2018,08,21)
GetOrderItem_ByAltKey_InvoiceNumber_InvoiceNumber = 930301
UpdateOrderItem_OrderNumber = 999999
UpdateOrderItem_ItemNumber = 20

;;------------------------------------------------------------
;;Test data for Vendor
;;
GetVendors_Count = 8
GetVendor_VendorNumber = 38
GetVendor_Expand_REL_Items_VendorNumber = 40
GetVendor_Expand_All_VendorNumber = 40
GetVendor_ByAltKey_State_State = "MA"
GetVendor_ByAltKey_Zip_ZipCode = 01000
GetVendor_ByAltKey_PaymentTerms_PaymentTermsCode = "30"
UpdateVendor_VendorNumber = 39

Save changes to and close the source file.

Build the Code

Before we move on, let's make sure the project builds:

Right-click on the Services.Test project and select Build.

Check the Output window and verify that the build was successful.

1>------ Build started: Project: Services.Test, Configuration: Debug Any CPU ------
========== Build: 1 succeeded, 0 failed, 5 up-to-date, 0 skipped ==========

Run Tests

Switch back to your command prompt window and move to into the Services.Test folder.
```
cd Services.Test
```
Now run the unit tests via a dotnet test command:

```
dotnet test --no-build --verbosity detailed
```

You should see output that looks something like this:

Starting test execution, please wait...

A total of 1 test files matched the specified pattern.
  √ GetCustomers [709ms]
  √ GetCustomers_Expand_REL_Orders [774ms]
  √ GetCustomers_Expand_REL_Item [36ms]
  √ GetCustomers_Expand_All [442ms]
  √ GetCustomer [37ms]
  √ GetCustomer_Expand_REL_Orders [17ms]
  √ GetCustomer_Expand_REL_Item [4ms]
  √ GetCustomer_Expand_All [13ms]
  √ GetCustomer_ByAltKey_State [6ms]
  √ GetCustomer_ByAltKey_Zip [3ms]
  √ GetCustomer_ByAltKey_PaymentTerms [3ms]
  √ UpdateCustomer [166ms]
  √ GetItems [31ms]
  √ GetItems_Expand_REL_Vendor [49ms]
  √ GetItems_Expand_REL_OrderItems [1s 281ms]
  √ GetItems_Expand_All [1s 275ms]
  √ GetItem [9ms]
  √ GetItem_Expand_REL_Vendor [4ms]
  √ GetItem_Expand_REL_OrderItems [12ms]
  √ GetItem_Expand_All [29ms]
  √ GetItem_ByAltKey_VendorNumber [3ms]
  √ GetItem_ByAltKey_Color [7ms]
  √ GetItem_ByAltKey_Size [5ms]
  √ GetItem_ByAltKey_Name [5ms]
  √ UpdateItem [43ms]
  √ GetOrderItems [1s 135ms]
  √ GetOrderItems_Expand_REL_Order [2s 701ms]
  √ GetOrderItems_Expand_REL_Item [3s 370ms]
  √ GetOrderItems_Expand_All [4s 645ms]
  √ GetOrderItem [9ms]
  √ GetOrderItem_Expand_REL_Order [4ms]
  √ GetOrderItem_Expand_REL_Item [5ms]
  √ GetOrderItem_Expand_All [3ms]
  √ GetOrderItem_ByAltKey_ItemOrdered [10ms]
  √ GetOrderItem_ByAltKey_DateShipped [9ms]
  √ GetOrderItem_ByAltKey_InvoiceNumber [3ms]
  √ UpdateOrderItem [50ms]
  √ GetOrders [355ms]
  √ GetOrders_Expand_REL_OrderItems [4s 905ms]
  √ GetOrders_Expand_REL_Customer [945ms]
  √ GetOrders_Expand_All [5s 477ms]
  √ GetOrder [7ms]
  √ GetOrder_Expand_REL_OrderItems [5ms]
  √ GetOrder_Expand_REL_Customer [3ms]
  √ GetOrder_Expand_All [4ms]
  √ GetOrder_ByAltKey_CustomerNumber [12ms]
  √ GetOrder_ByAltKey_DateOrdered [3ms]
  √ GetOrder_ByAltKey_DateCompleted [3ms]
  √ UpdateOrder [33ms]
  √ GetVendors [16ms]
  √ GetVendors_Expand_REL_Items [28ms]
  √ GetVendors_Expand_All [30ms]
  √ GetVendor [4ms]
  √ GetVendor_Expand_REL_Items [5ms]
  √ GetVendor_Expand_All [3ms]
  √ GetVendor_ByAltKey_State [3ms]
  √ GetVendor_ByAltKey_Zip [3ms]
  √ GetVendor_ByAltKey_PaymentTerms [3ms]
  √ UpdateVendor [33ms]

Test Run Successful.
Total tests: 59
     Passed: 59
 Total time: 30.9206 Seconds
       Done executing task "Microsoft.TestPlatform.Build.Tasks.VSTestTask".
     1>Done building target "VSTest" in project "Services.Test.synproj".
     1>Done Building Project "D:\HC_WEBINAR_MyDemoApi\Services.Test\Services.Test.synproj" (VSTest target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:31.37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly