Quick Start

The Ballerina Language has a built-in robust test framework, which allows you to achieve multiple levels of the test pyramid including unit testing, integration testing, and end to end testing. It provides features such as assertions, data providers, mocking, and code coverage, which enable the programmers to write comprehensive tests.

Writing a simple function
What’s Next?

Writing a simple function

To get started, let’s write a simple Ballerina function and test it.

First, let’s create a Ballerina project and add a new module. Use the ballerina new command to create the project. For more information on the command, see Structuring Ballerina Code.

The standard project will have the structure below.

 project-name/
     Ballerina.toml         
     src/
         module1/           	
             main.bal   
             Module.md
             [resources/]
             tests/
                 main_test.bal
                 [resources]	   

Now, let’s write the function, which handles sending a get request in the main.bal file of the module you just created.

 // main.bal
    
 import ballerina/io;
 import ballerina/http;
 import ballerina/stringutils;
    
 http:Client clientEndpoint = new("https://api.chucknorris.io/jokes/");
    
 // This function performs a `get` request to the Chuck Norris API and returns a random joke 
 // with the name replaced by the provided name or an error if the API invocation fails.
 function getRandomJoke(string name) returns string|error {
     http:Response|error result = clientEndpoint->get("/random");
     http:Response response = <http:Response>result;
     if (response.statusCode == http:STATUS_OK) {
         json payload = <json>response.getJsonPayload();
         json joke = <json>payload.value;
         string replacedText = stringutils:replace(joke.toJsonString(), "Chuck Norris", name);
         return replacedText;
     } else {
         error err = error("error occurred while sending GET request");
         io:println(err.message(),
             ", status code: ", response.statusCode,
             ", reason: ", response.getJsonPayload());
         return err;
     }
 }

Now, let’s write a simple test case to verify the behavior of the main function in the main_test.bal file.

 // main_test.bal
 import ballerina/io;
 import ballerina/test;
 import ballerina/http;
    
 // This test function tests the behavior of the `getRandomJoke` when
 // the API returns a successful response.
 @test:Config {}
 function testGetRandomJoke() {
     // Create a default mock HTTP Client and assign it to the `clientEndpoint`
     clientEndpoint = test:mock(http:Client);
     // Stub the behavior of the `get` function to return the specified mock response.
     test:prepare(clientEndpoint).when("get").thenReturn(getMockResponse());
     // Invoke the function to test.
     string result = checkpanic getRandomJoke("Sheldon");
     io:println(result);
     // Verify the return value.   
     test:assertEquals(result, "When Sheldon wants an egg, he cracks open a chicken.");
 }
    
 // Returns a mock HTTP response to be used for the jokes API invocation.
 function getMockResponse() returns http:Response {
     http:Response mockResponse = new;
     json mockPayload = {"value":"When Chuck Norris wants an egg, he cracks open a chicken."};
     mockResponse.setPayload(mockPayload);
     return mockResponse;
 }

Finally, let’s execute the tests using the following command.

$ ballerina test --code-coverage --all

This will print an output similar to the following.

 Compiling source
     foo/joke:0.1.0
    
 Creating balos
     target/balo/joke-2020r2-any-0.1.0.balo
    
 Running Tests with Coverage
     foo/joke:0.1.0
 When Sheldon wants an egg, he cracks open a chicken.
    
     [pass] testGetRandomJoke
    
     1 passing
     0 failing
     0 skipped
    
 Generating Test Report
     target/test_results.json
    
     View the test report at: file:///home/foo/test/sample-project/target/report/index.html

What’s Next?

Now, that you have an understanding of how a test case can be written and executed, you can dive deep into the available features in Writing Tests.