Unit Testing Using Mikros

Introduction

Mikros provides a testing package specifically to assist in writing unit tests within services (or any other application). This package allows building tests by replacing ("mocking") internal functionalities with maximum possible code coverage.

Features that can be simulated

All gRPC or HTTP services have their API definition declared via protobuf file (.proto). This means that, during the code generation process from these files, a whole layer that allows replacing its API is also generated, the mocks. These mocks are used to simulate API calls between services within unit tests.

In addition to these mocks generated by protobuf, Mikros allows simulating the following functionalities:

• Records sent to a consumer type service;
• Events sent to a subscriber type service;
• Mock for a service's Settings API;
• Mock for a service's database API.

The mock API provided by the testing package allows simulating any other API that has generated mocks as long as its functions receive a value of type context.Context as the first argument.

Recommendations

• Maintain a context (context.Context) and an object of the service's main struct as global variables.
• Names of test files.
• Initialize global test values in a function to test the service's main.
• Have a specific function to test each service API, whether this API is an RPC call, an HTTP endpoint, an event handler, or a record in a datastream.
• Do not write a test that simulates all possibilities of a code in a single function. Use subsets in each test function to cover the maximum code coverage in the tested code, and each subtest should test up to a certain point within this code.
• The go subtest API allows including descriptive text about itself and this should be used to describe what should happen in the test, written in English.
• Do not use tests for execution in parallel mode.

Test Examples

Unit test of a service's main function

func TestMain(m *testing.M) {
    os.Exit(func() int {
        ctx := context.TODO()
        svc := mikros.NewService()
        s = &server {
            Service: svc,
        }

        // If the service uses database
        defer s.Database().DropCollection(ctx)

        return m.Run()
    }())
}

Unit test without using any type of mock

func TestFoo(t *testing.T) {
    t.Run("some descriptive text about the test", func(t *testing.T) {
        test := ftesting.New(t, nil)
        res, err := s.SomeCallToFoo(ctx, &args)
        test.Assert().NoError(err)
        test.Assert().NotNil(res)
        test.Assert().Contains("some expected value", res)
    })
}

Unit test mocking an external service API

func TestMethod(t *testing.T) {
    t.Run("should succeed calling the method", func(t *testing.T) {
        test := ftesting.New(t, nil)
        mock := ftesting.NewMock[examplemock.MockExampleServiceClientMockRecorder](test, examplemock.NewMockExampleSericeClient)
        mock.Mock(&ftesting.MockOptions{
            Call: mock.Recorder().ExternalCall,
            Times: 1,
            Error: nil,
            Return: &example.ExternalCallResponse{
                Example: &example.ExampleProto{
                    Id: id.NewID("ex"),
                },
            },
        })

        // Replace the external service with the created mock.
        s.ExampleServiceClient = mock.Client()
        res, err := s.Method(ctx, &args)
        test.Assert().NoError(err)
        test.Assert().NotNil(res)
    })
}

Unit test mocking a collection in the database

func TestFoo(t *testing.T) {
    t.Run("should return an error on FindMany call", func(t *testing.T) {
        dbmock := ftesting.NewMock[fmockdb.MockDatabaseServiceOperationsMockRecorder](t, fmockdb.NewMockDatabaseServiceOperations)
        dbmock.Mock(&ftesting.MockOptions{
            Call: dbmock.Recorder().FindMany,
            Error: s.Errors().Internal(ctx, errors.New("internal database error")),
            Times: 1,

            // We set this as true here because in this example the tested code is using
            // the variadic argument of the API (a pagination option for example).
            UseVaridicArgument: true,

            // This flag indicates that the tested call returns a single value (in this case an
            // error). Generally, most tested APIs are from service RPCs and
            // they always have two returned values, the data and an error.
            SingleErrorReturned: true,
        })

        test := ftesting.New(t, &ftesting.Options{
            Database: dbmock.Client()
        })
		
        // Initialize the test mode by replacing internal functionalities
        // of Mikros.
        //
        // IMPORTANT: Remember to finalize this mode with the defer call.
        s.SetupTest(ctx, test)
        defer s.TeardownTest(ctx)
                
        res, err := s.CallToServiceMethod(ctx, &args)
        test.Assert().Nil(res)
        test.Assert().Error(err)
        test.Assert().Contains("internal database error", err.Error())
    })
}

Unit test replacing the service collection

func TestFoo(t *testing.T) {
    t.Run("should succeed in this call", func (t *testing.T) {
        test := ftesting.New(t, &ftesting.Options{
            // Replace the service collection, which in this example has
            // the name 'service' with a new one.
            Collections: map[string]string{
                "service": "new_collection_name",
            },
        })

        // Initialize the test mode by replacing internal functionalities
        // of Mikros.
        //
        // IMPORTANT: Remember to finalize this mode with the defer call.
        s.SetupTest(ctx, test)
        defer s.TeardownTest(ctx)

        // Since the collection belongs only to the test, it's empty and
        // needs data for validation. So we insert a record
        // for the test.
        record := entries["completed"]
        _ = s.Database().Insert(ctx, record)
		
        res, err := s.GetRecord(ctx, &example.GetRecordRequest{
            Id: record.Id,
        })

        test.Assert().NoError(err)
        test.Assert().NotNil(res)
    })
}

