com.carrotsearch.examples.randomizedrunner.Test012TestGroups Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of randomizedtesting-examples Show documentation

Simple use-case examples meant to be included in some end-user documentation if it's ever going to be written...

There is a newer version: 2.1.17

Show newest version

package com.carrotsearch.examples.randomizedrunner;

import java.lang.annotation.*;

import org.junit.Test;

import com.carrotsearch.randomizedtesting.RandomizedRunner;
import com.carrotsearch.randomizedtesting.RandomizedTest;
import com.carrotsearch.randomizedtesting.annotations.Nightly;
import com.carrotsearch.randomizedtesting.annotations.TestGroup;

/**
 * We introduced the notion of {@link Nightly} tests in
 * {@link Test011NightlyTests}. Similar to this idea, the user can introduce any
 * number of custom test groups which can be arbitrarily enabled or disabled. In
 * fact, {@link Nightly} is also defined as such a {@link TestGroup}.
 * 
 * 
 * A custom test group is an annotation itself annotated with a
 * {@link TestGroup}. For example, let's say we want a test group that marks all
 * tests that require a physical display. An annotation for this is shown in
 * {@link Test012TestGroups.RequiresDisplay}. It has no additional attributes.
 * What makes it a test group is a meta-annotation:
 * 
 * 
 * {@literal @}{@link TestGroup}(name = "requiresdisplay", enabled = false, sysProperty = "display")
 * 
 * 
 * which states that the group's name is "requiresdisplay" and that the group is
 * initially disabled unless a system property "display" is set to a boolean
 * value "false", "off" or "disabled".
 * 
 * 
 * {@link Nightly} is defined in a very similar way. Note that test groups are
 * real annotations so they are recognizable by IDEs, can be searched,
 * manipulated etc.
 * 
 * 

 * Another feature of using {@link RandomizedRunner} with groups is the ability to specify
 * complex group-based filters specified via tests.filter system property.
 * These filters are boolean conditions, with optional parentheses. For example:
 * 

 *  {@literal @}nightly - runs all tests with test group named nightly.
 *  not {@literal @}nightly - runs all tests not annotated with a test group named nightly.
 *  {@literal @}fast and not {@literal @}requiresdisplay - runs all tests annotated with fast and not annotated with requiresdisplay.
 *  not ({@literal @}slow or {@literal @}nightly) - skips any tests annotated with slow or nightly.  
 * 
 * 
 * Important! Note that using filtering expression has precedence over the default state of a group
 * and its corresponding system property. This is intentional so that filtering expressions can be used
 * independently of each group's default state. Should the default state be taken into account one
 * can use a special keyword default, as in:
 * 
 *  default and not {@literal @}slow - runs any tests that would be selected by their default
 *  group status (including those that do not have any test groups at all), 
 *  excluding any tests annotated with slow. 
 *    
 */
public class Test012TestGroups extends RandomizedTest {
  @TestGroup(name = "requiresdisplay", enabled = false, sysProperty = "display")
  @Retention(RetentionPolicy.RUNTIME)
  @Target({ElementType.METHOD})
  public static @interface RequiresDisplay {}
  
  @Test
  @RequiresDisplay
  public void usesDisplay() {
    System.out.println("Running on windows.");
  }
}