Getting Started¶

Getting Started will guide you through the process of testing your classes with approval testing. Don’t worry if you are used to normal testing with assertions you will get up to speed in minutes.

Setting Up Maven¶

Just add the approval library as a dependency:

<dependencies>
    <dependency>
        <groupId>com.github.nikolavp</groupId>
        <artifactId>approval</artifactId>
        <version>1.0-SNAPSHOT</version>
    </dependency>
</dependencies>

Note

Currently there are no stable version but we plan to release our first release soon, stay tuned :)

How is approval testing different¶

There are many sources from which you can learn about approval testing(just google it) but basically the process is the following:

you already have a working implementation of the thing you want to test
you run it and get the result the first time
the result will be shown to you in your preferred tool(this can be configured)
you either approve the result in which case it is recored(saved) and the test pass or you disapprove it in which case the test fails
the recorded result is then used on further test runs to make sure that there are no regressions in your code(i.e. you broke something and the result is not the same).
Of course sometimes you want to change the way something behaves so if the result is not the same we will prompt you with difference between the new result and the last recorded again in your preferred tool.

Approvals utility¶

This is the main starting point of the library. If you want to just approve a primitive object or arrays of primitive object then start here. The following will start the approval process for a String that MyCoolThing (our class under test) generated and use src/test/resources/approval/string.verified for recording/saving the results:

@Test
public void myApprovals() {
    String string = MyCoolThing.getComplexMultilineString();
    Approvals.verify(string, Paths.get('src/resources/approval/string.verified');
}

Approval class¶

This is the main object for starting the approval process. Basically it is used like this:

@Test
public void myApprovals() {
    String string = MyCoolThing.getComplexMultilineString();
    Approval<String> approver = Approval.of(String.class)
            .withReporter(Reporters.console())
            .build();
    approver.verify(string, Paths.get('src/resources/approval/string.verified');
}

note how this is different from Approvals utility - we are building a custom Approval object which allows us to control and change the whole approval process. Look at Reporter class and Converter for more info.

Note

Approval object are thread safe so you are allowed to declare them as static variables and reuse them in all your tests. In the example above if we have more testing methods we can only declare the Approval object once as a static variable in the Test class

Reporter class¶

Reporters(in lack of better name) are used to prompt the user for approving the result that was given to the Approval object. There is a withReporter method on ApprovalBuilder that allows you to use a custom reporter. We provide some ready to use reporters in the Reporters class:

console - this uses cat and diff to report the first result or the differences on the console
gvim - this uses gvim and gvimdiff to report the first result or the differences in gvim(our favourite editor)
gedit - this uses gedit to report the first result. Sadly on differences it just opens two tabs :(

Converter¶

Converters are objects that are responsible for serializing objects to raw form(currently byte[]). This interface allows you to create a custom converter for your custom objects and reuse the approval process in the library. We have converters for all primitive types, String and their array variants. Of course providing a converter for your custom object is dead easy. Let’s say you have a custom entity model class that you are going to use for verifications in your tests:

package com.nikolavp.approval;

/*
 * #%L
 * approval
 * %%
 * Copyright (C) 2014 Nikolavp
 * %%
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * #L%
 */

public class Entity {

    private String name;
    private int age;

    public Entity(String name, int age) {
        this.age = age;
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }

}

Here is a possible simple converter for the class:

package com.nikolavp.approval;

/*
 * #%L
 * approval
 * %%
 * Copyright (C) 2014 Nikolavp
 * %%
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * #L%
 */

import com.nikolavp.approval.converters.Converter;

import javax.annotation.Nonnull;
import java.nio.charset.StandardCharsets;

public class EntityConverter implements Converter<Entity> {
    @Nonnull
    @Override
    public byte[] getRawForm(Entity value) {
        return ("Entity is:\n" +
                "age = " + value.getAge() + "\n" +
                "name = " + value.getName() + "\n").getBytes(StandardCharsets.UTF_8);
    }
}

now let’s say we execute a simple test

    @Test
    public void customEntityTest() {
        Entity entity = new Entity("Nikola", 30);
        Approval<Entity> approver = Approval.of(Entity.class)
                .withReporter(Reporters.console())
                .withConveter(new EntityConverter())
                .build();
        approver.verify(entity, Paths.get("src/test/resources/approval/example/entity.verified"));
    }

we will get the following output in the console(because we are using the console reporter)

Entity is:

age = 30

name = Nikola

Path Mapper¶

Path mapper are used to abstract the way in which the final path file that contains the verification result is built. You are not required to use them but if you want to add structure to the your approval files you will at some point find the need for them. Let’s see an example:

You have the following class containing two verifications:

now if you want to add another approval test you will need to write the same destination directory for the approval path again. You can of course write a private static method that does the mapping for you but we can do better with PathMappers:

we abstracted the common parent directory with the help of the ParentPathMapper class. We provide other path mapper as part of the library that you can use:

JunitPathMapper

Limitations¶

Some things that you have to keep in mind when using the library:

unordered objects like HashSet, HashMap cannot be determisticly verified because their representation will vary from run to run.