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[][], a List<List<Object>>, or a String []. 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.

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.
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.

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. Default is ",". Optional.

Returns:

the regex to split String data

See Also:

String.split(String)

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.

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

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

Returns:

the format pattern to generate test method description

Default:

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