How to write your first Java unit test
Unit testing is really important for code quality (and for making your life easier when hunting for bugs), but if you’ve never done it before, where do you begin? Hopefully, this tutorial will help.
Let’s Begin
Let’s use a web-based Java TicTacToe game to demonstrate how to write your first unit test. First, here’s the code that checks to see if anyone has won the game.
public Player whoHasWon() {
ArrayList<Coordinate[]> winningPositions = new ArrayList<>();
// rows
winningPositions.add(new Coordinate[] {new Coordinate(0,0), new Coordinate(1,0), new Coordinate(2,0)});
winningPositions.add(new Coordinate[] {new Coordinate(0,1), new Coordinate(1,1), new Coordinate(2,1)});
winningPositions.add(new Coordinate[] {new Coordinate(0,2), new Coordinate(1,2), new Coordinate(2,2)});
// columns
winningPositions.add(new Coordinate[] {new Coordinate(0,0), new Coordinate(0,1), new Coordinate(0,2)});
winningPositions.add(new Coordinate[] {new Coordinate(1,0), new Coordinate(1,1), new Coordinate(1,2)});
winningPositions.add(new Coordinate[] {new Coordinate(2,0), new Coordinate(2,1), new Coordinate(2,2)});
// diagonals
winningPositions.add(new Coordinate[] {new Coordinate(0,0), new Coordinate(1,1), new Coordinate(2,2)});
winningPositions.add(new Coordinate[] {new Coordinate(2,0), new Coordinate(1,1), new Coordinate(0,2)});
for (Coordinate[] winningPosition : winningPositions) {
if (getCell(winningPosition[0]) == getCell(winningPosition[1])
&& getCell(winningPosition[1]) == getCell(winningPosition[2])) {
if (getCell(winningPosition[0]) != null) {
return getCell(winningPosition[0]);
}
}
}
return null;
}Next, we should write some unit tests to ensure the behavior is correct and doesn’t break in the future. So where do you start?
We will need to introduce a test framework into the project. For this example, we will use JUnit. To do this in Maven, simply add the following to your dependencies in the pom.xml
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.8.2</version>
<scope>test</scope>
</dependency>Next, it’s time to create a class for the unit tests to exist in. We want the tests to be in the same package as the class that we are testing. In our example, this is package com.diffblue.javademo.tictactoe;
Which means that the file should be in com/diffblue/javademo/tictactoe.
For a Maven project, this needs to be prefixed with src/test/java
Therefore, the path from the project root is src/test/java/com/diffblue/javademo/tictactoe.
This means that all the test classes are separated nicely from the main source code.
Finally, the class should follow the format <class under test>Test which, for this example, means the class will be BoardTest and the file obviously BoardTest.java
Note: when running tests with Maven, the default is to search for classes that are suffixed with Test.
With all that in mind, create a class:
package com.diffblue.javademo.tictactoe;
public class BoardTest {
}For this example, let’s create a test to check that detecting a player winning through the top row works correctly.
Create a method for this test:
package com.diffblue.javademo.tictactoe;
import org.junit.Test;
public class BoardTest {
@Test
public void playerOTopRow() {
// Arrange
// Act
// Assert
}
}This is slightly different from the methods that you have written in your source code. Working through the method: First there is an annotation to say that this is a test:
@TestAlso, note the relevant import. This will tell the tools that this method is a test. If you are using IntelliJ or Eclipse, you will see that you can now run this method as a test.
This is a good time to point out that unit tests are designed to protect against future mistakes. This means that your test needs to be easy to read and understand both by other developers and your future self. To split up tests to aid in readability, let’s add three comments: arrange, act and assert.
Now to start building out the test!
We need to set up an environment where the top row of the board is Naughts:
package com.diffblue.javademo.tictactoe;
import org.junit.Test;
public class BoardTest {
@Test
public void playerOTopRow() {
// Arrange
Board myBoard = new Board();
myBoard.setCell(new Coordinate(0,0), Player.NOUGHT);
myBoard.setCell(new Coordinate(0,1), Player.CROSS);
myBoard.setCell(new Coordinate(1,0), Player.NOUGHT);
myBoard.setCell(new Coordinate(1,1), Player.CROSS);
myBoard.setCell(new Coordinate(2,0), Player.NOUGHT);
// Act
// Assert
}
}Now we have a board that has Naughts winning through the top row. Next, call the method whoHasWon() and collect the result.
package com.diffblue.javademo.tictactoe;
import org.junit.Test;
public class BoardTest {
@Test
public void playerOTopRow() {
// Arrange
Board myBoard = new Board();
myBoard.setCell(new Coordinate(0,0), Player.NOUGHT);
myBoard.setCell(new Coordinate(0,1), Player.CROSS);
myBoard.setCell(new Coordinate(1,0), Player.NOUGHT);
myBoard.setCell(new Coordinate(1,1), Player.CROSS);
myBoard.setCell(new Coordinate(2,0), Player.NOUGHT);
// Act
Player result = myBoard.whoHasWon();
// Assert
}
}Now we have a test that sets up the environment and calls the method under test.
There is one final step to complete the test: add an Assert. The assert is the key part to the test, it is the thing that is checked to say whether the test has passed or failed. Here, we are checking that result is naught.
Here is our complete test:
package com.diffblue.javademo.tictactoe;
import org.junit.Test;
import static org.junit.Assert.assertEquals;
public class BoardTest {
@Test
public void playerOTopRow() {
// Arrange
Board myBoard = new Board();
myBoard.setCell(new Coordinate(0,0), Player.NOUGHT);
myBoard.setCell(new Coordinate(0,1), Player.CROSS);
myBoard.setCell(new Coordinate(1,0), Player.NOUGHT);
myBoard.setCell(new Coordinate(1,1), Player.CROSS);
myBoard.setCell(new Coordinate(2,0), Player.NOUGHT);
// Act
Player result = myBoard.whoHasWon();
// Assert
assertEquals("Player O didn't win in the top row", Player.NOUGHT, result);
}
}Looking at the assert, note the message (first argument to the assert). When a test fails, this message is printed in the results. This can give a clear indication of what has gone wrong to the person debugging the tests.
Another note: the order of the arguments is expected result first, and then the actual result. Because tools will include the expected and the actual results in the output, it is important to avoid confusion by getting these the correct way round.
Having finished the test, we can now run all the tests using mvn test and we will see that our test passes:
[INFO] ------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.diffblue.javademo.tictactoe.BoardTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.018 s - in com.diffblue.javademo.tictactoe.BoardTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]Congrats! With that, you’ve written your first test. The full source code for this tutorial is available here.
