com.tngtech.java.junit.dataprovider

Annotation Type DataProvider

@Documented
 @Retention(value=RUNTIME)
 @Target(value=METHOD)
public @interface DataProvider

Mark a method as a dataprovider used by a test method or use it directly at the test method and provide data via value() attribute.

• Use it on a separate method: The name of the dataprovider is the the name of the method. The method must be static and return an Object[][], an Iterable<Iterable<?>>, an Iterable<?>, or a String[]. Whereby Iterable can be replaced with any vaild subtype as well as arbitrary inner types are also supported. The test method will be called with each "row" of this two-dimensional array. The test method must be annotated with @UseDataProvider. This annotation behaves pretty much the same as the @DataProvider annotation from TestNG.

  Note: The name of the test method in the JUnit result will by default be the name of the test method (annotated by @UseDataProvider) suffixed by the parameters, can be changed by customizing format().

• Use it directly on test method: Provide all the data for the test method parameters as regex-separated Strings using String[] value().

  Note: All parameters of the test method must be primitive types (e.g. char, int, double), primitive wrapper types (e.g. Boolean, Long), case-sensitive Enum names, Strings, or types having single-argument String constructor. The former two are converted using the valueOf(String) methods of their corresponding wrapper classes or valueOf(Class<? extends Enum<?>>, String), respectively. This can cause Exceptions at runtime. A String must not contain commas! The String "null" will be passed as null or String, according to convertNulls().

If the test method arguments are retrieved from a regex-separated String[], the additional annotation parameters can be used to customized the generation/conversion behavior.

Field Summary

Fields

Modifier and Type	Fields and Description
static java.lang.String	COMMA Comma delimiter to split up parameters for dataproviders using the value()s String representation.
static java.lang.String	DEFAULT_FORMAT Default format string containing test method name followed by an index and all parameters within square brackets.
static java.lang.String	NULL null-String value to be converted to null if convertNulls() is true.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	convertNulls Determines if every "null"-String in value() or returned by the method annotated with @DataProvider should be converted to null (= true ) or used as String (= false).
java.lang.String	format Format pattern to be used to generate test method description.
boolean	ignoreEnumCase
java.lang.String	splitBy The delimiting regular expression by which the regex-separated Strings given by value() or returned by the method annotated with @DataProvider are split.
boolean	trimValues true if leading and trailing whitespace should be omitted in split Strings given by value() or returned by the method annotated with @DataProvider, false otherwise.
java.lang.String[]	value Define a list of parameters each as a regex-separated String for the annotated test method.

Field Detail

COMMA

public static final java.lang.String COMMA

Comma delimiter to split up parameters for dataproviders using the value()s String representation.

See Also:

splitBy()

NULL

public static final java.lang.String NULL

null-String value to be converted to null if convertNulls() is true.

See Also:

convertNulls()

DEFAULT_FORMAT

public static final java.lang.String DEFAULT_FORMAT

Default format string containing test method name followed by an index and all parameters within square brackets.

See Also:

format()

Element Detail

value

public abstract java.lang.String[] value

Define a list of parameters each as a regex-separated String for the annotated test method. Optional.

Returns:

list of regex-separated String parameters

Default:

{}

splitBy

public abstract java.lang.String splitBy

The delimiting regular expression by which the regex-separated Strings given by value() or returned by the method annotated with @DataProvider are split. Defaults to ",". Optional.

Returns:

the regex to split String data

See Also:

String.split(String), COMMA

Default:

","

convertNulls

public abstract boolean convertNulls

Determines if every "null"-String in value() or returned by the method annotated with @DataProvider should be converted to null (= true ) or used as String (= false). Default is true. Optional.

Returns:

true iif "null"-Strings should be converted to null.

See Also:

NULL

Default:

true

trimValues

public abstract boolean trimValues

true if leading and trailing whitespace should be omitted in split Strings given by value() or returned by the method annotated with @DataProvider, false otherwise. Default is true. Optional.

Returns:

true iif regex-separated String data should be trimmed

See Also:

String.trim()

Default:

true

format

public abstract java.lang.String format

Format pattern to be used to generate test method description. The following placeholders are by default available (for more information see their implementations in package com.tngtech.java.junit.dataprovider.internal.placeholder:

Placeholder	Aliases	Example	Description
%c	DataProviderRunnerTest	Simple name of test method class (= Class.getSimpleName())
%cc	com.tngtech.java .junit.dataprovider .DataProviderRunnerTest	Canonical name of test method class (= Class.getCanonicalName())
%m	testIsEmptyString	Simple name of test method (= Method.getName())
%cm	com.tngtech.test .java.junit.dataprovider .DataProviderJavaAcceptanceTest .testIsEmptyString(java.lang.String)	Complete signature of test method (= Method.toString())
%i	13	Index of the dataprovider test of current test method (starting at 0). Useful to generate unique test method descriptions.
%p[x]	test, <null>, 4	Subscripting all parameters by positive or negative index (1.) and range (2.). All indices may either be positive (starting at 0 and increment) to number parameters from the beginning or negative (starting from -1 and decrement) to number parameters from the end: A positive or negative index {code x} to get the String representation of a specific parameter, e.g. %p[3] (= third parameter) or %p[-2] (= second last parameter). A range index producing the comma-separated String representation of corresponding parameters, e.g. %p[0..1] for the first two parameters, %p[0..-2] for all parameters expect the last, or %p[-3..-1] for the last two parameters. Attention: This placeholder will cause an IndexOutOfBoundsException iif any index exceeds the parameters array length

Hints:

• A produced test method name should be unique among all other in the same class.
• Every above listed parameter can be used multiple times

Defaults to "%m[%i: %p[0..-1]]". Optional.

Returns:

the format pattern to generate test method description

See Also:

DEFAULT_FORMAT

Default:

"%m[%i: %p[0..-1]]"

ignoreEnumCase

public abstract boolean ignoreEnumCase

Returns:

true if and only if the case for Enum conversion should be ignored such that searching for the corresponding Enum values is case-insensitive. Default is false. Optional.

Default:

false