pbt-java8

I have become a big fan of property based testing (PBT) and the associated frameworks that are available. However Java 6 has very limited support for property based testing primarily because:

• It does not have lambdas - this makes combining generators and creating code blocks a little cumbersome,
• It does not have collection classes - so performing operations over lists is typically done using loops rather than using nifty functional constructs like map, fold (or reduce) and filter.

Over the past couple of months I have had a need to create PB tests on projects where the developers associated with the project are not comfortable to adopt a new language such as Scala for the purposes of testing. So I knocked together a library for Java 6 whilst performing the String Calculator Kata hoping to see what would pop out. Much to my surprise most of the effort went into creating the boilerplate code necessary to support PBT in Java 6 rather than the tests themselves. The Java 6 library became so useful I ported it to Java 8 - this is the result.

The Concept

The scope of a traditional unit test is centered around cherry picking data to validate a specific scenario. This works well to validate that the code under test is behaving as it is expected to. The issue with this style of testing is that you only test scenarios that you can think of. The philosophy behind PBT is to confirm that the invariant between a component's input and output data is valid for a set of input data.

An Example

The structure of a PBT is to describe the inputs to the test using one or more generators and then to validate that, given the input the results are as expected.

Using the String Calculator as a backdrop let's look at a number of scenarios.

Given an integer should return its value

	import za.co.no9.pbt.Generator;
	import za.co.no9.pbt.IntegerGenerator;
	import static za.co.no9.pbt.Gen.forAll;

    @Test
    public void given_an_integer_should_return_its_value() {
    	Generator<Integer> integers = IntegerGenerator.from(-2000, 2000);
    	
        forAll(integers, n ->
                assertEquals(n, add(n.toString())));
    }

Notes:

• This library is used within a normal jUnit test - there is no need to include any other framework or exotic parent classes.
• The variable integers is a generator that, when the method next is invoked on it, will return an Integer in the range -2000 and 2000.
• The forAll construct accepts one or more generators and a function. forAll then executes the function za.co.no9.pbt.Gen.ITERATIONS number of times by invoking this function with values that are supplied by call next on each of the generators. In code the forAll method is implemented as

    public static <T> void forAll(Generator<T> gen1, Consumer<T> consumer) {
        for (int i = 0; i < ITERATIONS; i += 1) {
            consumer.accept(gen1.next());
        }
    }

• All of Java's native data types have supported generators - BooleanGenerator, ByteGenerator, CharacterGenerator, DoubleGenerator, FloatGenerator, IntegerGenerator, LongGenerator and ShortGenerator.

Given a list of integers should return the sum

	import za.co.no9.pbt.Generator;
	import za.co.no9.pbt.IntegerGenerator;
	import static za.co.no9.pbt.Gen.forAll;

    @Test
    public void given_a_list_of_integers_should_return_its_value() {
    	Generator<List<Integer>> listOfIntegers = IntegerGenerator.from(-2000, 2000).nonEmptyList();
    	
        forAll(listOfIntegers, ns ->
                assertEquals(
                	ns.stream().reduce(0, (sum, n) -> sum + n), 
                	add(ns.stream().map(Object::toString).collect(Collectors.joining(",")))));
    }

Notes:

• Each generator has a set of methods that can be applied to return a generator collection. In the example above the variable listOfIntegers is a generator that is assembled by calling nonEmptyList on the integers collection from the previous example. In the same way it is possible to create a Set from a generator.
• A complete set of tests for the kata can be found in the kata test package.

Library Dependency

	<dependency>
		<groupId>za.co.no9</groupId>
		<artifactId>pbt-java8</artifactId>
		<version>1.0</version>
	</dependency>

Generators

A number of generators are included within this library are listed below. The code to support these generators is simple. I would encourage anyone wishing to use this library to take a look at this code - once you have seen this code you'll realise that creating a generator from scratch is dead easy.