--- title: "How To Use Assert In JUnit With Examples | CoderPad" description: "The JUnit Assert class is what you use to write unit testing assertions in JUnit. Learn more about it in this guide, full of examples." canonical: "https://coderpad.io/blog/development/how-to-use-assert-in-junit-with-examples/" last_modified: "2026-04-15 16:20:50" --- [Back to blog](https://coderpad.io/blog/) # How To Use Assert In JUnit With Examples March 27, 2023 7 Minute Read By Carlos Schults [Development](https://coderpad.io/blog/development/) Assertions are at the heart of [unit testing](https://coderpad.io/blog/development/integration-tests-vs-unit-tests-integration-matters-more/). They’re crucial in giving unit tests their “self-validating” characteristic, without which they’d be practically useless. In this post, you’ll learn more about the`Assert`JUnit class and how you can use it to write your assertions when unit testing your Java code. This will be a practical post, but we’ll start with a brief theoretical digression to explain what “assert” means in JUnit. Then, it’s time to roll up your sleeves. You’ll learn the following: - The process for installing JUnit 5 - How to create a sample project for testing - What the main assertion methods are and how they work Let’s get started. ## What is Assert in JUnit? In JUnit,`Assert`is a class that contains many assertion methods you can use when writing unit tests. To understand what that means, you must take a step back and learn about the structure of unit tests first. Though this is far from being a rule, a unit test typically contains three phases: - First, you prepare the values for your test. - Then, you execute the action you want to test. - Finally, you compare the results you got to what you expected to get. Unit test frameworks enable you to perform said comparisons by using assertions. An assertion is a type of special syntax you can use to express an expectation in your test code. If the expectation proves true, your test passes; otherwise, it fails. That’s why the structure above is known as the arrange-act-assert pattern. So, the JUnit`Assert`class is what allows you to write assertions in your JUnit tests. There are many assertions available; the main ones enable you to verify the following: - The equality of two values - Whether an object is`null` - The logical value of a boolean variable - Whether two variables point to the same object in memory Let’s see how to use assertions in practice. ## Installing JUnit 5 and creating a sample project Start by creating a new Java project and open it with the IDE or text editor you’re most comfortable with. The next step is to install JUnit 5 on your project. JUnit 5 is the latest major version of the framework, and it’s a complete rewrite. Rather than being a simple component, JUnit 5 is made up of several independent components. To be able to write tests, you need at least JUnit Platform and JUnit Jupiter. Since I’m using Maven, I’ll add the following to my`pom.xml`file: ``` org.junit.jupiter junit-jupiter-engine 5.2.0 test org.junit.platform junit-platform-runner 1.2.0 test Code language: HTML, XML (xml) ``` Now, go under`src/test/java`and create a new Java class. Call it`DemoTest`and paste the following code on it: ``` import org.junit.Test; import static org.junit.Assert.*; public class DemoTest { }Code language: Java (java) ``` ## The main JUnit Assert m ethods With your demo project in place, it’s time to start writing some assertions. ### assertEquals() `assertEquals()`is probably the most used assertion. With it, you can compare two values and see whether they’re equal. Here’s an example of`assertEquals()`that uses two overloads of the method, one for integers and the other for strings: ``` @Test public void assertEquals_demo() { // integers int expected = 4; int actual = 2 + 2; assertEquals(expected, actual); // strings assertEquals("JUnit5", "JUnit" + "5"); } Code language: Java (java) ``` Generally speaking, you should avoid more than one assertion per test method, but this is just an example here. Also, remember that argument order matters when using`assertEquals()`. The first argument represents the result you expect to get after the “act” phase of your test, and the second one is what you actually got. Those values are then used in the error message when the test fails, so mixing them up can throw off your test results Let’s see a test failure example. I’ll go back to the previous example, and in the line where I assign the expected variable, I’ll pass 5 to it instead of 4. When I run the test, I get this result: ``` java.lang.AssertionError:  Expected: 5 Actual: 4Code language: CSS (css) ``` #### A warning on reference types Before moving on, there’s something you need to be aware of when dealing with reference types. For that, consider a simple class: ``` public class Person {     private final String name;     private final int age;     public Person(String name, int age) {         this.name = name;         this.age = age;     } }Code language: Java (java) ``` Now, consider the following test: ``` p1 = new Person("John Doe", 32); var p2 = new Person("John Doe", 32); assertEquals(p1, p2);Code language: Java (java) ``` You might think that such a test would pass, but it fails: ``` java.lang.AssertionError:  Expected :Person@17d99928 Actual   :Person@3834d63f Code language: CSS (css) ``` That’s because classes are [reference types](https://www.javatpoint.com/reference-data-types-in-java). As such, when you use`assertEquals`, only the references of the objects are compared by default. Even though`p1`and`p2`have the same values, they refer to different objects in the heap memory, so they’re considered different. However, we really want to compare those two objects by their values, not their references. In other words, we want structural equality rather than referential equality. Achieving that is easy: you’d have to override the`equals()`method on the`Person`class. ``` @Override public boolean equals(Object obj) { if (obj == this) return true; if (!(obj instanceof Person)) { return false; } Person other = (Person) obj; return other.name.equals(this.name) && other.age == this.age; }Code language: Java (java) ``` #### A useful overload There are multiple versions (overloads) of the`assertEquals()`method that can be used with different data types such as`long`,`String`,`double`,`float`,`int`, etc. Each of these versions also has a variant that includes an additional`String`parameter called`message`. This variant can be used to specify a message to be displayed if the test fails. This can be useful when multiple tests fail simultaneously, as it allows for faster identification of the issue. By the way, all assertion methods have an overload like that. So it’d be redundant to provide an example for each. You’ll see an example of the`message`parameter being used soon. ### assertNotEquals() It’s common for assertion methods to have an inverse method.`assertNotEquals()`asserts that two objects are different. Like its counterpart, you should pay attention to the order of the parameters: - First comes the unexpected value - Then the actual value ### assertTrue() The`assertTrue()`method asserts that a given boolean value is true. As an example, let’s rewrite the previous assertion, replacing`assertEquals`with`assertTrue`: ``` assertTrue(p1.equals(p2));Code language: Java (java) ``` This is just an example. In real test code, it’s better to use`assertEquals`over`assertTrue`when comparing two values. That’s because`assertEquals`will give you a more useful error message when a failure occurs, following the pattern “expected: x; actual: y.” Use`assertTrue()`, for instance, to assert the return value of a method of type boolean. Here’s an example: ``` @Test public void assertTrue_demo() { int yearsOfEmployment = 5; String name = "John Doe"; Employee emp = new Employee(name, yearsOfEmployment); assertTrue(emp.isEligibleForSabbatical()); }Code language: Java (java) ``` This is the code for the`Employee`class: ``` public class Employee {     private final String name;     private final int yearsOfEmployment;     public Employee(String name, int yearsOfEmployment) {         this.name = name;         this.yearsOfEmployment = yearsOfEmployment;     }     public boolean isEligibleForSabbatical() {         return yearsOfEmployment >= 5;     } }Code language: Java (java) ``` `assertTrue()`has a useful overload in which you can provide a message when the test fails: ``` @Test public void assertTrue_demo() { int yearsOfEmployment = 5; String name = "John Doe"; Employee emp = new Employee(name, yearsOfEmployment); assertTrue( "Employees with 5 or more years of employment are eligible for a sabbatical", emp.isEligibleForSabbatical()); }Code language: Java (java) ``` I’ll go into the production method and add a bug: ``` return yearsOfEmployment >= 6;Code language: Java (java) ``` Now the test fails with a helpful message: ``` java.lang.AssertionError: Employees with 5 or more years of employment are eligible for a sabbatical at org.junit.Assert.fail(Assert.java:89) at org.junit.Assert.assertTrue(Assert.java:42) at DemoTest.assertTrue_demo(DemoTest.java:10) [...]Code language: CSS (css) ``` ### assertFalse() As its name suggests, the`assertFalse()`method is the opposite of`assertTrue()`– the test passes when its parameter evaluates to false. ### assertSame() When discussing`assertEquals()`, you’ve learned that reference types (objects) are compared regarding their references. That’s why`assertEquals()`fails for objects that don’t override the`equals()`method. What if you really wanted to verify reference equality? In this case, you’d use the`assertSame()`method: ``` var p1 = new Person("Jane Doe", 20); var p2 = p1; assertSame(p1, p2);Code language: Java (java) ``` ### assertNotSame() If you wanted to assert that two variables don’t point to the same object, you’d use the opposite method:`assertNotSame()`. ### assertNull() You use the`assertNull()`method to verify whether the specified parameter contains a`null`reference: ``` PhoneNumber candidate = PhoneNumber.tryParse("this isn't a phone number"); assertNull(candidate);Code language: Java (java) ``` ### assertNotNull() You should know the drill by now: this is the inverse of the previous one, and I won’t bore you with an example. Just a personal anecdote: I rarely use`assertNotNull()`when writing my tests. Most of the time, I find that there are more useful assertions I can write. For instance, I often have a specific value I want to compare the result of the operation to, in which case`assertEquals()`is the answer. ### assertThrows() When writing tests, not only must you test the scenario in which everything works fine—i.e. the happy path—but you should also test the sad path scenarios. Languages like Java use the concept of exceptions to express unintended behaviors and errors in methods. So you’ll often have to write tests that verify whether a given exception happens. Let’s go back to the`Person`class from previous examples and change its constructor, adding two [guard clauses](https://wiki.c2.com/?GuardClause): ``` public Person(String name, int age) { if (name == null || name.trim().isEmpty()) throw new IllegalArgumentException("Name shouldn't be empty!"); if (age < 0) throw new IllegalArgumentException("Age can't be negative!"); this.name = name; this.age = age; }Code language: Java (java) ``` You’ll agree with me that it’s reasonable to prohibit empty names and negative ages. But now it’d be great to have tests for these scenarios for two reasons: - Documentation: The tests will serve as a specification of the class’s behavior. - Code quality: The tests will prevent the guard clauses from being removed or changed. Let’s write a test for the negative age scenario: ``` @Test public void negativeAgesNotAllowed() { int age = -1; String name = "John Doe"; assertThrows(IllegalArgumentException.class, () -> new Person(name, age)); }Code language: Java (java) ``` As you can see, using`assertThrows`isn’t hard: you pass the expected exception class as the first argument and a lambda expression representing the action to be executed as the second one. As an exercise, try implementing tests for these scenarios for the`name`argument: - An empty string - A string with spaces - `null` How about you try out JUnit in the sandbox below? ## Assert y our way to better software In this post, you’ve learned what assertions are, why they’re crucial for unit testing, and how to write assertions using the JUnit`Assert`class. Where should you go next? My suggestion is for you to explore the`Assert`class in more depth. There are many assertions available. The ones we’ve explored barely scratch the surface, despite being some of the most important ones. The more you master the`Assert`class, the more expressive your unit tests will be. Thanks for reading! This post was written by Carlos Schults. [Carlos](https://carlosschults.net) is a consultant and software engineer with experience in desktop, web, and mobile development. Though his primary language is C#, he has experience with a number of languages and platforms. His main interests include automated testing, version control, and code quality. ## Subscribe for more CoderPad insights ## Trending Articles Previous slide Next slide [Development ## What is Prompt Engineering? Introducing AI tools such as ChatGPT and Bard helps increase the efficiency of tasks such as data generation, code generation and completion, text summarization, etc. How were these AI tools trained to answer almost every question you ask them? The answer, prompt engineering, is discussed in this blog post. Read the post](https://coderpad.io/blog/development/what-is-prompt-engineering/) [Development ## A Guide To Using React’s useCallback() Hook Are you looking to optimize your React applications? Have you heard of the useCallback hook? useCallback is a powerful React hook that helps you optimize your application by preventing unnecessary re-renders. In this post, we'll dive into React's useCallback() hook, define referential equality and callback functions and how to tie it all together. Read the post](https://coderpad.io/blog/development/a-guide-to-using-reacts-usecallback-hook/) [Development ## MySQL vs. PostgreSQL: How Do They Compare? A database is a convenient tool that allows users to access information, maintain records, and apply commonly used operations, such as insertion, modification, deletion, and data organization. Learn about MySQL vs PostgreSQL, their features, advantages, and disadvantages. Finally, check out which one is the best choice for you. Read the post](https://coderpad.io/blog/development/mysql-vs-postgresql-how-do-they-compare/) [Development ## PostgreSQL LIKE Operator: A Detailed Guide When using databases, searching for values that match a given pattern is a familiar necessity. Learn how you can retrieve entries with queries including a particular string using Postgres LIKE operator. Read the post](https://coderpad.io/blog/development/postgresql-like-operator-a-detailed-guide/) [Development ## How To Use DataProvider In TestNG With Examples When it comes to testing there are many tools and techniques available. In this post, we'll discuss how to use DataProvider with TestNG. Read the post](https://coderpad.io/blog/development/how-to-use-dataprovider-in-testng-with-examples/) [Development ## How To Get Up And Running With Django Migrations: A Guide Django migrations are a way of handling the application of changes to a database schema. By following the steps outlined in this guide, you can easily set up and use migrations in your Django projects. Read the post](https://coderpad.io/blog/development/how-to-get-up-and-running-with-django-migrations-a-guide/) [Development ## Writing A Parameterized Test In JUnit With Examples A JUnit parameterized test allows you to decouple data from structure, generating cleaner and more reliable tests. Learn more in this guide. Read the post](https://coderpad.io/blog/development/writing-a-parameterized-test-in-junit-with-examples/) [Development ## A Simple Guide To TypeORM: What It Is And How To Use It Considering current languages have object-oriented programming features, most database management systems are based on the relational model, with tables instead of objects. For these reasons, mapping relational objects is very important in development. In this article, you will learn what TypeORM, one of the main tools used today, is. Read the post](https://coderpad.io/blog/development/a-simple-guide-to-typeorm-what-it-is-and-how-to-use-it/) [Development ## Using PreparedStatement in JDBC With Examples In this post, we'll see why and how to work with JDBC and PreparedStatement. We will also learn along with examples using code. Read the post](https://coderpad.io/blog/development/using-preparedstatement-in-jdbc-with-examples/) [Development ## React vs React Native: The Differences Explained React and React Native are similar in that they both allow web developers to build applications based on the unique concept of components. But the two frameworks do this in radically different ways. In this post, we cover the key differences between react and react native frameworks, implementation, and which is an appropriate choice. Read the post](https://coderpad.io/blog/development/react-vs-react-native-the-differences-explained/) [Development ## Logging in Django The most challenging part of fixing a problem is identifying it. Unfortunately, this statement is exceptionally true when it comes to debugging. Learn how to use the power of logging into your Django applications to improve your debug process in this article. Read the post](https://coderpad.io/blog/development/logging-in-django/) [Development ## How To Get Started With TypeScript in Node.js TypeScript was the third most popular programming language in 2022, following Rust and Python. It’s widely admired by the JavaScript community and used by many companies to build front-end and back-end applications. In this post, let's dive into TypeScript, learn how to get started with TypeScript in a Node.js application, and then cover ts-node. Read the post](https://coderpad.io/blog/development/how-to-get-started-with-typescript-in-node-js/) ## Hire with confidence. See why engineering teams trust CoderPad to evaluate developers with realistic, AI-ready hiring workflows. [Request a demo](https://coderpad.io/sales/)