Test data provider

We enriched the Neodymium library to have an easy way to structure and manage test data in various ways.

We support the following file formats:

• CSV
• XML
• JSON
• Properties

NOTE: This is also the order in which data set files and package test data files are searched

Test data is a key-value storage that is defined beside your test classes. There are two different types of data files, data sets and package test data. Combined together they build test data which will be stored in a map that you can access later. In general all package data will be added to the map and then later on data from data sets. It is on purpose that you can overwrite values from package test data with values from data sets. This allows you define general data in package test data and test specific data in the data sets. So you can augment your data sets while having the possibility to override it at the same time.

• Data sets: Contains multiple sets of data for a particular test class. A data set file must have the same name as the test class it is providing data for. For example: A data set file for a class named foo.java could be for example foo.csv or foo.json
• Package test data: Provides data for all test classes that are in the same package and inherits to classes all sub packages. Package test data is defined in a file named package_testdata which must contain data in one of the supported file formats and so it needs an proper file ending e.g.: package_testdata.properties

NOTE: In general both types of data files need to be at the same place (package) as the class is else they can't be found.

Data sets

Data sets are special as each defined set of data automatically causes a separate run of all tests of the class it is defined for. So for example: If you execute a test case and have a data set file with three data sets, it will be automatically executed for each and every defined data set unless told otherwise. You can control that behaviour with annoations: @DataSet and @SuppressDataSets

• We support data set in the following file formats: CSV, XLM and JSON. Please find an example for each format below.

• @SuppressDataSets: Can be annotated to a method and/or class. On a class it prevents all methods from beeing executed multiple times for data sets. On a method it is the same behaviour but just for that method and it will override any DataSet annotation from class or method.

• @DataSet: Can be anntotated to a method and/or class. This annotation can be used to limit a method to certain data sets regardless if there is an SuppressDataSets annotation on the class. If the class has an SuppressDataSets annotation the DataSet annotation can be used on a method to reenable execution for all or individual data sets. DataSet annotation can be parameterized to reference a specific data set. One could refer them by using an integer (value) or by using a string (id)

  • value: @DataSet(2) an integer referencing a specific data set (first data set would be referenced by 1)
  • id: @DataSet(id = "Jebediah's data set") an string value that refers to an data set which has the same value for attribute testId (see Example 1). This allows you to name your data sets which will come handy at some point.

Example 1

MyTest.csv

firstname, testId
Jane, Jane's data set
Jebediah, Jebediah's data set
Jill, Jill's data set

NOTE: Our CSV implementation treats the first line as variable name definition

@RunWith(NeodymiumRunner.class)
public class MyTest 
{
    @Test // by default all methods will be executed with all data sets that are defined
    public void allDataSets()
    {
        // you can access the current value by using DataUtils
        String firstname = DataUtils.asString("firstname");
    }
}

On execution of the code above Eclipse' JUnit view will display the following output

Example 2

NOTE: use same csv file as above

@RunWith(NeodymiumRunner.class)
@SuppressDataSets // disables data set support for the whole class
public class MyTest
{
    @Test
    public void noDataSets()
    {
    	// this method will run only once and without any data set because of the SuppressDataSets annotation on the class
    }
    
    @Test
    @DataSet(3) // overrides the class level @SuppressDataSets to run with the third data set
    public void onlyThirdDataSet()
    {
    	// this method will run only with third data set
    }
    
    @Test
    @DataSet // overrides the class level @SuppressDataSets to run with all data sets
    public void allDataSets()
    {
    	// this method will run with all three data sets
    }
}

Example 3

Please checkout our example project to find more hands on examples e.g. RegisterTest.java

Package test data

Package test data is almost the same as data sets except that it doesn't lead to multiple method execution. It is also a key value store that you can access from all the classes in a package and its sub packages. Package test data are defined in a file named e.g. package_testdata.csv (ending depends on choosen content format). One of the goodies of package test data is that the containing data will be inherited. For example: you define package test data in package com.mycompany and you can also use them from classes in sub packages like com.mycompany.tests and you can override these values by redefine a new value in a sub package test data file.

How to use test data

Test data and data sets are automatically processed on test execution. The NeodymiumRunner looks for package test data files and data set files. To access the data from you test case you can use DataUtils class or you can access the underlying hash map directly by using Context.get().data

There are a few convinience methods in DataUtils that might be handy as these methods offer auto type conversion from string

Method	Description
String asString(String key)	returns the value for stored key as string
int asInt(String key)	returns the value for stored key as integer
long asLong(String key)	returns the value for stored key as long
double asDouble(String key)	returns the value for stored key as double
float asFloat(String key)	returns the value for stored key as float
boolean asBool(String key)	returns the value for stored key as boolean
T get(Class<T> clazz)	creates an instance of the given class and tries to set value of member by searching test data for fields with the same name
randomEmail()	creates an random email address based on the values from configuration
randomPassword()	creates an random password based on the values from configuration

How to format test data

The test data files should follow a specific key value pattern. We show case the format for each type below.

CSV

The first line of the *.csv file defines the names for the available data fields each of the following lines defines a data set. If you are writing the files by hand please pay attention that you do not add any unneeded spaces. They will lead to errors since the are added without trimming into the names or values of the data set.

name1,name2,name3
value1-set1,value2-set1,value3-set1
value1-set2,value2-set2,value3-set2

XML

Our XML format has a datafile root element. This can hold as dataset element which results in a execution of the test method using the data elements as available parameters for that execution.

<?xml version="1.0" encoding="UTF-8"?>
<datafile>
	<dataset>
		<data key="name1">value1-set1</data>
		<data key="name2">value2-set1</data>
		<data key="name3">value3-set1</data>
	</dataset>
	<dataset>
		<data key="name1">value1-set2</data>
		<data key="name2">value2-set2</data>
		<data key="name3">value3-set2</data>
	</dataset>
</datafile>

JSON

Our JSON format represents an array of objects. Each JSON object results in a execution of the test method using the data it holds.

[
{"name1":"value1-set1", "name2":"value2-set1", "name3":"value3-set1"},
{"name1":"value1-set2", "name2":"value2-set2", "name3":"value3-set2"}
]

Test specific data sets

Test specific test data files need to have the same name as the test file and they need to be place either in the same directory as the test file or on the same path within the resource directory. The file format can be one of the above. With test specific data sets your are able to multiply the test execution. Every test method within the JUnit test will be executed once for each data set. Using this feature you can reach a higher test coverage by reusing the same code with different test data.

Test specific data overwrites the fields from package test data.

Package test data

You can add test data on package levels in order to structure and manage you test data that should be shared between tests. Package test data only just take the first data set into account. All other data sets are ignored.

In order to use package test data you need to add a file with the name package_testdata and the file ending of one of the supported types.