Annotation Interface Given

@Documented @Target({ANNOTATION_TYPE,FIELD,PARAMETER}) @Retention(RUNTIME) @Repeatable(Given.List.class) public @interface Given
Indicates that a field or parameter should be automatically generated with a random value during test execution.

This annotation can be applied to:

  • fields
  • @Test method parameters
  • @RepeatedTest method parameters
  • additional @ParameterizedTest method parameters
@ExtendWith(InstancioExtension.class)
class ExampleTest {

    @Given
    private List<Person> persons;

    @Test
    void example1(@Given int randomInt) {
        // Regular @Test method with generated parameters
    }

    @RepeatedTest(10)
    void example2(@Given String randomString) {
        // @RepeatedTest method with generated parameters
    }

    @ValueSource(strings = {"foo", "bar", "baz"})
    @ParameterizedTest
    void example3(String value, @Given LocalDate randomDate) {
        // Supplement @ParameterizedTest arguments with additional generated arguments
        // Augment @ParameterizedTest arguments with additional generated values
    }
}

Repeated declarations

This annotation is repeatable. Repeating it is equivalent to listing all the providers in a single declaration, so that: 

@Given(FooProvider.class)
@Given(BarProvider.class)
private String value;

has the same effect as: 

@Given( {FooProvider.class, BarProvider.class} )
private String value;

Note that repeating the annotation adds an alternative rather than an additional step: the providers form a single set of candidates, from which one is selected at random each time a value is generated. They are never applied together.

Candidates are gathered from every @Given that applies to an element, whether declared directly or contributed by a meta-annotation, so that composed annotations combine into one set.

Since:
5.0.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Given.List
    Container for repeated @Given declarations.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Class<? extends GivenProvider>[]
    value
    Specifies classes that will provide values for the annotated parameter or field.

  • Element Details

    • value

      @ExperimentalApi Class<? extends GivenProvider>[] value
      Specifies classes that will provide values for the annotated parameter or field.
      • If no class is specified, Instancio will generate random values for elements annotated with @Given.
      • If multiple classes are specified, a provider will be selected randomly from the specified classes.
      Returns:
      the classes responsible for providing values
      Since:
      5.0.0
      Default:
      {}