Introduction to AssertJ-DB

This is a free sample lesson of my Introduction to AssertJ-DB course. If you like this sample lesson, you should take a look at the course. It has 6 lessons, 17 exercises, and 2 quizzes. The price of the course is 12,5€ + VAT.

After you have finished this lesson, you:

• Know what AssertJ-DB is.
• Understand why you should use AssertJ-DB.
• Can get the required dependencies with Maven and Gradle.
• Understand how you can configure AssertJ-DB.

Let's begin.

What Is AssertJ-DB and Why Should You Use It?

AssertJ-DB is an AssertJ module which allows you to write assertions for the data that's found from a relational database. You should consider using AssertJ-DB because:

First, you don't have to use external data set files. Instead, you can write your assertions by using Java programming language. This solves two problems:

• It's quite common that you have to write multiple different assertions for the data that's found from the same database table. If you write these assertions by using external data set files, these data set files contain duplicate configuration (table and column names) and duplicate test data. That's why tests which use external data set files are hard to maintain. It's true that you can make this problem a bit less painful by splitting large data set files into smaller files, but you cannot totally eliminate this problem. On the other hand, if you write your assertions with AssertJ-DB, you can eliminate duplicate code by using the techniques described on this course.
• If you write your assertions by using external data set files, the only way to read them is to open the data set file. This makes your tests hard to read. On the other hand, if you write your assertions with AssertJ-DB, you can read them without leaving your test class. This makes your tests more pleasant to read.

Second, if you have to write assertions for multiple column values and one of your assertion fails, you might not have all the information you need because it’s possible that some of your assertions weren’t run. You can solve this problem and shorten your feedback loop by writing soft assertions. When you run a test method which has multiple soft assertions, AssertJ-DB runs all assertions, collects possible assertion failures, and reports all assertion failures after all assertions have been run. In other words, if you use soft assertions, you have to run your test only once.

Third, you can remove duplicate code and emphasize business rules by writing custom assertions. Even though AssertJ-DB has a clean API, the fact is that when you want to write an assertion for a column value, you have to specify the name of the database table, the name of the column, the index of the table row, and the expected value. This becomes repetitive quite fast and you end up with a lot of duplicate code. Luckily, you can get rid of duplicate code by putting it to one place.

Also, there are situations when you have to write assertions which enforce a business rule. For example, if you are writing tests for code which creates new payments, you have to make sure that your code creates a pending transaction. AssertJ-DB helps you to replace the traditional data-centric assertions with custom assertions which ensure that your tests are easy to read, write, and maintain.

Fourth, you can customize the error message shown if an assertion fails. Generally speaking, AssertJ-DB has very good error messages, but there are situations when you should override the default error message.

In other words, I think that AssertJ-DB helps you to write tests which are easy to read, write, and maintain. Next, you will learn how you can get the required dependencies with Maven and Gradle.

Getting the Required Dependencies

Before you can write assertions with AssertJ-DB, you have to ensure that the assertj-db dependency (version 2.0.2) is found from the classpath.

If you are using Maven, you have to add the assertj-db dependency to the test scope. You can do this by adding the following dependency to the dependencies section of your POM file:

<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-db</artifactId>
    <version>2.0.2</version>
    <scope>test</scope>
</dependency>

If you are using Gradle, you have to add the assertj-db dependency to the testImplementation dependency configuration. You can do this by adding the following snippet to your build.gradle file:

dependencies {
    testImplementation(
            'org.assertj:assertj-db:2.0.2'
    )
}

After you have added this dependency to the classpath, you can start using AssertJ-DB. Let's move on and find out how you can configure AssertJ-DB.

Configuring AssertJ-DB

You can configure AssertJ-DB by creating a new org.assertj.db.type.Table object. This object allows you to write assertions for the data that's found from one database table. In other words, if you have to write assertions for the data that's found from different database tables, you have to create multiple Table objects (one object per database table).

When you create a new Table object, you have to provide (at least) two constructor arguments. These arguments:

1. Configure the database connection.
2. Specify the name of the database table.

When you configure the database connection, you can use one of these two options:

First, you can inject the javax.sql.DataSource object into your test class and pass this object as the first constructor argument. I think that you should use this approach if you can do it because it's easy and it ensures that the system under test and your assertions use the same database.

After you have created a new Table object which allows you to write assertions for the data found from the user_account database table, the source code of your test class could look as follows:

import org.assertj.db.type.Table;
import org.junit.jupiter.api.DisplayName;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;

import javax.sql.DataSource;

@SpringBootTest
@ActiveProfiles("integrationTest")
@DisplayName("Tests for the content of the user_account database table")
class UserAccountTableTest {

    private final Table userAccountTable;

    @Autowired
    UserAccountTableTest(DataSource dataSource) {
        this.userAccountTable = new Table(dataSource, "user_account");
    }
}

Second, if you have no other choice, you can also configure the database connection manually by creating a new org.assertj.db.type.Source object and pass this object as the first constructor argument. When you create a new Source object, you have to provide three constructor arguments:

1. The JDBC url.
2. The username of the database user.
3. The password of the database user.

After you have created a new Table object which allows you to write assertions for the data found from the user_account database table, the source code of your test class could look as follows:

import org.assertj.db.type.Source;
import org.assertj.db.type.Table;
import org.junit.jupiter.api.DisplayName;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;

@SpringBootTest
@ActiveProfiles("integrationTest")
@DisplayName("Tests for the content of the user_account database table")
class UserAccountTableTest {

    private final Table userAccountTable;

    UserAccountTableTest() {
        var dbConnection = new Source("jdbc:postgresql:assertj-db", 
                "username", 
                "password"
        );
        this.userAccountTable = new Table(dbConnection, "user_account");
    }
}

You can now configure AssertJ-DB. Let's summarize what you learned from this lesson.

This is a free sample lesson of my Introduction to AssertJ-DB course. If you liked this sample lesson, you should take a look at the course. It has 6 lessons, 17 exercises, and 2 quizzes. The price of the course is 12,5€ + VAT.

Summary

This lesson has taught you five things:

• AssertJ-DB is an AssertJ module which which allows you to write assertions for the data that's found from a relational database.
• Before you can write assertions with AssertJ-DB, you have to ensure that the assertj-db dependency is found from the classpath.
• AssertJ-DB helps you to solve the problems caused by external data set files and write assertions which are easy to read, write, and maintain.
• When you create a new Table object, you should inject a DataSource object into your test class and pass it as the first constructor argument (which configures the database connection).
• If you have no other choice, you can configure the database connection manually by creating a new Source object. When you create a new Table object, you have to pass the created Source object as the first constructor argument.

Get the sample code from Github