• Description
• GridJunit3TestSuite
  • GridJunit3LocalTestSuite
  • Logging
  • Test Nesting
• GridifyTest Annotation
• Configuration
  • Test Scheduling
• Starting Grid Node
• Examples

Description

Distributed JUnit support has been added starting GridGain 1.6.0 release.

You can distribute your JUnit3 test suites in 2 different ways. One way is to use GridJunit3TestSuite directly instead of the usual JUnit3 TestSuite. This is perhaps the easiest and most straight forward way to grid-enable your JUnit3 test suites.

Another way is by attaching @GridifyTest to your static suite() methods on JUnit3 test suites. The advantage of this approach is that you can provide test configuration parameters, such as timeout or custom test router right as annotation parameter in code, without having to change your existing test suites or having to pass extra VM arguments.

Package

org.gridgain.grid.test.junit3 ^Javadoc

GridJunit3TestSuite

GridJunit3TestSuite ^Javadoc is the test suite that handles distributing JUnit tests automatically. Simply add tests to this suite just like you would for regular JUnit3 suites, and these tests will be executed in parallel on the grid. Note that if there are no other grid nodes, this suite will still ensure parallel test execution within single JVM.

Bellow is an example of distributed JUnit3 test suite:

public class GridJunit3ExampleTestSuite {
    // Standard JUnit3 static suite method.
    public static TestSuite suite() {
        TestSuite suite = new GridJunit3TestSuite("Example Grid Test Suite");

        // Add tests.
        suite.addTestSuite(TestA.class);
        suite.addTestSuite(TestB.class);
        suite.addTestSuite(TestC.class);

        return suite;
    }
}

If you have four tests A, B, C, and D, and if you need to run A and B sequentially, then you should create a nested test suite with test A and B as follows:

public class GridJunit3ExampleTestSuite {
    // Standard JUnit3 static suite method.
    public static TestSuite suite() {
        TestSuite suite = new GridJunit3TestSuite("Example Grid Test Suite");

        // Nested test suite to run tests A and B sequentially.
        TestSuite nested = new TestSuite("Example Nested Sequential Suite");

        nested.addTestSuite(TestA.class);
        nested.addTestSuite(TestB.class);

        // Add tests A and B.
        suite.addTest(nested);

        // Add other tests.
        suite.addTestSuite(TestC.class);

        return suite;
    }
}

GridJunit3LocalTestSuite

Some tests can only be executed locally mostly due to some environment issues. However they still can benefit from parallel execution with other tests. GridGain supports it via GridJunit3LocalTestSuite ^Javadoc suites that can be nested within GridJunit3TestSuite ^Javadoc test suite.

To use local test suite within distributed test suite, simply add it to distributed test suite as follows:

public class GridJunit3ExampleTestSuite {
    // Local test suite example.
    public static TestSuite suite() {
        TestSuite suite = new GridJunit3TestSuite("Example Grid Test Suite");

        // Local nested test suite to always run tests A and B 
        // on the local node.
        TestSuite nested = new GridJunit3LocalTestSuite("Example Nested Sequential Suite");

        nested.addTestSuite(TestA.class);
        nested.addTestSuite(TestB.class);

        // Add local tests A and B.
        suite.addTest(nested);

        // Add other tests.
        suite.addTestSuite(TestC.class);
        suite.addTestSuite(TestD.class);

        return suite;
    }
}

Logging

When running distributed JUnit, all the logging that is done to System.out or System.err is preserved. GridGain will accumulate all logging that is done on remote nodes, send them back to originating node and associate all log statements with their corresponding tests. This way, for example, if you are running tests from and IDEA or Eclipse (or any other IDE) you would still see the logs as if it was a local run. However, since remote nodes keep all log statements done within a single individual test case in memory, you must make sure that enough memory is allocated on every node and that individual test cases do not spit out GigaBytes of log statements. Also note, that logs will be sent back to originating node upon completion of every test, so don't be alarmed if you don't see any log statements for a while and then all of them appear at once.

GridGain achieves such log transparency via reassigning System.out or System.err to internal PrintStream implementation. However, when using Log4J (or any other logging framework) within your tests you must make sure that it is configured with ConsoleAppender and that ConsoleAppender.setFollow(boolean) attribute is set to true. Logging to files is not supported yet and is planned for future releases.

Test Nesting

GridJunit3TestSuite ^Javadoc instances can be nested within each other as deep as needed. However all nested distributed test suites will be treated just like regular JUnit test suites and not as distributed test suites. This approach becomes convenient when you have several distributed test suites that you would like to be able to execute separately in distributed fashion, but at the same time you would like to be able to execute them as a part of larger distributed suites.

GridifyTest Annotation

To enable JUnit3 tests using @GridifyTest ^Javadoc annotation, simply attach this annotation to "static suite()" method for a test suite you would like to grid-enable.

