WSO2 Test Automation Framework : Start multiple server instances with different system properties.

WSO2 products servers can be started by providing different system properties.
In order to test certain product features you might need to start the servers with specific server properties. Some of those system properties are mentioned below.

 system-properties:  
   -DhttpPort=           Overrides the HTTP port defined in the config files.  
   -DhttpsPort=          Overrides the HTTPS port defined in the config files.  
   -DosgiConsole=[port]   Start Carbon with Equinox OSGi console.  
   -DportOffset=[port]     Start server with different port offsets.  
   -Dsetup              Can be used to start server after dropping the database  

This post will illustrate how to start WSO2 product servers by providing system properties, and writing integration tests to run on the newly started instances. The test framework start default server instances on default product ports before all test suites.Thus, starting another server on the default product ports on the same host will cause port binding errors. In order to start multiple server instances, you have to set -DportOffset property. If you are going to run multiple product instances on same host for integration tests then setting port offset property is a must.

MultipleServersManager (org.wso2.carbon.automation.core.MultipleServersManager)

The test framework provides MultipleServersManager.java which acts as a container for multiple carbon instances. To use this class, you have to Implement a TestServerManager instance for different types of servers. e.g. AS, ESB etc. Then create a class with appropriate testNG annotation to start server before you suite or test class execution.

TestServerManager (org.wso2.carbon.automation.core.TestServerManager)

TestServerManager is responsible for preparing a Carbon server for test executions, and it shutdown the server after test executions.All test suites/classes which require starting of a new server instance should extend this class.

How to start multiple product instances in integration tests.

Following code sample demonstrate the usage of TestServerManager class. It implement CarbonTestServerManager as the container for TestServerManager instances.

 import java.io.IOException;  
 import java.util.Map;  
   
 import org.wso2.carbon.automation.core.TestServerManager;  
   
 public class CarbonTestServerManager extends TestServerManager {  
   
   public CarbonTestServerManager() {  
   }  
   
   public CarbonTestServerManager(String carbonZip, Map<String, String> startupParameterMap) {  
     super(carbonZip, startupParameterMap);  
   }  
   
   public CarbonTestServerManager(int portOffset) {  
     super(portOffset);  
   }  
   
   public String startServer() throws IOException {  
     String carbonHome = super.startServer();  
     System.setProperty("carbon.home", carbonHome);  
     return carbonHome;  
   }  
   
   public void stopServer() throws Exception {  
     super.stopServer();  
   }  
   
   protected void copyArtifacts(String carbonHome) throws IOException {  
   }  
 }  

Following Test class demonstrates the usage of CarbonServerManager to start two ESB instances with different port offsets. In order to start server instances with different system properties, you need to define a HashMap and put all system properties as key value pairs. Once the map is passed to multiple server manager, the framework will start new server instance with all provided system properties.

 public class NewInstanceTestCase extends CarbonTestServerManager {  
   public MultipleServersManager manager = new MultipleServersManager();  
   public Map<String, String> startupParameterMap1 = new HashMap<String, String>();  
   public Map<String, String> startupParameterMap2 = new HashMap<String, String>();  
   
   @SetEnvironment(executionEnvironments = {ExecutionEnvironment.integration_all})  
   @BeforeClass(groups = {"esb.multi.server"})  
   public void testStartServers() throws IOException {  
     startupParameterMap1.put("-DportOffset", "10");  
     CarbonTestServerManager server1 = new CarbonTestServerManager(System.getProperty("carbon.zip"),  
                                    startupParameterMap1);  
     startupParameterMap2.put("-DportOffset", "20");  
     CarbonTestServerManager server2 = new CarbonTestServerManager(System.getProperty("carbon.zip"),  
                                    startupParameterMap2);  
     manager.startServers(server1, server2);  
   }  
   
   @SetEnvironment(executionEnvironments = {ExecutionEnvironment.integration_all})  
   @Test(groups = {"esb.multi.server"})  
   public void test() {  
     System.out.println("Test server startup with system properties");  
   }  
   
   @SetEnvironment(executionEnvironments = {ExecutionEnvironment.integration_all})  
   @AfterClass  
   public void clean() throws Exception {  
     manager.stopAllServers();  
   }  
 }  

Also note that since test case is depending on carbon zip file to start server instances, you have to use custom annotation @SetEnvironment to skip the test from platform setup. In the above example, test case will be executed only on integration level.

You can find the test case source at here