ballerina/test

Module Overview

This module facilitates writing tests for Ballerina code in a simple manner. It provides a number of capabilities such as configuring the setup and cleanup steps at different levels, ordering and grouping of tests, providing value-sets to tests, and independence from external functions and endpoints via mocking capabilities.

Annotations

A Ballerina testsuite can be implemented using a set of annotations. The available annotations enable executing instructions before and after the testsuite or a single test, organize a set of tests into a group, define data-driven tests, specify an order of execution, disable tests and mocking.

Test Config

The following example shows a simple testsuite.

The before and after attributes can be used to set the execution order by specifying the functions to run before and/or after the test.

The dependsOn attribute can also be used to set the test execution order by specifying the list of functions that the test function depends on.

The dataProvider attribute can be used to assign a function to act as a data provider for a test. The data provider can return data as a map of tuples or as an array of arrays. If there is an issue while generating the data set, it can return an error which will be handled by the test framework.

Before and After Suite

The BeforeSuite annotation is used to execute a particular function before the test suite is executed. This can be used to setup the prerequisites before executing the test suite.

The AfterSuite annotation is used to execute a particular function after the test suite is executed. This is used to tear-down the prerequisites or execute post actions after executing the test suite.

Before and After Groups

The BeforeGroups and annotation can be used to execute the function before the first test function belonging the specified groups.

The AfterGroups and annotation can be used to execute the function after the last test function belonging the specified groups.

Assertions

This module provides a number of assertions in order to verify the expected behaviour of a piece of code. These assertions can be used to decide if the test is passing or failing based on the condition.

Following sample shows how to use assertions in Testerina.

Mocking

The test module provides capabilities to mock a function or an object for unit testing. The mocking features can be used to control the behavior of functions and objects by defining return values or replacing the entire object or function with a user-defined equivalent. This feature will help you to test the Ballerina code independently from other modules and external endpoints.

Function Mocking

Function mocking allows to control the behavior of a function in the module being tested or a function of an imported module.

The annotation @test:Mock {} is used to declare a MockFunction object, with details of the name of the function to be mocked, as well as the module name if an import function is being mocked. The module name value of the annotation is optional if the function being mocked is not an import function.

Declaring the annotation with this object will create a default mock object in place of the original function. Subsequent to the declaration, the function call should be stubbed using the available mocking features. Different behaviors can be defined for different test cases if required.

Samples

main.bal

test.bal

The following example shows different ways of stubbing a function call.

Object Mocking

Object mocking enables controlling the values of member variables and the behavior of the member functions of an object. This is vital when working with client objects as the remote functions can be stubbed to return a mock value without having to actually make calls to the remote endpoint.

Mocking of objects can be done in two ways.The available features provide the functionality to substitute the real object with a user-defined mock object or to stub the behavior of required functions.

1. Creating a test double (providing an equivalent object in place of the real)
2. Stubbing the member function or member variable (specifying the behavior of functions and values of variables)

Creating a test double is suitable when a single mock function/object can be used throughout all tests whereas stubbing is ideal when defining different behaviors for different test cases is required.

Creating a test double

A custom mock object can be defined in place of the real object which should contain the member variables and functions that need to be replaced. The custom object should be made structurally equivalent to the real object via the mocking features in the test module. A runtime exception will be thrown if any of the defined functions or variables is not equivalent to the counterpart of the original object.

main.bal

test.bal

Stubbing member functions and variables of an object

The member functions and variables are stubbed to return a specific value or to do nothing when invoked. Using the test module, a default mock object of the specified type. The default action of any member function/variable is to panic upon invocation/retrieval. After mock object creation, the required functions and variables of the default mock object should be stubbed to return a value or to do nothing when called.

Samples

The following example demonstrates how to stub a member function to return a specific value.

The following example demonstrates how to stub a member function to return different values on subsequent calls.

The following example demonstrates how to stub a member function to do nothing when called.

The following example shows how to return a value when a member variable is accessed.