Unit tests - Raul6469/java-quickstart GitHub Wiki

You may have noticed Java files that are not part of your application, in the src/test/java folder. This folder holds unit tests for your application.

This is completely OPTIONAL, but it might be of some interest as it's usually a mark of good software quality. If you don't want to make unit tests, you can delete the whole src/test folder

What are unit tests?

Unit tests are pieces of code that will execute code from your main application, and check that it behaves as expected.

Let's say you are working on a calculator, and you have a sum method that return the sum of two integer parameters :

public static int sum(int a, int b) {
    return a + b;
}

As your project grows, you will add more and more features, but you don't wont to break the existing ones! And if you're working in a team, this can be even more challenging, as people might not be aware about breaking a feature developed by a team mate.

So once you're done writing your feature, you can write a unit test that will check that sum will always return the sum of the two parameters. It consists of a method that will call the sum function and check on an example that it's returning you the expected result.

@Test
public void goodSumResult() {
    assertEquals(5, Calculator.sum(2, 3));
}

goodSumResult is a classic Java method as you are used to write. The @Test above it is an "annotation" that marks tells the compiler this method is a test.

assertEquals is a function that checks the equality between two parameters. The first one is what you know you expect, and the second one is what your application code actually returns. If both parameters are equals, your test is good! Otherwise, it will be marked as failed.

Let's see your test in action! Run in a terminal in the project root folder the following command:

./gradlew test

Gradle will build your app and execute all tests marked with the @Test annotation, and you should see the following output:

Your test passed!

Now let's imagine someone broke your sum method, making it return only the first parameter:

public static int sum(int a, int b) {
    return a;
}

Run the tests again with ./gradlew test, and you should see this output:

Unit tests caught the bug! When there are failing tests, you can display more information about what went wrong by opening the HTML report file in your browser (the path to this file is written later in the test output in your terminal)

Take a closer look at the first line:

java.lang.AssertionError: expected:<5> but was:<2>

It tells you that the expected result was 5 because 2 + 3, but your code return 2 instead!

You can alternatively see these error messages directly in your terminal by running the tests again with this command: ./gradlew test --info

Relation with GitHub Actions

GitHub Actions is a feature that automates tasks execution in a virtual environement for your project. This project template already provides a setup that will make GitHub execute your unit tests against every change, so you don't have to think to execute ./gradlew test by hand. You will see green or red icons next in your commit history on GitHub telling you if there's an issue with your code.

Benefits

Obviously, this is a very simple example and you might not see interest for this case. But unit tests really shine once you get more complex methods handling different cases with if statements. Once you write a set of tests with your feature, you can always be sure that your code is behaving correctly (at least on your test cases).

This is a very common practice in software companies, as applications are complex and developed by multiple teams.

Withdraws

This can be tedious and slow down your work, if you want to write test cases in addition to your feature. You should take your deadlines into account when deciding to write tests or not. If your are working on a small project that needs to be done quickly by a few people, then writing unit tests is not a good fit for you. The general philosophy for writing unit tests is to slow down new work a bit in order to ensure it's stability over time.

If you don't want to write tests and clean up unnecessary files from the project, you can delete the whole src/test folder.