Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 29 ยท Practice and review

JUnit and TestNG Cheat Sheet

A side-by-side JUnit 6 and TestNG cheat sheet: annotations, assertions, lifecycle order, parameterized tests, filtering, Maven and Gradle commands and common fixes.

This page is the whole track on a few screens. Use it when you know a feature exists but cannot remember its name, or when you move between a JUnit project and a TestNG one in the same week. Everything here is read-only reference, except two small stand-ins at the end that let you look things up by typing. Each section links back to the lesson with the full explanation.

Where to look

Annotations JUnit and TestNG side by side.
Assertions Names and argument order.
Lifecycle What runs before and after what.
Commands Maven, Gradle and fixes.
1 / 2

Annotations side by side

Purpose JUnit Jupiter (6) TestNG
Mark a test @Test (org.junit.jupiter.api) @Test (org.testng.annotations)
Before each test @BeforeEach @BeforeMethod
After each test @AfterEach @AfterMethod
Once per class @BeforeAll / @AfterAll (static by default) @BeforeClass / @AfterClass
Once per <test> / suite (use extensions or a launcher listener) @BeforeTest, @BeforeSuite and After pairs
Skip @Disabled("why") @Test(enabled = false)
Readable name @DisplayName("...") @Test(description = "...")
Group or filter @Tag("slow") @Test(groups = {"slow"})
Expect an exception assertThrows(X.class, () -> ...) @Test(expectedExceptions = X.class)
Timeout @Timeout(2) (seconds) @Test(timeOut = 2000) (ms)
Repeat @RepeatedTest(5) @Test(invocationCount = 5)
Data-driven @ParameterizedTest + a source @Test(dataProvider = "name")
Test order @TestMethodOrder, @Order priority, dependsOnMethods
Nested structure @Nested inner class (use separate classes or groups)
Extend the framework @ExtendWith, @RegisterExtension listeners and IMethodInterceptor
Instance per test New instance for each method One instance for the class

Lessons: JUnit first test, lifecycle and nesting, TestNG annotations.

Assertions

Check JUnit (expected first) TestNG (actual first)
Equality assertEquals(expected, actual) assertEquals(actual, expected)
Doubles assertEquals(e, a, delta) assertEquals(a, e, delta)
Boolean assertTrue(c), assertFalse(c) assertTrue(c), assertFalse(c)
Null assertNull(x), assertNotNull(x) assertNull(x), assertNotNull(x)
Same instance assertSame(e, a) assertSame(a, e)
Collections assertIterableEquals(e, a) assertEquals(actualCollection, expectedCollection)
Throws assertThrows(X.class, executable) assertThrows(X.class, runnable)
Group of checks assertAll(...) new SoftAssert() then assertAll()
Unconditional failure fail("message") fail("message")
Custom message last argument, a String or Supplier<String> last argument, a String

Rules worth remembering:

  • Put the message in the last position in both libraries; use a Supplier in JUnit when building the message is costly.
  • Compare doubles with a delta, never with exact equality.
  • assertThrows returns the exception, so you can check the message afterward.
  • A TestNG SoftAssert that never calls assertAll() never fails.

Details: JUnit assertions, TestNG assertions and groups.

Lifecycle order

JUnit, per class:

TEXT
@BeforeAll (once)
  new instance
    @BeforeEach -> test -> @AfterEach
  new instance
    @BeforeEach -> test -> @AfterEach
@AfterAll (once)

TestNG, per suite:

TEXT
@BeforeSuite
  @BeforeTest
    @BeforeClass
      @BeforeMethod -> test -> @AfterMethod
      @BeforeMethod -> test -> @AfterMethod
    @AfterClass
  @AfterTest
@AfterSuite

In an inherited hierarchy, set-up methods of the superclass run first and tear-down methods of the superclass run last, in both libraries. In JUnit, nested classes add their own @BeforeEach after the outer one.

Parameterized and dynamic tests

Need JUnit TestNG
A list of single values @ValueSource(ints = {1, 2, 3}) provider returning Object[][]
Rows of values @CsvSource({"a,1", "b,2"}) Object[][] { {"a", 1}, {"b", 2} }
Values from a method @MethodSource("cases") (static) @DataProvider method
All enum constants @EnumSource(Color.class) a provider building the array
Tests generated at run time @TestFactory returning DynamicTests @Factory returning test objects
Values from testng.xml not applicable @Parameters({"baseUrl"})
Run the rows in parallel JUnit parallel execution setting @DataProvider(parallel = true)

See Parameterized and Dynamic Tests and Data Providers and Factories.

Choosing what runs

