Unit Testing

1. Introduction

In the tutorials so far we have introduced many features of Groundkit which you can use to produce ground software, but we haven’t yet discussed mechanisms you can use to ensure the code you build using Groundkit is correct.

When making use of reusable software in ground systems (where the consequences of failure can be painful!), it’s important that you, and others, can have confidence that the software will work as intended.

To help with this, the Groundkit Tooling has Unit Testing support built into it.

This tutorial will show you how to use this Unit Testing support when developing your own Component Types.

In this tutorial, you will:

  • Learn about the basic structure used for Unit Testing Component Types.

  • Create, implement and run some Unit Tests for the storage.SimpleConfigStore Component Type you worked on in the previous tutorial.

2. Before You Begin

Guidance on the styles and conventions used in these tutorials is available here.

Unless otherwise directed, all commands in this tutorial must be run in the developing_components/UnitTesting workspace.

You must have Groundkit installed as described in the Getting Started Guide.

Install a copy of the tutorials locally by running hgk-prepare-tutorials.

Navigate to the developing_components/UnitTesting workspace in a terminal and run hgk workspace prepare to ensure it is ready to use.

3. JUnit and Mockito

Groundkit uses two third-party tools to assist with developing and running Unit Tests:

  • JUnit5, a Unit Test framework built for Java applications, and

  • Mockito, a popular mocking framework.

JUnit provides helper methods and a set of assertions for composing Unit Tests.

Mockito is used to generate mocks. These are methods used to fulfil the requirements of the code being tested in place of the real methods, which are often unavailable when Unit Testing.

There is a wealth of information about Unit Testing available online. In this tutorial we assume a basic familiarity with the concepts involved, and focus on how to write and run tests when working with Groundkit.

We will cover various JUnit and Mockito features we often use, and where relevant we will link to the documentation provided by those projects.

4. Unit Tests in Groundkit

In Groundkit Component Types are the principle unit of reuse. This means that it is reasonable to expect a given Component Type to work correctly when instantiated within any Deployment Type.

To try and ensure that a Component Type will work correctly in new contexts, we typically write a set of tests which attempt to cover all of the interfaces of a Component Type.

This usually means:

  • For Service Providers, writing tests which make sure they implement each Operation of that Service correctly.

  • For Component Types with Actions and Parameters, writing tests which invoke each Action with various Arguments, and get and set each Parameter with various values, to make sure each case is handled correctly.

  • For Service Consumers, mocking the Service Operations which the Component Type issues. This gives us opportunity to make sure the correct Service Operations are issued at the correct times.

For complex Component Types there are more interfaces to consider, but they follow the same principles: exercise your inputs, and mock your requirements.

5. Testing storage.SimpleConfigStore

In the following sections you will create, implement and run a Unit Test to demonstrate the storage.SimpleConfigStore Component Type's get and store Operations, which you implemented in the previous tutorial.

If you haven’t yet completed that tutorial, we suggest you do so now.

5.1. Creating the Test File

Generating the test files for a Component Type is very simple. Whenever a Component Type is generated using the generate command, test files are automatically created.

A complete copy of the storage.SimpleConfigStore Component Type is provided in this tutorial’s library. This is the Component Type you will write the Unit Tests against.

Generate a test file for the provided storage.SimpleConfigStore Component Type by generating it.

hgk component-type generate storage.SimpleConfigStore

This creates a test file for the storage.SimpleConfigStore Component Type in the following location:

library/componenttypes/storage/simpleconfigstore/src/test/java/com/brightascension/componentimpls/storage/simpleconfigstore/simpleconfigstoreimpl/SimpleConfigStoreImplTest.java

Open SimpleConfigStoreImplTest.java.

As you can see, SimpleConfigStoreImplTest.java already contains various fields and methods required to write some Unit Tests. There are TODO comments indicating where you will need to make changes.

From top to bottom, the file includes:

  • Fields for two of the mocks you will need in testing your Component.

    • A mock for the storage.FSS Service.

    • A mock for the Component Container. This is an autogenerated class that contains methods for, among others, logging, accessing initialisation data, and accessing consumed Services.

  • A field for accessing the Component Instance being tested.

  • A setupMocks method for initialising the mocked classes. There are `TODO`s describing how to complete this method.

  • An example unit test method. You will need to write several of these to fully test your Component.

5.2. Designing the Tests

As is the case with any software, it makes sense to think about how you’re going to approach writing your Unit Tests before you begin.

Tests should usually cover the broad functional jobs which a Component Type fulfils. In the case of storage.SimpleConfigStore, we are mostly interested in testing the code which uses FSS which you added in the previous tutorial.

To test the configuration storing and getting functionality, you will implement unit tests which exercise the following specific cases:

  1. Read a config value that doesn’t exist.

  2. Read a config value that does exist.

  3. Write a config value.

These tests are fairly pedantic, since our Component is very simple. However, they are illustrative of how you might go about unit testing more complex Components.

We will work through this list in order in the remaining sections of the tutorial, referring back to it as required.