Unit test of an HTTP API

func TestAPI(t *testing.T) {
    t.Run("should succeed with valid input", func(t *testing.T) {
        test := ftesting.New(t, &ftesting.Options{
            // You should initialize the `httpHandler` test within TestMain
            Handler: httpHandler.HttpHandler(),
        })

        res, err := test.Post(&ftesting.RequestOptions{
            Path: "/alert-input/v2/vehicle",
            Headers: map[string]string{
                "contract_code": sharedpb.ContractCode_CONTRACT_CODE_HORTO_0001.ValueWithoutPrefix(),
            },
            ContentType: "application/json",
            Body: &alert_inputpb.CreateAlertInputVehicleRequest{
                Alerts: []*alert_inputpb.AlertInputRequest{
                    {
                        Origin:      sharedpb.Origin_ORIGIN_ENGEBRAS,
                        PassageId:   "092834a02d932",
                        Latitude:    "-23.453",
                        Longitude:   "-46.533",
                        CaptureTime: "2021-06-11T11:04:47-03:00",
                        Plate:       "ABC1234",
                        FileUrl:     "s3://some.valid.url/image.jpg",
                        Issues: []*alert_inputpb.CreateAlertInputIssueRequest{
                            {
                                Code:        "42",
                                Description: "Licenciamento em atraso",
                            },
                        },
                    },
                },
            },
        })

        test.Assert().NoError(err)
        test.Assert().NotNil(res)

        // It's worth remembering here that the return of an HTTP API test always
        // returns a `[]byte`. This way it's necessary to convert it to the
        // desired format if it needs to be validated.
        var response *alert_inputpb.CreateAlertInputPersonalResponse
        marshal := marshaler.ProtoMarshaler
        err = marshal.Decode(res, &response)
        test.Assert().NoError(err)
        test.Assert().Equal("OK", response.GetStatus().ValueWithoutPrefix())
    })	
}

Unit test of a consumer service

func TestConsumer(t *testing.T) {
    t.Run("should succeed with valid alert input PERSONAL", func (t *testing.T) {
        test := ftesting.New(t, nil)
        ali := alertInputs["all-info-personal"].ProtoResponse()
		
        // Create a consumer with a record (`Records`) in the queue for reading.
        consumer, err := ftesting.NewDatastreamConsumption(&ftesting.DatastreamConsumptionOptions{
            StreamName: "ALERT_INPUT_CHANNEL",
            Records:    []proto.Message{ali},
        })

        test.Assert().NoError(err)
        test.Assert().NotNil(consumer)
		
        err := s.callConsumerHandler(ctx, consumer)
        test.Assert().NoError(err)
    })
}

Unit test of a subscriber service

func TestSubscriber(t *testing.T) {
    t.Run("should succeed", func(t *testing.T) {
        test := ftesting.New(t, nil)
		
        // Create an event to be sent directly to its handler.
        event, err := ftesting.NewPubsubEvent(&ftesting.PubsubEventOptions{
            Type: sharedpb.EventType_EVENT_TYPE_FILE_CREATED,
            Data: files["image"].ProtoResponse(),
        })

        test.Assert().NoError(err)
        test.Assert().NotNil(event)

        f := NewFileCreatedHandler(s)
        err = f(ctx, event)
        test.Assert().NoError(err)
    })	
}

Testing Migrations

Mikros provides a specific API for testing migration scripts. It allows selecting which scripts will be executed, in addition to using the resource of being able to be executed on an "alternative" collection, that is, with a name different from the standard. It is also possible to determine the origin of these scripts that will be executed, whether they belong to the common migration directory or a specific deploy environment.

Important: For migration tests, it is recommended to use the subsets feature to cover and test all scripts currently present in the service, one by one, that is, each subset should test up to a specific script (UpTo).

Example:

func TestDatabaseMigrations(t *testing.T) {
    t.Run("some important test is happening", func(t *testing.T) {
        test := ftesting.New(t, &ftesting.Options{
            Collections: map[string]string{
                "address": "test_migration_1",
            },
            Migration: &ftesting.MigrationOptions{
                // The last migration that will execute in this test, i.e.,
                // scripts 001 and 002 will also execute.
                UpTo: "003_add_new_field_uf.up.json",
            },
        })

        srv.SetupTest(ctx, test)
        defer srv.TeardownTest(ctx)

        // Insert some data to migrate
        adr := addresses["completed1"]
        _ = srv.Database().Insert(ctx, adr)

        err := test.Migrate(srv.ServiceName())
        test.Assert().NoError(err)

        // Validate migrated data
        // TODO
    })
}