Goal JUnit way TestNG way
One class build filter, or selectClass in the Launcher <class name="..."/> in testng.xml
One method selectMethod or -Dtest=Class#method <methods><include name="..."/></methods>
By label @Tag and includeTags / excludeTags groups plus <include> / <exclude>
Only on some systems @EnabledOnOs, @EnabledIf, assumeTrue check inside the test, or skip with SkipException
Everything except slow exclude tag slow exclude group slow

Build commands

Maven:

Terminal
mvn test                                   # all tests Surefire finds
mvn test -Dtest=OrderServiceTest           # one class
mvn test -Dtest=OrderServiceTest#cancels   # one method
mvn test -Dgroups=fast                     # JUnit tag or TestNG group
mvn test -DexcludedGroups=slow
mvn verify                                 # also runs integration tests (Failsafe)
mvn -DskipTests package                    # compile tests but do not run them

Gradle:

Terminal
gradle test                                      # all tests
gradle test --tests OrderServiceTest             # one class
gradle test --tests 'OrderServiceTest.cancels'   # one method
gradle cleanTest test                            # force a re-run

Gradle build file (Kotlin DSL), one engine at a time:

Kotlin
tasks.test {
    useJUnitPlatform()          // JUnit Jupiter (and Vintage, if on the classpath)
    // useTestNG()              // or TestNG
}

Maven's Surefire plugin runs classes named *Test, Test*, *Tests and *TestCase by default; Failsafe is conventionally used for *IT. Lessons: Maven and Gradle, Coverage and CI.

Common problems and fixes

Symptom Likely cause Fix
Test compiles but never runs Imported org.junit.Test (JUnit 4) in a Jupiter project, or class name does not match Surefire patterns Import from org.junit.jupiter.api; rename to *Test
"No tests found" with TestNG Engine not selected in the build useTestNG() in Gradle, TestNG dependency on the Maven classpath
@BeforeAll method not static Default per-method lifecycle Make it static or add @TestInstance(PER_CLASS)
Message says expected and actual the wrong way round Mixed JUnit and TestNG argument order Use one convention per module
Passes alone, fails in a suite Shared static or database state Reset state in @BeforeEach, avoid static mutable fields
Fails only at certain hours Real clock Inject Clock
Fails now and then Sleeps, threads, random data Wait on conditions, seed random generators
UnnecessaryStubbingException Mockito strict stubs found an unused stub Delete the stub or fix the test
TestNG test is skipped, not failed A dependsOnMethods dependency failed Fix the first failure
Soft assertions never fail assertAll() was not called Call it at the end, or in an @AfterMethod

The longer story behind the flakiness rows is in Flaky Tests and Common Mistakes.

Two lookups you can run

The first stand-in is a tiny translator built from the annotation table above. Edit the list of names you want to translate. It is only a lookup table, not a real migration tool; the full strategy is in Migrating from JUnit 4 and Between Frameworks.

JS Annotation translator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

@Rule is missing from the table on purpose. Rules are not a one-to-one rename: they become extensions, as described in Writing JUnit Extensions.

The second stand-in builds the Maven and Gradle commands for a goal. Change goal and read the result.

JS Command picker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Gradle has no command-line flag for tags or groups in a plain setup; you set them in the build file (or read a project property there), which is why that row prints a configuration line instead of a command.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which JUnit Jupiter annotation matches TestNG's @BeforeMethod?

    @BeforeEach runs before every test method, just as @BeforeMethod does in TestNG.
  2. 2. How do you run one test method with Maven Surefire?

    -Dtest accepts Class#method. -Dgroups selects tags or groups, not method names.
  3. 3. Which pair is in the right argument order?

    JUnit puts the expected value first and TestNG the actual value first.
  4. 4. A TestNG test shows as skipped. What is a likely reason?

    With dependsOnMethods or dependsOnGroups, a failed dependency makes TestNG skip the dependent tests.

Summary

  • Memorize the pairs: @BeforeEach/@BeforeMethod, @AfterEach/@AfterMethod, @BeforeAll/@BeforeClass, @Disabled/enabled = false, @Tag/groups.
  • JUnit creates a new instance per test method; TestNG one per class.
  • JUnit's assertEquals(expected, actual) is the reverse of TestNG's assertEquals(actual, expected).
  • mvn test -Dtest=Class#method and gradle test --tests Class.method run a single test; tags and groups are chosen with -Dgroups in Maven or in the Gradle build file.
  • Most mysterious failures are one of: wrong import, wrong name pattern, shared state, real time, or a failed dependency.

That is the end of the track. If you want more practice, repeat the exercises with the opposite framework, or start again from the testing landscape and read it with fresh eyes.