or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-org-junit-platform--junit-platform-runner

JUnit 4 based Runner which runs tests on the JUnit Platform in a JUnit 4 environment

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.junit.platform/junit-platform-runner@1.12.x

To install, run

npx @tessl/cli install tessl/maven-org-junit-platform--junit-platform-runner@1.12.0

index.mddocs/

JUnit Platform Runner

JUnit Platform Runner is a JUnit 4 based Runner that allows tests to be executed on the JUnit Platform in a JUnit 4 environment. It serves as a bridge component enabling JUnit 5 (Jupiter) tests to run in environments that support JUnit 4 but do not yet support the JUnit Platform directly.

⚠️ Deprecated Notice: This module is deprecated since JUnit Platform 1.8 in favor of junit-platform-suite-engine with @Suite annotation support, and is scheduled for removal in JUnit Platform 2.0.

Package Information

  • Package Name: org.junit.platform:junit-platform-runner
  • Package Type: Maven
  • Language: Java
  • Version: 1.12.2
  • Installation: 
    <dependency>
  <groupId>org.junit.platform</groupId>
  <artifactId>junit-platform-runner</artifactId>
  <version>1.12.2</version>
</dependency>

Core Imports

import org.junit.platform.runner.JUnitPlatform;
import org.junit.runner.RunWith;
import org.junit.runner.manipulation.Filter;
import org.junit.runner.manipulation.NoTestsRemainException;
import org.junit.runner.notification.RunNotifier;
import org.junit.runner.Description;

Additional imports for configuration:

import org.junit.platform.suite.api.*;

Basic Usage

Running a Single Test Class

import org.junit.jupiter.api.Test;
import org.junit.runner.RunWith;
import org.junit.platform.runner.JUnitPlatform;

@RunWith(JUnitPlatform.class)
public class MyJUnit5TestClass {
    
    @Test
    void shouldPassTest() {
        // JUnit 5 test logic
    }
    
    @Test
    void anotherTest() {
        // Another JUnit 5 test
    }
}

Creating a Test Suite

import org.junit.runner.RunWith;
import org.junit.platform.runner.JUnitPlatform;
import org.junit.platform.suite.api.*;

@RunWith(JUnitPlatform.class)
@SuiteDisplayName("My Test Suite")
@SelectPackages("com.example.tests")
@ExcludeTags("slow")
public class MyTestSuite {
    // Empty class body - configuration is done via annotations
}

Architecture

The JUnit Platform Runner serves as a bridge between JUnit 4 and the JUnit Platform, enabling JUnit 5 tests to run in JUnit 4 environments:

  • Runner Pattern: Implements JUnit 4's Runner interface to integrate with existing build tools and IDEs
  • Test Discovery: Uses JUnit Platform's discovery API to find and organize tests
  • Event Translation: Translates JUnit Platform test execution events into JUnit 4 notification events
  • Suite Configuration: Supports extensive configuration through annotations from junit-platform-suite-api

The runner discovers tests using JUnit Platform mechanisms, builds an internal test tree representation, then executes tests while translating events to JUnit 4's RunNotifier system for compatibility with existing tooling.

Capabilities

JUnitPlatform Runner

The main Runner class that enables JUnit Platform tests to run in JUnit 4 environments.

/**
 * JUnit 4 based Runner which runs tests on the JUnit Platform in a JUnit 4 environment.
 * Annotating a class with @RunWith(JUnitPlatform.class) allows it to be run with IDEs 
 * and build systems that support JUnit 4 but do not yet support the JUnit Platform directly.
 * 
 * Note: Test classes and suites annotated with @RunWith(JUnitPlatform.class) cannot be 
 * executed directly on the JUnit Platform and can only be executed using JUnit 4 infrastructure.
 * 
 * @since 1.0
 * @deprecated since 1.8, in favor of the @Suite support provided by junit-platform-suite-engine;
 *             to be removed in JUnit Platform 2.0
 * @status DEPRECATED
 */
@Deprecated
public class JUnitPlatform extends Runner implements Filterable {
    
    /**
     * Creates a new JUnitPlatform runner for the specified test class.
     * @param testClass the test class to run; must be public to be picked up by IDEs and build tools
     */
    public JUnitPlatform(Class<?> testClass);
    
    /**
     * Returns the suite description for the test tree.
     * @return Description object representing the test suite
     */
    @Override
    public Description getDescription();
    
    /**
     * Executes the tests using the provided RunNotifier.
     * @param notifier the RunNotifier to report test execution events
     */
    @Override
    public void run(RunNotifier notifier);
    
    /**
     * Applies a filter to limit which tests are executed.
     * @param filter the Filter to apply
     * @throws NoTestsRemainException if no tests remain after filtering
     */
    @Override
    public void filter(Filter filter) throws NoTestsRemainException;
}

Usage Examples:

// Basic test class usage - must be public
@RunWith(JUnitPlatform.class)
public class SimpleTestClass {
    @Test
    void testMethod() {
        // test implementation
    }
}

