Junit 5 – ConsoleLauncher

The Junit 5 ConsoleLauncher is a stand-alone application for launching or running the JUnit Platform tests from the console. This article shows you how to use the JUnit 5 ConsoleLauncher to run tests from a command line with several examples. You can run parallel tests also from ConsoleLauncher.

ConsoleLauncher allows you to run JUnit Vintage ( JUnit 3 and JUnit 4 based ) and JUnit Jupiter (Junit 5 based) tests.

Technologies used in following Examples :

• JUnit 5.5.2
• junit-platform-console-standalone 1.6.0

1. Download Junit platform standalone Jar

We need to download an executable junit-platform-console-standalone-1.6.0.jar , it is available at maven central repository.

2. Run tests with options

In order to run your Junit 5 tests from ConsoleLuncher, you need to set class path of your tests and dependent classes. In my case test classes generated in build/classes/java/test folder and application related classes generated in build/classes/java/main folder.

Let’s run Junit 5 tests cases using ConsoleLauncher with different options.

Example 1 : Run specific test cases :

To run specific test cases use option -c CLASS, OR --select-class CLASS. With this option select a class for test discovery. This option can be repeated.

$ java -jar junit-platform-console-standalone-1.6.0.jar 
     --classpath build/classes/java/test:build/classes/java/main 
     -c com.javabydeveloper.util.Junit5_Dynamic_Tests_Parallel_Test

$ java -jar junit-platform-console-standalone-1.6.0.jar 
     --classpath build/classes/java/test:build/classes/java/main 
     -select-class com.javabydeveloper.util.Junit5_Dynamic_Tests_Parallel_Test

I am trying run following Dynamic Test case.

public class Junit5_Dynamic_Tests_Parallel_Test {
	
	@Execution(ExecutionMode.CONCURRENT)
	@TestFactory
	Collection<DynamicTest> test_parallel_dynamictests1() {
		
	    return Arrays.asList(
	            dynamicTest("1st dynamic test", () -> { 
	            	assertTrue(MathUtil.isPrime(13)); 
	            	System.out.println(Thread.currentThread().getName()+" => 1st dynamic test");
	            }),
	            dynamicTest("2nd dynamic test", () -> {
	            	assertEquals(5, MathUtil.devide(25, 5));
	            	System.out.println(Thread.currentThread().getName()+" => 2nd dynamic test");
	            }),
	            dynamicTest("3rd dynamic test", () -> { 
	            	assertEquals(12, MathUtil.add(7, 5)); 
	            	System.out.println(Thread.currentThread().getName()+" => 3rd dynamic test");
	            })
	        );
	  }
	
	@Execution(ExecutionMode.SAME_THREAD)
	@TestFactory
	Collection<DynamicTest> test_parallel_dynamictests2() {
		
	    return Arrays.asList(
	            dynamicTest("4th dynamic test", () -> { 
	            	assertTrue(MathUtil.isPrime(13)); 
	            	System.out.println(Thread.currentThread().getName()+" => 4th dynamic test");
	            }),
	            dynamicTest("5th dynamic test", () -> {
	            	assertEquals(5, MathUtil.devide(25, 5));
	            	System.out.println(Thread.currentThread().getName()+" => 5th dynamic test");
	            }),
	            dynamicTest("6th dynamic test", () -> { 
	            	assertEquals(12, MathUtil.add(7, 5)); 
	            	System.out.println(Thread.currentThread().getName()+" => 6th dynamic test");
	            })
	        );
	  }
}

Following is the output :

Example 2 : Run tests in specific package :

To run specific test cases in package use option -p PKG, OR --select-package PKG . This option can be repeated.

$ java -jar junit-platform-console-standalone-1.6.0.jar 
     --classpath build/classes/java/test:build/classes/java/main 
     -p com.javabydeveloper.util

$ java -jar junit-platform-console-standalone-1.6.0.jar 
     --classpath build/classes/java/test:build/classes/java/main 
     -select-package com.javabydeveloper.util

Example 3 : Filter and include run tag specific tests :

To run test cases based on Tags, use option -t TAG, OR --include-tag TAG. When this option is repeated, all patterns will be combined using OR semantics.

$ java -jar junit-platform-console-standalone-1.6.0.jar 
    --classpath build/classes/java/test:build/classes/java/main
    -p com.javabydeveloper.tag -t 'api | security' 

$ java -jar junit-platform-console-standalone-1.6.0.jar 
    --classpath build/classes/java/test:build/classes/java/main
    -p com.javabydeveloper.tag --include-tag 'api | security' 

Example 4 : Filter and Exclude run tag specific tests :

To run specific tagged test cases use option -T TAG, OR --exclude-tag TAG . When this option is repeated, all patterns will be combined using OR semantics.

$ java -jar junit-platform-console-standalone-1.6.0.jar 
    --classpath build/classes/java/test:build/classes/java/main
    -p com.javabydeveloper.tag -T 'accessibility' 

$ java -jar junit-platform-console-standalone-1.6.0.jar 
    --classpath build/classes/java/test:build/classes/java/main
    -p com.javabydeveloper.tag --exclude-tag 'accessibility' 

Example 5 : Run Parallel tests :

Following is the command to run all the tests with in package parallel. For the parallel tests we need to set configuration parameters, and configuration parameters we can set to ConsoleLauncher using --config which can be repeated.

java -jar junit-platform-console-standalone-1.6.0.jar 
    --classpath build/classes/java/test:build/classes/java/main 
    -p com.javabydeveloper.util 
    --config=junit.jupiter.execution.parallel.enabled=true 
    --config=junit.jupiter.execution.parallel.mode.default=concurrent

3. Junit 5 ConsoleLauncher exit code

1. The ConsoleLauncher exits with a status code of 1 if any containers or tests failed.
2. If no tests are discovered and the --fail-if-no-tests command-line option is supplied, the ConsoleLauncher exits with a status code of 2. Otherwise the exit code is 0.

You also might be interested in following examples

1. Junit 5 Dynamic Tests
2. Junit 5 tags and filter tests
3. Junit 5 Timeout tests
4. Junit 5 test order
5. Junit 5 maven example
6. Junit 5 Disable tests
7. Junit 5 parameterized Tests

References

1. Junit 5 document
2. Junt 5 Dynamic Tests
3. Junit 5 Tags and Filter
4. Junit 5 parale execution