Description (JUnit API)
Date: 2018-08-04

org.junit.runner

## Class Description

- java.lang.Object
- - org.junit.runner.Description

- All Implemented Interfaces:
    java.io.Serializable

      public class Description
      extends java.lang.Object
      implements java.io.Serializable

  A `Description` describes a test which is to be run or has been run. `Descriptions` can be atomic (a single test) or compound (containing children tests). `Descriptions` are used to provide feedback about the tests that are about to run (for example, the tree view visible in many IDEs) or tests that have been run (for example, the failures view).

  `Descriptions` are implemented as a single class rather than a Composite because they are entirely informational. They contain no logic aside from counting their tests.

  In the past, we used the raw `TestCase`s and `TestSuite`s to display the tree of tests. This was no longer viable in JUnit 4 because atomic tests no longer have a superclass below `Object`. We needed a way to pass a class and name together. Description emerged from this.

  Since:
    4.0
  See Also:
    `Request`, `Runner`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Description` | `EMPTY` Describes a Runner which runs no tests
    `static Description` | `TEST_MECHANISM` Describes a step in the test-running mechanism that goes so wrong no other description can be used (for example, an exception thrown from a Runner's constructor

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addChild(Description description)` Add `Description` as a child of the receiver.
    `Description` | `childlessCopy()`
    `static Description` | `createSuiteDescription(java.lang.Class<?> testClass)` Create a `Description` named after `testClass`
    `static Description` | `createSuiteDescription(java.lang.String name, java.lang.annotation.Annotation... annotations)` Create a `Description` named `name`.
    `static Description` | `createSuiteDescription(java.lang.String name, java.io.Serializable uniqueId, java.lang.annotation.Annotation... annotations)` Create a `Description` named `name`.
    `static Description` | `createTestDescription(java.lang.Class<?> clazz, java.lang.String name)` Create a `Description` of a single test named `name` in the class `clazz`.
    `static Description` | `createTestDescription(java.lang.Class<?> clazz, java.lang.String name, java.lang.annotation.Annotation... annotations)` Create a `Description` of a single test named `name` in the class `clazz`.
    `static Description` | `createTestDescription(java.lang.String className, java.lang.String name, java.lang.annotation.Annotation... annotations)` Create a `Description` of a single test named `name` in the 'class' named `className`.
    `static Description` | `createTestDescription(java.lang.String className, java.lang.String name, java.io.Serializable uniqueId)` Create a `Description` of a single test named `name` in the class `clazz`.
    `boolean` | `equals(java.lang.Object obj)`
    `<T extends java.lang.annotation.Annotation> T` | `getAnnotation(java.lang.Class<T> annotationType)`
    `java.util.Collection<java.lang.annotation.Annotation>` | `getAnnotations()`
    `java.util.ArrayList<Description>` | `getChildren()` Gets the copy of the children of this `Description`.
    `java.lang.String` | `getClassName()`
    `java.lang.String` | `getDisplayName()`
    `java.lang.String` | `getMethodName()`
    `java.lang.Class<?>` | `getTestClass()`
    `int` | `hashCode()`
    `boolean` | `isEmpty()`
    `boolean` | `isSuite()`
    `boolean` | `isTest()`
    `int` | `testCount()`
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY

          public static final Description EMPTY

      Describes a Runner which runs no tests

    - #### TEST_MECHANISM

          public static final Description TEST_MECHANISM

      Describes a step in the test-running mechanism that goes so wrong no other description can be used (for example, an exception thrown from a Runner's constructor

  - ### Method Detail

    - #### createSuiteDescription

          public static Description createSuiteDescription(java.lang.String name,
                                           java.lang.annotation.Annotation... annotations)

      Create a `Description` named `name`. Generally, you will add children to this `Description`.
      Parameters:
        `name` - the name of the `Description`
        `annotations` - meta-data about the test, for downstream interpreters
      Returns:
        a `Description` named `name`

    - #### createSuiteDescription

          public static Description createSuiteDescription(java.lang.String name,
                                           java.io.Serializable uniqueId,
                                           java.lang.annotation.Annotation... annotations)

      Create a `Description` named `name`. Generally, you will add children to this `Description`.
      Parameters:
        `name` - the name of the `Description`
        `uniqueId` - an arbitrary object used to define uniqueness (in `equals(Object)`
        `annotations` - meta-data about the test, for downstream interpreters
      Returns:
        a `Description` named `name`

    - #### createTestDescription

          public static Description createTestDescription(java.lang.String className,
                                          java.lang.String name,
                                          java.lang.annotation.Annotation... annotations)

      Create a `Description` of a single test named `name` in the 'class' named `className`. Generally, this will be a leaf `Description`. This method is a better choice than `createTestDescription(Class, String, Annotation...)` for test runners whose test cases are not defined in an actual Java `Class`.
      Parameters:
        `className` - the class name of the test
        `name` - the name of the test (a method name for test annotated with `Test`)
        `annotations` - meta-data about the test, for downstream interpreters
      Returns:
        a `Description` named `name`

    - #### createTestDescription

          public static Description createTestDescription(java.lang.Class<?> clazz,
                                          java.lang.String name,
                                          java.lang.annotation.Annotation... annotations)

      Create a `Description` of a single test named `name` in the class `clazz`. Generally, this will be a leaf `Description`.
      Parameters:
        `clazz` - the class of the test
        `name` - the name of the test (a method name for test annotated with `Test`)
        `annotations` - meta-data about the test, for downstream interpreters
      Returns:
        a `Description` named `name`

    - #### createTestDescription

          public static Description createTestDescription(java.lang.Class<?> clazz,
                                          java.lang.String name)

      Create a `Description` of a single test named `name` in the class `clazz`. Generally, this will be a leaf `Description`. (This remains for binary compatibility with clients of JUnit 4.3)
      Parameters:
        `clazz` - the class of the test
        `name` - the name of the test (a method name for test annotated with `Test`)
      Returns:
        a `Description` named `name`

    - #### createTestDescription

          public static Description createTestDescription(java.lang.String className,
                                          java.lang.String name,
                                          java.io.Serializable uniqueId)

      Create a `Description` of a single test named `name` in the class `clazz`. Generally, this will be a leaf `Description`.
      Parameters:
        `name` - the name of the test (a method name for test annotated with `Test`)
      Returns:
        a `Description` named `name`

    - #### createSuiteDescription

          public static Description createSuiteDescription(java.lang.Class<?> testClass)

      Create a `Description` named after `testClass`
      Parameters:
        `testClass` - A `Class` containing tests
      Returns:
        a `Description` of `testClass`

    - #### getDisplayName

          public java.lang.String getDisplayName()

      Returns:
        a user-understandable label

    - #### addChild

          public void addChild(Description description)

      Add `Description` as a child of the receiver.
      Parameters:
        `description` - the soon-to-be child.

    - #### getChildren

          public java.util.ArrayList<Description> getChildren()

      Gets the copy of the children of this `Description`. Returns an empty list if there are no children.

    - #### isSuite

          public boolean isSuite()

      Returns:
        `true` if the receiver is a suite

    - #### isTest

          public boolean isTest()

      Returns:
        `true` if the receiver is an atomic test

    - #### testCount

          public int testCount()

      Returns:
        the total number of atomic tests in the receiver

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object obj)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### isEmpty

          public boolean isEmpty()

      Returns:
        true if this is a description of a Runner that runs no tests

    - #### childlessCopy

          public Description childlessCopy()

      Returns:
        a copy of this description, with no children (on the assumption that some of the children will be added back)

    - #### getAnnotation

          public <T extends java.lang.annotation.Annotation> T getAnnotation(java.lang.Class<T> annotationType)

      Returns:
        the annotation of type annotationType that is attached to this description node, or null if none exists

    - #### getAnnotations

          public java.util.Collection<java.lang.annotation.Annotation> getAnnotations()

      Returns:
        all of the annotations attached to this description node

    - #### getTestClass

          public java.lang.Class<?> getTestClass()

      Returns:
        If this describes a method invocation, the class of the test instance.

    - #### getClassName

          public java.lang.String getClassName()

      Returns:
        If this describes a method invocation, the name of the class of the test instance

    - #### getMethodName

          public java.lang.String getMethodName()

      Returns:
        If this describes a method invocation, the name of the method (or null if not)