5.3. Initialisation Data

The first TODO in SimpleConfigStoreImplTest.java suggests you set Initialisation Data values for the Component Instance under test. However, as you can see in SimpleConfigStoreImplInitData.java, there is no Initialisation Data.

Update the setupMocks to return empty Initialisation Data.

Show the updated TODO
@@ -30,15 +30,14 @@ class SimpleConfigStoreImplTest {
 
   @BeforeEach
   void setupMocks() {
-    // TODO: If your Component contains initialisation data, uncomment the below lines and provide values for your Component's initialisation data.
-    // SimpleConfigStoreImplInitData componentInitData = new SimpleConfigStoreImplInitData();
-    // lenient().when(container.simpleConfigStoreInitData()).thenReturn(componentInitData);
+    SimpleConfigStoreImplInitData componentInitData = new SimpleConfigStoreImplInitData();
+    lenient().when(container.simpleConfigStoreInitData()).thenReturn(componentInitData);
 
     // Set up the mocks for any service requirements
     lenient().when(container.storageFSSFilestore()).thenReturn(storageFSSFilestore);
 
     // Instantiate the Component after the Component's initialisation data and Container have been set up.
-    // this.component = new SimpleConfigStoreImpl(container);
+    this.component = new SimpleConfigStoreImpl(container);
   }
 
   /**

When testing other Component Types you may wish to put invalid values in the Initialisation Data in order to test validation. You may also want to provide different Initialisation Data for different tests.

5.4. Test 1: Read a Non-Existent Config Value

The first test outlined above needs to check that invoking get on a non-existent value is handled correctly.

The first step in implementing the new test is to select a name for it. It is important to ensure that test methods are named in a way which clearly describes the test being carried out. This allows readers to quickly understand the purpose of each test, whether they are reading the test methods themselves, or the test output produced when the tests are run. This test method will test retrieving a non-existent value from the config.

Rename the SimpleConfigStoreImplTest.yourFirstUnitTest test method to have a more appropriate name for the test you are implementing, and update the description comment accordingly.

Show the updated test method name
@@ -41,10 +41,11 @@ class SimpleConfigStoreImplTest {
   }
 
   /**
-   * Your first unit test.
+   * Tests retrieving a config value that doesn't exist. For this not to throw an exception, we need to verify that the correct
+   * options are passed in to openFile so that an empty file is silently created by the FSS.
    */
   @Test
-  void yourFirstUnitTest() {
+  void getNonExistentValue() {
     // TODO: Remember to fill in your unit tests!
   }
 }

We’ll show you the code needed for this first test, but you might like to try and work it out on your own first.

Remember, you can see the docs for the FSS by running:

hgk service generate-docs storage.FSS
Show the updated test
@@ -7,13 +7,20 @@ package com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfi
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.storage.fss.StorageFSSFilestore;
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.SimpleConfigStoreImplContainer;
 
+import com.brightascension.genone.exception.GenOneBaseException;
+import com.brightascension.services.storage.fss.StorageFSSOpenFileResponse;
+import com.brightascension.services.storage.fss.StorageFSSReadFileResponse;
+import com.brightascension.services.storage.fss.types.FSSAccessMode;
+import com.brightascension.services.storage.simpleconfigstore.StorageSimpleConfigStoreGetResponse;
+import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.Mock;
+import org.mockito.internal.util.MockUtil;
 import org.mockito.junit.jupiter.MockitoExtension;
 
-import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.*;
 
 /**
  * The unit test class for the SimpleConfigStore Component.
@@ -28,14 +35,23 @@ class SimpleConfigStoreImplTest {
   // The Component to be tested, instantiated in setupMocks() below.
   private SimpleConfigStoreImpl component;
 
+  // Some expected responses from the FSS
+  private String configParam = "some.param";
+  private int fileId = 1;
+  private byte[] fileContents = new byte[0];
+
   @BeforeEach
-  void setupMocks() {
+  void setupMocks() throws GenOneBaseException {
     SimpleConfigStoreImplInitData componentInitData = new SimpleConfigStoreImplInitData();
     lenient().when(container.simpleConfigStoreInitData()).thenReturn(componentInitData);
 
     // Set up the mocks for any service requirements
     lenient().when(container.storageFSSFilestore()).thenReturn(storageFSSFilestore);
 
+    // Set up some default mocks for the FSS
+    lenient().when(storageFSSFilestore.openFile(any(), any(Boolean.class), any(Boolean.class), any())).thenReturn(new StorageFSSOpenFileResponse(fileId));
+    lenient().when(storageFSSFilestore.readFile(any(Integer.class), any(Long.class))).thenReturn(new StorageFSSReadFileResponse(fileContents));
+
     // Instantiate the Component after the Component's initialisation data and Container have been set up.
     this.component = new SimpleConfigStoreImpl(container);
   }
@@ -45,7 +61,15 @@ class SimpleConfigStoreImplTest {
    * options are passed in to openFile so that an empty file is silently created by the FSS.
    */
   @Test
-  void getNonExistentValue() {
-    // TODO: Remember to fill in your unit tests!
+  void getNonExistentValue() throws GenOneBaseException {
+    StorageSimpleConfigStoreGetResponse response = component.storageSimpleConfigStoreConfigServiceGet(configParam);
+
+    // Verify the FSS calls
+    verify(storageFSSFilestore, times(1)).openFile(configParam, true, false, FSSAccessMode.READ_WRITE);
+    verify(storageFSSFilestore, times(1)).readFile(fileId, Integer.MAX_VALUE);
+    verify(storageFSSFilestore, times(1)).closeFile(fileId);
+
+    // Verify the response
+    Assertions.assertEquals("", response.value(), "Expected empty string");
   }
 }

5.5. Test 2: Read an Existing Config Value

Next, add a test to test retrieving a config value that should return a non-empty String.

Can you implement this by adapting the test method you wrote in the last section?

Show the updated test.
@@ -16,6 +16,8 @@ import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import org.mockito.Mock;
 import org.mockito.internal.util.MockUtil;
 import org.mockito.junit.jupiter.MockitoExtension;
@@ -57,11 +59,18 @@ class SimpleConfigStoreImplTest {
   }
 
   /**
-   * Tests retrieving a config value that doesn't exist. For this not to throw an exception, we need to verify that the correct
+   * Tests retrieving some config values.
+   *
+   * For this not to throw an exception when the file doesn't exist, we need to verify that the correct
    * options are passed in to openFile so that an empty file is silently created by the FSS.
    */
-  @Test
-  void getNonExistentValue() throws GenOneBaseException {
+  @ParameterizedTest
+  @ValueSource(strings = {"", "someValue"})
+  void testGetValue(String expValue) throws GenOneBaseException {
+    // Set up the expected file contents
+    fileContents = expValue.getBytes();
+    lenient().when(storageFSSFilestore.readFile(any(Integer.class), any(Long.class))).thenReturn(new StorageFSSReadFileResponse(fileContents));
+
     StorageSimpleConfigStoreGetResponse response = component.storageSimpleConfigStoreConfigServiceGet(configParam);
 
     // Verify the FSS calls
@@ -69,7 +78,7 @@ class SimpleConfigStoreImplTest {
     verify(storageFSSFilestore, times(1)).readFile(fileId, Integer.MAX_VALUE);
     verify(storageFSSFilestore, times(1)).closeFile(fileId);
 
     // Verify the response
-    Assertions.assertEquals("", response.value(), "Expected empty string");
+    Assertions.assertEquals(expValue, response.value(), "Expected: " +  expValue);
   }
 }

Note, to use the @ParameterizedTest we had to update workspace-pom.xml to add a new dependency:

@@ -17,4 +17,12 @@
   </properties>
 
   <!-- NOTE: Any dependencies specified here will be inherited by all artefacts in this workspace -->
+  <dependencies>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-params</artifactId>
+      <version>5.10.0</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
 </project>

5.6. Test 3: Store a Config Value

Finally, we need to test storing a config value.

Add the new test.

Show the new test.
@@ -81,4 +81,17 @@ class SimpleConfigStoreImplTest {
     // Verify the response
     Assertions.assertEquals(expValue, response.value(), "Expected: " +  expValue);
   }
+
+  /**
+   * Tests writing a config value.
+   */
+  @Test
+  void testStoreValue() throws GenOneBaseException {
+    component.storageSimpleConfigStoreConfigServiceStore(configParam, "someValue");
+
+    // Verify the FSS calls
+    verify(storageFSSFilestore, times(1)).openFile(configParam, true, false, FSSAccessMode.READ_WRITE);
+    verify(storageFSSFilestore, times(1)).writeFile(fileId, "someValue".getBytes());
+    verify(storageFSSFilestore, times(1)).closeFile(fileId);
+  }
 }

5.7. Running Tests

Build and run the tests either in your IDE or on the command line.

Build and run the storage.SimpleConfigStore Unit Tests by running the following command:

hgk component-type build storage.SimpleConfigStore --verbose

You should see the following near the bottom of the output:

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.SimpleConfigStoreImplTest
OpenJDK 64-Bit Server VM warning: Sharing is only supported for boot loader classes because bootstrap classpath has been appended
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.823 s -- in com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.SimpleConfigStoreImplTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0

Using the techniques you’ve learned in this tutorial you could write more tests to further exercise storage.SimpleConfigStore. Have a think about what these test might be and how you’d write them.

Perhaps also consider how you might write Unit Tests for the MessagePrinter and EventPublisher Component Types you encountered in the first three tutorials.

6. Wrap Up

In this tutorial you have:

  • Learned about how Unit Testing is supported by Groundkit.

  • Learned how to use Groundkit Tooling to generate, build and run Unit Tests.

  • Implemented and run Unit Tests for the storage.SimpleConfigStore Component Type, making use of mocking to fulfil its FSS requirement.