JUnit assertions are essential for validating test outcomes in Selenium automation. They help confirm that your application behaves as expected during UI tests.
Overview
What are JUnit Assertions?
JUnit assertions are methods used to verify that a specific condition is true during test execution. If the condition fails, the test is marked as failed, helping identify bugs early in the development cycle.
Common Assertions in JUnit 5
JUnit 5 provides a comprehensive set of assertions to validate different conditions in your tests.
- assertEquals(expected, actual) – Verifies equality between expected and actual values.
- assertNotEquals(expected, actual) – Confirms that expected and actual values are not equal.
- assertTrue(condition) – Confirms that a given condition is evaluated as true.
- assertFalse(condition) – Confirms that a given condition is evaluated as false.
- assertNull(value) – Asserts that a value is null.
- assertNotNull(value) – Asserts that a value is not null.
- assertSame(expected, actual) – Verifies that two references point to the same object.
- assertNotSame(unexpected, actual) – Verifies that two references do not point to the same object.
- assertArrayEquals(expectedArray, actualArray) – Confirms that two arrays contain the same elements in the same order.
- assertThrows(expectedException.class, executable) – Verifies that the executable throws the expected exception.
- assertDoesNotThrow(executable) – Confirms that the executable does not throw any exception.
- assertAll() – Allows grouping multiple assertions together for collective evaluation.
- fail(message) – Marks a test as failed unconditionally.
This article explains how to use these JUnit 5 assertions effectively in Selenium tests, with practical examples to strengthen your test automation strategy.
What are Assertions in Selenium Testing?
Assertions in Selenium testing validate that your web application behaves as expected during test execution. While Selenium handles browser automation (like clicking buttons or filling forms), assertions come from testing frameworks like JUnit or TestNG and verify outcomes, such as page titles, element values, or the presence of UI components.
By adding assertions to your Selenium tests, you can automatically check whether:
- A specific element is visible on the page
- The current URL or title matches the expected value
- A user action results in the correct output or state
If an assertion fails, the test stops and is marked as failed, helping catch bugs early and reliably.
Different types of Asserts
There are two primary types of JUnit assert methods.
Hard Assert
In hard assert, the program execution stops as soon as an exception occurs and thereby skipping all the next steps in the test method. It throws an Assertion error and marks the test case as failed though all the steps in the test method were not executed. After the assert fails, the current test is skipped and the next @Test is executed.
Example: Hard assert can be used in login scenarios, where we would like the execution to stop if the login credentials are not valid.
Soft Assert
In some cases, we need the test execution to continue even when there is any exception encountered. Soft Asserts do not throw an Assertion error if there is any exception and rather record the failure. Later, it collects all the assertions throughout the @Test method and throws all the exceptions caught during the process with the assertAll() method.
Example: Soft assert can be used to verify multiple page elements of any landing page, where we would like all the steps to be executed and to throw an error only at the last line of the @Test method.
Also Read: Assert and Verify Methods in Selenium
Benefits of JUnit5 over JUnit4
JUnit 5 introduces a more flexible and modern testing architecture than JUnit 4. It supports new programming paradigms and provides better extensibility for advanced testing needs. Here are the key benefits:
- Modular structure: JUnit 5 separates the platform, test engine, and backward compatibility into distinct modules (Platform, Jupiter, Vintage).
- Clearer annotations: Uses @BeforeEach, @AfterEach, @BeforeAll, and @AfterAll instead of JUnit 4’s @Before, @After, etc.
- Dynamic tests: Supports runtime test generation using @TestFactory, which is helpful for parameterized or data-driven testing.
Read More: What is Assertion Testing?
- Richer assertions: Includes assertAll, assertThrows, and assertTimeout for more flexible validation.
- Flexible extension model: Replaces @Rule and @ClassRule with a more powerful Extension API for custom behavior.
- Improved IDE and build tool support: Native compatibility with modern tools like Maven, Gradle, and IntelliJ for better integration.
Read More: How to install Selenium in Intellij?
- Custom display names: @DisplayName lets you assign readable names to test classes and methods.
- Tag-based filtering: @Tag allows grouping and selectively running tests for better test management.
Adding JUnit Library, JUnit5 and Maven Dependencies
Assuming Selenium Java and WebDriverManager JARs are already included, the next step is to add the JUnit 5 library and its Maven dependencies.
Add the following dependency inside the <dependencies> tag in the pom.xml file of the Maven project you are using.
<dependency> <groupId>org.seleniumhq.selenium</groupId> <artifactId>selenium-java</artifactId> <version>4.3.0</version> </dependency> <dependency> <groupId>io.github.bonigarcia</groupId> <artifactId>webdrivermanager</artifactId> <version>5.2.1</version> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-engine</artifactId> <version>5.0.0</version> <scope>compile</scope> </dependency>
Also, add JUnit5 library by right clicking on the Maven project and selecting -> “Build Path” >> “Configure Build Path” >> “Add Library” >> JUnit. Click “Next”, Select “JUnit5” from the “JUnit Library version” dropdown and click on “Finish”. Finally click “Apply and Close” to save the configuration.
JUnit5 Assertions Class Methods
To use JUnit assert methods, import org.junit.jupiter.api.Assertions class.
All JUnit Jupiter Assertions are static methods. As per the official document, “Assertions is a collection of utility methods that support asserting conditions in tests.”
1. assertEquals()
Use Assertions.assertEquals() method, if you need to assert that any given two values are equal.
assertEquals() is an overloaded method for different data types such as byte, char, double, float, int, long, Object, short. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertEquals(int expected, int actual) assertEquals(Object expected, Object actual) assertEquals(Object expected, Object actual, String message)
Program:
public class AssertionsTest {
static WebDriver driver;
static String url = "http://automationpractice.com/index.php";
WebElement wb=driver.findElement(By.xpath("//span[@class='shop-phone']//i[@class='icon-phone']/following-sibling::strong"));
@BeforeAll
public static void setUp() {
WebDriverManager.chromedriver().setup();
driver = new ChromeDriver();
driver.manage().window().maximize();
driver.get(url);
}
@Test
@DisplayName("AsserEquals demo")
public void assertEquals() {
//This will fail
Assertions.assertEquals("0123-23456", wb.getText());
Assertions.assertEquals('S', 'S');
//This will fail
Assertions.assertEquals("JUnit5", "JUnit4", "Strings are not equal");
}
}In the first assertion, we are expecting “0123-23456” and the actual value is “0123-456-789”. So, the assertion will fail.
In the third assertion, we are expecting “JUnit5”, and actual value is “JUnit4”, so the assert will fail with the message passed.
In case of failure, AssertionFailedError exception will be thrown in the following manner:
2. assertNotEquals()
Use Assertions.assertNotEquals() method, if you need to assert that given any two values are not equal.
assertNotEquals() supports only Object data type as parameter. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertNotEquals (Object unexpected, Object actual) assertNotEquals (Object unexpected, Object actual, String message)
Program:
@Test
@DisplayName("AsserNotEquals demo")
public void assertNotEquals() {
//This will fail
Assertions.assertNotEquals("0123-456-789", wb.getText());
Assertions.assertNotEquals("JUnit5", "JUnit4");
Assertions.assertNotEquals('S', 'T');
}In case of failure, AssertionFailedError exception will be thrown in the following manner:
3. assertArrayEquals()
Use Assertions.assertArrayEquals() method, if you need to assert that given any two arrays are equal.
assertArrayEquals() is an overloaded method for different data types such as boolean[], byte[], char[], double[], float[], int[], long[], Object[], short[]. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertArrayEquals (int expected, int actual) assertArrayEquals (Object expected, Object actual) assertArrayEquals (int expected, int actual, String message)
Program:
@Test
@DisplayName("AssertArrayEquals demo")
public void assertArrayEquals() {
int[] array1 = { 1, 2, 3 };
int[] array2 = { 2, 3, 1 };
//This will fail
Assertions.assertArrayEquals(array1, array2);
}The assert will fail as element order is different.
In case of failure, AssertionFailedError exception will be thrown in the following manner:
4. assertNull()
Use Assertions.assertNull() method, if you need to assert that given any value is null.
assertNull() supports only Object data type as parameter. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertNull (Object actual) assertNull (Object actual, String message)
Program:
@Test
@DisplayName("AssertNull demo")
public void assertNull() {
Assertions.assertNull(null);
//This will fail
Assertions.assertNull(wb.getText());
}The second assert will fail as we are passing element string value which is not null
In case of failure, AssertionFailedError exception will be thrown in the following manner:
5. assertNotNull()
Use Assertions.assertNotNull() method, if you need to assert that given any value is not null.
assertNotNull() supports only Object data type as parameter. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertNotNull (Object actual) assertNotNull (Object actual, String message)
Program:
@Test
@DisplayName("AssertNotNull demo")
public void assertNotNull() {
Assertions.assertNotNull(wb.getText());
//This will fail
Assertions.assertNotNull(null);
}The second assert will fail as we are explicitly passing null value.
In case of failure, AssertionFailedError exception will be thrown.
6. assertSame()
Use Assertions.assertSame() method, if you need to assert that given any two values refer to the same object.
assertSame() supports only Object data type as parameter. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertSame (Object expected, Object actual) assertSame (Object expected, Object actual, String message)
Program:
@Test
@DisplayName("AssertSame demo")
public void assertSame() {
String s1="JUnit is great!";
String copy=s1;
String s2="JUnit is fun!";
Assertions.assertSame(s1, copy);
//This will fail
Assertions.assertSame(s1, s2);
}First assert will pass as copy and s1 refer to the same object
Second assert will fail as s1 and s2 refer to the different object
In case of failure, AssertionFailedError exception will be thrown in the following manner:
7. assertNotSame()
Use Assertions.assertNotSame() method, if you need to assert that given any two values do not refer to the same object.
assertNotSame() supports only Object data type as parameter. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertNotSame (Object unexpected, Object actual) assertNotSame (Object unexpected, Object actual, String message)
Program:
@Test
@DisplayName("AssertNotSame demo")
public void assertNotSame() {
String s1="Selenium";
String copy=s1;
String s2="Playwright";
//This will fail
Assertions.assertNotSame(s1, copy);
Assertions.assertNotSame(s1, s2);
}First assert will fail as s1 and copy refer to the same object
Second assert will pass as s1 and s2 refer to the different object
In case of failure, AssertionFailedError exception will be thrown in the following manner:
8. assertTrue()
Use Assertions.assertTrue() method, if you need to assert that the supplied condition is true.
assertTrue() supports only boolean value as parameter. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertTrue (boolean condition) assertTrue (boolean condition, String message)
Program:
@Test
@DisplayName("AssertTrue demo")
public void assertTrue() {
Assertions.assertTrue(true);
//This will fail
Assertions.assertTrue(5 < 0);
Assertions.assertTrue(wb.isDisplayed());
}Second assert will fail as 5<0 returns false
In case of failure, AssertionFailedError exception will be thrown in the following manner:
9. assertFalse()
Use Assertions.assertFalse() method, if you need to assert that the supplied condition is false.
assertFalse() supports only boolean value as parameter. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertFalse (boolean condition) assertFalse (boolean condition, String message)
Program:
@Test
@DisplayName("AssertFalse demo")
public void assertFalse() {
Assertions.assertFalse(false);
Assertions.assertFalse(5 < 0);
//This will fail
Assertions.assertFalse(wb.isDisplayed(), "Expected web element not to be displayed");
}Third assert will fail as element is displayed on webpage which is true value
In case of failure, AssertionFailedError exception will be thrown as seen below:
10. assertIterableEquals()
Use Assertions.assertIterableEquals () method, if you need to assert that the actual and expected iterables are deeply equal. It means the total number of elements and the order of actual and expected should be equal.
assertThrows() supports Iterable object as parameter. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertIterableEquals(Iterable<?> expected, Iterable<?> actual) assertIterableEquals(Iterable<?> expected, Iterable<?> actual, String message)
Program:
@Test
@DisplayName("AssertIterableEquals demo")
public void assertIterableEquals() {
final List<Integer> firstList = Arrays.asList(1, 2, 3);
final List<Integer> secondList = Arrays.asList(1, 2, 3);
final List<Integer> thirdList = Arrays.asList(3, 1, 2);
Assertions.assertIterableEquals(firstList, secondList);
//This will fail
Assertions.assertIterableEquals(firstList, thirdList);
}First assert will pass as firstList and secondList have the same number of elements and are in the same order.
Second assert will pass as firstList and thirdList have the same number of elements but are not in the same order.
In case of failure, AssertionFailedError exception will be thrown in the following manner:
11. assertThrows()
Use Assertions.assertThrows() method, if you need to assert that the supplied executable throws an exception of the expected type and returns the exception.
assertThrows() supports only exception classes and executable as parameters. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertThrows (Class<T> expectedType, Executable executable) assertThrows (Class<T> expectedType, Executable executable, String message)
Program:
@Test
@DisplayName("AssertThrows demo")
public void assertThrows() {
Throwable ex =Assertions.assertThrows(IllegalArgumentException.class,
()-> {throw new IllegalArgumentException();});
//This will fail
Throwable exc=Assertions.assertThrows(IllegalArgumentException.class,
()-> {throw new NullPointerException();});
}First assert will pass as expected Exception type and the error thrown by the executable are the same.
Second assert will fail as expected Exception type and the error thrown by the executable are different.
In case of failure, AssertionFailedError exception will be thrown in the following manner:
12. assertTimeout()
Use Assertions.assertTimeout() method, if you need to assert that the execution of the system under test is completed before the specified timeout is exceeded.
assertTimeout() supports Duration object, ThrowingSupplier object or an executable. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertTimeout (Duration timeout, Executable executable) assertTimeout (Duration timeout, Executable executable, String message)
Program:
@Test
@DisplayName("AssertTimeout demo")
public void assertTimeout() {
Assertions.assertTimeout(Duration.ofMinutes(1), ()-> {return "testresult";});
Assertions.assertTimeout(Duration.ofMillis(100), () -> {
Thread.sleep(200);
return "testresult";
});
}- The first assert will pass as we expect the message to be returned before 1 min. And as there is no delay provided, the message will be returned instantly.
- The second assert will fail as we expect the message to be returned before 100 milliseconds. And as there is a delay of 200 milliseconds before returning the message, it will obviously fail.
In case of failure, AssertionFailedError exception will be thrown in the following manner:
13. assertTimeoutPreemptively()
In assertTimeoutPreemptively () method, execution of the Executable or ThrowingSupplier will be preemptively aborted if the timeout is exceeded.
assertTimeout() supports Duration object, ThrowingSupplier object or an executable. It also supports error messages to be passed as an argument in case of test failure.
Syntax:
assertTimeoutPreemptively (Duration timeout, Executable executable) assertTimeout Preemptively (Duration timeout, Executable executable, String message)
Program:
@Test
@DisplayName("AssertTimeoutPreemptively demo")
public void assertTimeoutPreemptively() {
Assertions.assertTimeoutPreemptively(Duration.ofMinutes(1), ()-> {return "testresult";});
Assertions.assertTimeoutPreemptively(Duration.ofMillis(100), () -> {
Thread.sleep(200);
return "testresult";
});
}In case of failure, AssertionFailedError exception will be thrown in the following manner:
14. fail()
Use Assertions.fail() method, if you need to fail a particular method with the supplied message as well as the underlying cause of the failure.
fail() supports String and Throwable values as parameters.
Syntax:
fail(String message)
fail(String message, Throwable cause)
Program:
@Test
@DisplayName("Fail demo")
public void Fail() {
Assertions.fail("This method is failed");
}In case of failure, AssertionFailedError exception will be thrown in the following manner:
There you have it. 14 different examples on how to use different types of JUnit Assertions for Selenium Tests. Ensure that refer to our documentation while you’re running your first Selenium test with JUnit 5 on BrowserStack Automate
Integrate Selenium with JUnit5
Running Selenium tests with JUnit5 on BrowserStack
BrowserStack is a cloud-based testing platform that enables developers and QA teams to run Selenium automation on real browsers and mobile devices hosted in remote data centers. It integrates seamlessly with Selenium (via BrowserStack Automate), allowing cross-browser and cross-device testing without maintaining a local device lab.
Key Features of BrowserStack:
- Real Device Cloud: Access over 3,500 combinations of real desktop browsers and mobile devices to ensure authentic test environments
- Parallel Testing: Run hundreds of tests simultaneously to reduce overall test runtime and accelerate releases.
- Local Testing: Securely test apps hosted on internal or staging environments via an encrypted local proxy.
- Comprehensive Debugging Tools: Capture logs, screenshots, and full video recordings alongside Selenium sessions for fast root-cause analysis
- Network and Geolocation Simulation: Emulate various network speeds and geo-locations to validate performance under real-world conditions.
Conclusion
JUnit assertions validate test outcomes and ensure your Selenium test scripts are both reliable and meaningful. By using a variety of assertions like assertEquals, assertTrue, and assertThrows, you can systematically verify UI behavior and catch regressions early in the development cycle.
To further enhance your Selenium testing, run JUnit tests on BrowserStack. This allows teams to run cross-browser and cross-device tests under real user conditions without managing infrastructure. In addition, parallel execution helps reduce overall test duration, while CI integration enables continuous testing within development pipelines.
Featured Article
