skip to content

With TestNG's org.testng.Assert.assertEquals, in which order do the actual value, expected value and message go, and what breaks if they are swapped?

level: middleimportance: must knowfreq 50%

answer

  1. natural reading order
  2. the value under test leads
  3. message trails the two values
  4. backwards failure text after migration

basics

~20 s

TestNG's Assert.assertEquals takes (actual, expected, message). Swapping the first two normally leaves pass or fail unchanged, but the failure text 'expected [x] but found [y]' then reports the values backwards and misleads whoever triages it.

solid answer

~40 s

TestNG's `org.testng.Assert` puts the **actual** value first, the **expected** value second and the optional **message** last: `assertEquals(response.status(), 200, "status")`. That is the reverse of JUnit Jupiter, whose `assertEquals` takes the expected value first. If a JUnit habit swaps them, the verdict normally does not change, because TestNG checks equality in both directions, but the failure text becomes `status expected [503] but found [200]`, naming the real result as the expectation, so whoever triages it chases the wrong side. Suites moved from JUnit by rewriting imports carry this everywhere. The fix is to reorder each call in one reviewed change; during a staged move, old expected-first calls can sit on TestNG's `org.testng.AssertJUnit`, which keeps JUnit's order, until they are converted.

code

java · 23 lines
java
import static org.testng.Assert.assertEquals;

import org.testng.annotations.Test;

public class HealthEndpointTest {

  @Test
  public void healthReturnsOk() {
    int status = callHealthEndpoint();

    // TestNG order: actual, expected, message
    assertEquals(status, 200, "health status");
    // On failure: health status expected [200] but found [503]

    // JUnit habit, reversed for TestNG:
    // assertEquals(200, status, "health status");
    // On failure: health status expected [503] but found [200]
  }

  private int callHealthEndpoint() {
    return 200;
  }
}

go deeper

for a junior

Recall that TestNG's Assert takes the actual value first, the expected value second and the message last, and that JUnit Jupiter puts the expected value first.

for a middle

Explain that a swap normally keeps the verdict but inverts the 'expected [x] but found [y]' text, and show the correct call and its failure message.

for a senior

Diagnose a migrated suite whose failure messages read backwards, including message-first calls that compile against the String overload, and plan a reviewed fix.

for a principal

Decide whether a migration converts every call to TestNG's order in one pass or parks old classes on AssertJUnit first, and how review keeps new calls consistent.

## The signature Every equality check on `org.testng.Assert` follows one rule, stated in the class's own documentation: the order is always **actual value, expected value**, then an optional **message**. ```java Assert.assertEquals(Object actual, Object expected, String message); Assert.assertEquals(int actual, int expected, String message); Assert.assertNotEquals(Object actual, Object expected, String message); Assert.assertSame(Object actual, Object expected, String message); ``` - **actual** is the value the code under test produced. - **expected** is the value the test specifies. - **message** is a short label that TestNG puts in front of the failure text. The authors chose this order because it reads like a sentence: "assert that the status equals 200". JUnit Jupiter made the opposite choice and takes the expected value first, which is where most confusion starts. ## What the failure message says When an equality check fails, TestNG builds the text from the two slots, not from what you meant by them: ```text <message> expected [<value in the expected slot>] but found [<value in the actual slot>] ``` So for `assertEquals(status, 200, "health status")` with a status of 503, the report says `health status expected [200] but found [503]`, which is correct. Write the same check JUnit-style as `assertEquals(200, status, "health status")` and the report says `health status expected [503] but found [200]`. Both versions fail on the same input, because TestNG compares the two values in both directions; only the story the message tells is inverted. ## How a migrated suite ends up backwards The usual sequence: 1. A suite written for JUnit uses `assertEquals(expected, actual)` throughout. 2. The team moves it to TestNG and changes `import static org.junit...` lines to `import static org.testng.Assert.*`. 3. Everything compiles, because the parameter types are symmetric, and the green tests stay green. 4. Weeks later a real regression fails with `expected [503] but found [200]`, and the engineer on call goes looking for why the service returned 200. The inverted text costs time on every failure, and because nothing broke at migration time, nobody connects it to the import change. ## Reading a failure you did not write When a report lands in front of you, two quick tests reveal a reversed call before you open the code: - **Look at which side looks computed.** If the `expected [...]` side holds a timestamp, a generated id or an error string, and the `found [...]` side holds a tidy literal like `200`, the arguments are almost certainly swapped. - **Compare with the method name.** A test called `returnsCreatedStatus` that reports `expected [500] but found [201]` is telling you the code returned 500, not 201. One check is immune: when `assertNotEquals` fails, both values are equal by definition, so its `did not expect [x] but found [x]` text normally reads the same whichever way round the arguments are. The swap only misleads on equality and identity checks, which is most of them. ## Message position across TestNG's checks | Method | Where the message goes | |---|---| | `assertEquals`, `assertNotEquals`, `assertSame` | Last, after actual and expected | | `assertTrue`, `assertFalse`, `assertNull`, `assertNotNull` | Last, after the single value | | `assertThrows`, `expectThrows` | **First**, before the exception class | | `AssertJUnit.assertEquals` | First, followed by expected then actual | The last row is TestNG's compatibility class `org.testng.AssertJUnit`, which keeps the JUnit 3/4-style signatures. It exists precisely so expected-first calls keep their meaning when only the import changes. ## Fixing a migrated suite - **Find the suspects.** In TestNG, a call whose first argument is a literal or a constant and whose second is a variable or a method call is almost always reversed. A regex or structural code search finds most of them. - **Review each hit.** A literal can legitimately be the value under test inside a fixture, so this is not a blind search-and-replace. - **Fix in one change.** Mixed conventions are worse than either convention, because no reader can trust any failure text. - **Or stage it.** Point the unconverted classes at `org.testng.AssertJUnit` first, so their order is honest immediately, then convert class by class. - **Watch message-first calls.** A JUnit 3/4-style `assertEquals("status", "OK", result)` still compiles against `org.testng.Assert`, because TestNG has an `assertEquals(String actual, String expected, String message)` overload. It then compares the label with the expected value and fails every time, printing the real result as its message. ## Contrast with JUnit Jupiter In one sentence: JUnit Jupiter's `assertEquals` is expected-first with the message last, TestNG's `Assert` is actual-first with the message last, and the two compile against the same arguments, which is exactly why the swap goes unnoticed.

  • Why does a JUnit 3/4-style call like assertEquals("status", "OK", result) still compile after its import is switched to org.testng.Assert?
    TestNG has an assertEquals(String actual, String expected, String message) overload. The label "status" lands in the actual slot, "OK" in the expected slot and the real result becomes the message, so the call compares two constants and fails every time. Message-first calls need reordering, or TestNG's AssertJUnit, not just a new import.
  • How would you find swapped arguments across a large migrated TestNG suite?
    Search for assertEquals calls whose first argument is a literal or constant and whose second is a variable or method call; in TestNG that shape usually means the values are reversed. Review each hit, since a literal can be the value under test in a fixture, and fix them in one reviewed change so every failure message can be trusted again.

  • TestNG's assertEquals takes the expected value first, the same as JUnit Jupiter.
  • Swapping actual and expected in TestNG turns passing tests into failing ones.
  • Every org.testng.Assert method takes the message as its last parameter.
  • Changing the imports from JUnit to org.testng.Assert completes the assertion migration.
  • Argument order is cosmetic, because only pass or fail matters.