// Test suite with package selection and tag filtering
@RunWith(JUnitPlatform.class)
@SelectPackages({"com.example.unit", "com.example.integration"})
@ExcludeTags("slow")
@IncludeTags("important | critical")  // Tag expression with OR
public class ComprehensiveTestSuite {
}

// Configuration with parameters
@RunWith(JUnitPlatform.class)
@SelectClasses({DatabaseTest.class, NetworkTest.class})
@ConfigurationParameter(key = "junit.jupiter.execution.parallel.enabled", value = "true")
@ConfigurationParameter(key = "junit.jupiter.execution.parallel.mode.default", value = "concurrent")
public class ParallelTestSuite {
}

Test Selection Annotations

Annotations for selecting which tests to include in the test run.

/**
 * Select specific test classes to include
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface SelectClasses {
    /** One or more classes to select */
    Class<?>[] value() default {};
    
    /** 
     * One or more classes to select by their fully qualified names
     * @since 1.10
     * @status EXPERIMENTAL
     */
    String[] names() default {};
}

/**
 * Select tests from specific packages
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface SelectPackages {
    String[] value();
}

/**
 * Select tests from classpath resources
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface SelectClasspathResource {
    String value();
}

/**
 * Select tests from specific directories  
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface SelectDirectories {
    String[] value();
}

/**
 * Select tests from specific files
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface SelectFile {
    String value();
}

/**
 * Select tests from specific modules
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface SelectModules {
    String[] value();
}

/**
 * Select tests using URIs
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface SelectUris {
    String[] value();
}

Test Filtering Annotations

Annotations for filtering tests based on various criteria.

/**
 * Include tests matching class name patterns
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface IncludeClassNamePatterns {
    /** Default pattern matches Test classes/methods */
    String[] value() default "^(Test.*|.+[.$]Test.*|.*Tests?)$";
}

/**
 * Exclude tests matching class name patterns
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface ExcludeClassNamePatterns {
    String[] value();
}

/**
 * Include specific test engines
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface IncludeEngines {
    String[] value();
}

/**
 * Exclude specific test engines
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface ExcludeEngines {
    String[] value();
}

/**
 * Include specific packages
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface IncludePackages {
    String[] value();
}

/**
 * Exclude specific packages
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface ExcludePackages {
    String[] value();
}

/**
 * Include tests with specific tags. Supports tag expressions
 * with operators: ! (not), & (and), | (or), and parentheses.
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface IncludeTags {
    String[] value();
}

/**
 * Exclude tests with specific tags. Supports tag expressions
 * with operators: ! (not), & (and), | (or), and parentheses.
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface ExcludeTags {
    String[] value();
}

Display and Configuration Annotations

Annotations for customizing test display and configuration.

/**
 * Set custom display name for test suite
 * @since 1.0
 * @status MAINTAINED
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface SuiteDisplayName {
    String value();
}

/**
 * Use technical names instead of display names
 * @deprecated since 1.8, to be removed in JUnit Platform 2.0
 * @since 1.0
 * @status DEPRECATED
 */
@Deprecated
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface UseTechnicalNames {
}

/**
 * Set configuration parameters (repeatable annotation)
 * @since 1.8
 * @status STABLE
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@Repeatable(ConfigurationParameters.class)
public @interface ConfigurationParameter {
    String key();
    String value();
}

/**
 * Container for multiple configuration parameters
 * @since 1.8
 * @status STABLE
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface ConfigurationParameters {
    ConfigurationParameter[] value();
}

/**
 * Load configuration from resource
 * @since 1.8
 * @status STABLE
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface ConfigurationParametersResource {
    String value();
}

Modern Suite Annotation (Replacement)

The modern @Suite annotation that replaces the deprecated JUnit Platform Runner.

/**
 * Marks a class as a test suite on the JUnit Platform. This is the modern
 * replacement for @RunWith(JUnitPlatform.class).
 * @since 1.8
 * @status STABLE
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface Suite {
    /**
     * Configures whether the test suite should fail if no tests are found.
     * @since 1.9
     */
    boolean failIfNoTests() default true;
}

Dependencies

The JUnit Platform Runner requires the following dependencies:

Core Dependencies:

  • junit:junit (JUnit 4) - Required for Runner infrastructure
  • org.junit.platform:junit-platform-launcher - Required for test discovery and execution
  • org.junit.platform:junit-platform-suite-api - Required for configuration annotations

Optional Dependencies:

  • org.apiguardian:apiguardian-api - Provides API status annotations

Migration Path

Since this runner is deprecated, consider migrating to the modern approach:

Old (Deprecated):

@RunWith(JUnitPlatform.class)
@SelectPackages("com.example")
public class TestSuite {}

New (Recommended):

@Suite
@SelectPackages("com.example")
public class TestSuite {}

The new approach requires junit-platform-suite-engine instead of junit-platform-runner.

Limitations

  • Test classes run with this runner cannot be executed directly on the JUnit Platform
  • Only works in JUnit 4 environments - cannot run as native JUnit 5 tests
  • Deprecated and will be removed in JUnit Platform 2.0
  • Test classes must be public to be picked up by IDEs and build tools
  • When used without configuration annotations, uses default include pattern for class discovery