public class GridifyJunit3ExampleTestSuite {
    // Standard JUnit3 suite method. Note we attach @GridifyTest
    // annotation to it, so it will be grid-enabled.
    @GridifyTest
    public static TestSuite suite() {
        TestSuite suite = new TestSuite("Example Test Suite");

        // Nested test suite to run tests A and B sequentially.
        TestSuite nested = new TestSuite("Example Nested Sequential Suite");

        nested.addTestSuite(TestA.class);
        nested.addTestSuite(TestB.class);

        // Add tests A and B.
        suite.addTest(nested);
 
        // Add other tests.
        suite.addTestSuite(TestC.class);
        suite.addTestSuite(TestD.class);

        return suite;
    }
}

For information on how to start GridGain with AOP support refer to AOP Configuration documentation. Note that only AspectJ and JBoss AOP are supported. Spring AOP is not supported as it is proxy-based and only works with interfaces.

Configuration

To run distributed JUnit tests you need to start other instances of GridGain. You can do so by running GRIDGAIN_HOME/bin/gridgain-junit.{sh|bat} script, which will start default configuration. If configuration other than default is required, then use regular GRIDGAIN_HOME/bin/gridgain.{sh|bat} script and pass your own Spring configuration file as a parameter to the script.

You can use the following configuration parameters to configure distributed test suite locally. Note that many parameters can be overridden by setting corresponding JVM parameters defined in GridTestVmParameters ^Javadoc at VM startup.

Configuration Method	Default Value	Description
setDisabled(boolean) Javadoc	false	If true then GridGain will be turned off and suite will run locally. This value can be overridden by setting GridTestVmParameters.GRID_DISABLED Javadoc JVM parameter to true. This parameter comes handy when you would like to turn off GridGain without changing the actual code.
setConfigurationPath(String) Javadoc	config/junit/junit-spring.xml	Optional path to GridGain Spring configuration file for running JUnit tests. This property can be overridden by setting GridTestVmParameters.GRID_CONFIG Javadoc VM parameter. Note that the value can be either absolute value or relative to GRIDGAIN_HOME installation folder.
setRouterClassName(String) Javadoc	GridTestRouterAdapter Javadoc class name.	Optional name of test router class that implements GridTestRouter Javadoc interface. If not provided, then tests will be routed in round-robin fashion using default GridTestRouterAdapter Javadoc . The value of this parameter can be overridden by setting GridTestVmParameters.GRID_TEST_ROUTER Javadoc VM parameter to the name of your own custom router class.
GRID_ROUTER_PREFER_REMOTE Javadoc	false	This value can only be set as VM parameter. Set it to true, e.g. -DGRID_ROUTER_PREFER_REMOTE=true, if you would like test router to not route tests to local node if there are remote nodes present. Note that this property works only with default test router.
setRouterClass(Class) Javadoc	null	Same as setRouterClassName(String) Javadoc , but sets the actual class instead of the name.
setTimeout(long) Javadoc	0 which means that tests will never timeout.	Maximum timeout value in milliseconds after which test suite will return without waiting for the remaining tests to complete. This value can be overridden by setting GridTestVmParameters.GRID_TEST_TIMEOUT Javadoc JVM parameter to the timeout value for the tests.

Test Scheduling

With GridGain you can configure how many tests you can run in parallel by specifying parallelJobsNumber configuration parameter on GridCollisionSpi ^Javadoc . Simply uncomment the following section in GRIDGAIN_HOME/config/junit/junit-spring.xml file:

<property name="collisionSpi">
    <bean class="org.gridgain.grid.spi.collision.fifoqueue.GridFifoQueueCollisionSpi">
        <property name="parallelJobsNumber" value="1"/>
    </bean>
</property>

The XML configuration above will guarantee that only 1 test can run at a time on local or remote nodes. You can ensure this way that although your tests run in parallel on different nodes, within a single node only one test can be running and all other ones are waiting.

Starting Grid Node

To start a remote node for JUnit tests, open the terminal window on Linux/Mac OS X or Command Prompt on Windows, change directory to ${GRIDGAIN_HOME}/bin and run the gridgain.{sh|bat} script. However, distributed JUnits have to use GridTestExecutorService ^Javadoc which is pre-configured in ${GRIDGAIN_HOME}/config/junit/junit-spring.xml Spring configuration file. You need to specify a path to this file to the gridgain startup script as follows:

gridgain.bat config/junit/junit-spring.xml

or starting from GridGain 1.6.1, simply execute gridgain-junit.{sh|bat} script.

gridgain-junit.bat

It takes 2-3 seconds for grid node to start and if everything worked fine you should see starting log ending with successful start acknowledgment.

Examples

GridGain comes with several examples for distributed JUnit3. Please refer to JUnit3 - Distributed JUnit Example for example of how to use GridJunit3TestSuite ^Javadoc or to JUnit3 - Distributed JUnit with GridifyTest Example for example on how to use @GridifyTest ^Javadoc annotation to grid-enable your tests.