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
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.