Sebastien Arod edited this page Mar 31, 2015 · 9 revisions

From a given set of test classes, the Categories runner runs only the classes and methods that are annotated with either the category given with the @IncludeCategory annotation, or a subtype of that category. Either classes or interfaces can be used as categories. Subtyping works, so if you say @IncludeCategory(SuperClass.class), a test marked @Category({SubClass.class}) will be run.

You can also exclude categories by using the @ExcludeCategory annotation


public interface FastTests { /* category marker */ }
public interface SlowTests { /* category marker */ }

public class A {
  public void a() {

  public void b() {

@Category({SlowTests.class, FastTests.class})
public class B {
  public void c() {


@SuiteClasses( { A.class, B.class }) // Note that Categories is a kind of Suite
public class SlowTestSuite {
  // Will run A.b and B.c, but not A.a

@SuiteClasses( { A.class, B.class }) // Note that Categories is a kind of Suite
public class SlowTestSuite {
  // Will run A.b, but not A.a or B.c

Using categories with Maven

You can use categories with either maven-surefire-plugin (for unit tests) or maven-failsafe-plugin (for integration tests). Using either plugin, you can configure a list of categories to include or exclude. Without using either option, all tests will be executed by default.


Similarly, to exclude a certain list of categories, you would use the <excludedGroups/> configuration element.

Using categories with Gradle

Gradle's test task allows the specification of the JUnit categories you want to include and exclude.

test {
    useJUnit {
        includeCategories 'org.gradle.junit.CategoryA'
        excludeCategories 'org.gradle.junit.CategoryB'

Using categories with SBT

SBT's junit-interface allows the specification of JUnit categories via --include-categories=<CLASSES> and --exclude-categories=<CLASSES>.

 Typical usages for categories

Categories are used to add metadata on the tests.

The frequently encountered categories usages are about:

  • The type of automated tests: UnitTests, IntegrationTests, SmokeTests, RegressionTests, PerformanceTests ...
  • How quick the tests execute: SlowTests, QuickTests
  • In which part of the ci build the tests should be executed: NightlyBuildTests
  • The state of the test: UnstableTests, InProgressTests

This is also used to add project specific metadata like which feature of a project is covered by the test.

See usages of Junit Categories on github hosted projects