Test services and clients

Testing Ballerina services involves sending specific requests to the service using a client and verifying the responses using the assertion functions. The aim is to make sure that the service and client behave as expected when sending and recieving both expected requests and malformed ones.

Test services

Any services defined in the package will start up on the specified ports and will remain running for the duration of the testing phase. After completing tests, the services will shut down automatically. It allows you to send requests directly to the service to test its functionality.

Note: The service starts automatically, only if you have tests in the module where it is defined.


To test a service, you can create a client in the test source, which sends requests directly to the service and use the test assertion functions to assert the responses. This can be used for both external services and services defined in the package as well.



Test clients

In cases where a fully fledged client is already defined for a particular service, you can make use of object mocking to mock the calls to the service and return curated responses to the client. It is useful when testing the full extent of the client by mocking responses that are difficult to reproduce in actual scenarios. It would cover a variety of cases that the client can handle without having the service to be up and running.

Example: The following is a simple example on how mocking can be used to stub responses to services that you may not be able to access during the test execution.

To lean more about how to use mocking to test services, see Mocking.

Configure services and clients

Service or client configurations can be defined for testing using Configurable variables. Maintaining a test configurable configuration allows us to re-define the host or port as required. For example, when defining a service, the value for the host or port can be specified in the Config.toml file, which will be used specifically when running the tests.



The Config.toml must be placed in the tests folder for the values to be applied during execution.