Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 29 ยท TestNG core

Dependencies, Priority and Test Ordering

Control TestNG test order with dependsOnMethods, dependsOnGroups, alwaysRun, priority and invocationCount, and learn why dependent tests are usually a design smell.

Good unit tests are independent: each one sets up what it needs, checks one thing, and can run alone or in any order. TestNG nevertheless ships with a feature set that explicitly lets tests depend on each other: dependsOnMethods, dependsOnGroups, priority. These exist because TestNG was built for more than unit tests. In large end-to-end flows (log in, create an order, pay it, check the receipt) it is natural to say "do not even try the payment test if the order could not be created".

This lesson explains each ordering tool, what TestNG does when a dependency fails, and when you should avoid all of it. The real TestNG code is read-only (it needs the TestNG jar and a build tool), and two JavaScript stand-ins let you run the scheduling logic: a dependency scheduler and an invocation-count runner. They model the documented behavior; they are not TestNG.

For the surrounding basics, see TestNG Annotations and Lifecycle and TestNG Assertions and Groups.

Four ways to shape a run

dependsOn... Run after other tests; skip if they fail.
priority Lower numbers run first.
invocationCount Repeat one test many times.
expectedExceptions The test must throw.
1 / 2

dependsOnMethods

Mark a test with the names of the methods it needs, and TestNG guarantees two things: those methods run first, and if any of them did not pass, the dependent test is skipped instead of run.

Java
import org.testng.annotations.Test;

public class OrderFlowTest {

    @Test
    public void login() { /* ... */ }

    @Test(dependsOnMethods = "login")
    public void createOrder() { /* ... */ }

    @Test(dependsOnMethods = {"createOrder"})
    public void payOrder() { /* ... */ }

    @Test(dependsOnMethods = "payOrder", alwaysRun = true)
    public void cleanUp() { /* runs even when payOrder failed or was skipped */ }
}

If createOrder fails, TestNG reports payOrder as skipped (not failed), and the report shows exactly one real failure: the root cause. That is the main benefit. Without dependencies, a broken login would make every later test fail with confusing messages.

Details to remember:

  • The names are strings, so a typo or a rename is not caught by the compiler. A name that matches no method makes TestNG throw an error before the run starts.
  • A circular dependency (a needs b, b needs a) is also reported as an error up front.
  • dependsOnMethods refers to methods by name; if you overload a method name, every overload counts.
  • alwaysRun = true on a @Test lets it run after its dependencies even if they failed. Use it for cleanup steps that must still happen.

dependsOnGroups

dependsOnGroups works the same way, but on labels: the test waits for every method in the named groups, and is skipped if any of them did not pass.

Java
@Test(groups = "init")
public void startDatabase() { }

@Test(groups = "init")
public void loadFixtures() { }

@Test(dependsOnGroups = "init")
public void queryWorks() { }

Group dependencies are less brittle than method names, because you can add a method to init without touching the dependents. They need the group names to be spelled correctly everywhere, which links to the group rules in the previous lesson.

priority

priority is a plain integer on @Test; lower numbers run first, the default is 0, and negative values are allowed. Methods with equal priority are ordered by name.

Java
@Test(priority = -1) public void checkEnvironment() { }
@Test                public void defaultPriority() { }       // priority 0
@Test(priority = 10) public void lastOfAll() { }

Priority is only a sort key; it does not skip anything. If a dependency and a priority disagree, the dependency wins: a test never runs before the methods it depends on, whatever its priority. Priority orders tests inside a class; it is not a good tool for ordering across classes (use the order of <class> entries in testng.xml, or avoid needing it).

A common beginner pattern is numbering every method (priority = 1, 2, 3) to force a script-like order. That works, but it hides a real relationship that dependsOnMethods would state, and it still runs step 3 after step 2 failed.

The scheduler, as a stand-in

How would a test runner turn these rules into an execution order? The stand-in below does it in a few lines: it repeatedly picks, among the tests whose dependencies are all finished, the one with the lowest priority (ties by name); it runs it, or skips it if a dependency did not pass and alwaysRun is off. It also reports unknown names and cycles. Change a test to throw and see which tests are skipped.

JS Stand-in: a dependency and priority scheduler

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

No output.

Case 4 is the one to remember: report has the lowest priority of all, yet runs after collect because it depends on it.

invocationCount, threadPoolSize and successPercentage

@Test(invocationCount = 100) runs one method 100 times. Used with threadPoolSize = 10 the invocations run on ten threads, a simple way to probe thread safety. successPercentage = 95 lets the test count as passed when at least 95% of the invocations pass. It is a tool for flaky behavior that is truly statistical (a random algorithm, a load probe), and a poor excuse for an unreliable test: a test that passes 95 percent of the time hides real bugs. See Flaky Tests and Common Mistakes for the better fixes.

Java
@Test(invocationCount = 50, threadPoolSize = 5, successPercentage = 100)
public void counterIsThreadSafe() { /* hammer the counter */ }

@Test(invocationTimeOut = 500)   // each call must finish within 500 ms
public void lookupIsFast() { }

The stand-in below counts passes with a seeded random generator, so the result is the same every time.

JS Stand-in: invocationCount and successPercentage

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

No output.

expectedExceptions

@Test(expectedExceptions = IllegalArgumentException.class) makes the test pass only if the method throws that exception, and expectedExceptionsMessageRegExp = "amount must be .*" also matches the message. It is the TestNG ancestor of JUnit's assertThrows, and it works, but it has the same weakness as JUnit 4's @Test(expected = ...): the whole method is covered, so an exception thrown by the setup lines also passes. TestNG has Assert.assertThrows and Assert.expectThrows (the latter returns the exception); prefer them whenever the test has any code before the call that must throw.

When dependencies are a smell

Tests that depend on each other have costs:

  • They cannot run alone. Running payOrder from your IDE means running login and createOrder first, and other tools may not honor dependencies the same way.
  • One failure hides many tests. A single broken step turns the rest of the chain into skips, and you learn nothing about those features until the first problem is fixed.
  • They share state, usually hidden. The order id created by createOrder has to live in a field, which breaks as soon as methods run in parallel.
  • They hide design problems. If testing the third step needs the first two, the code under test often has the same hidden coupling.

A better default: give every test its own arrangement, using @BeforeMethod, builders, or an in-memory fixture, and use dependencies only where the scenario itself is a sequence (end-to-end flows, smoke checks like "if the server is not up, skip the rest"), or as a coarse guard such as dependsOnGroups = "init".

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A test with dependsOnMethods = "login" runs, and login failed. What does TestNG report for the dependent test?

    A test whose dependencies did not pass is skipped. That keeps the report focused on the root cause.
  2. 2. A test has priority = -5 but dependsOnMethods = "collect", where collect has priority = 5. Which runs first?

    Priority is only a sort key among tests that are ready to run. A test is never ready before its dependencies have finished.
  3. 3. What does alwaysRun = true on a @Test method with dependencies do?

    The test still runs after its dependencies, but it is not skipped when they fail. It suits cleanup steps.
  4. 4. Why are dependent tests often considered a design smell for unit tests?

    Independent tests are easier to run, debug and parallelize. Use dependencies for genuine step-by-step scenarios, not to share state.
  5. 5. What is the main weakness of @Test(expectedExceptions = ...) compared with Assert.assertThrows?

    With expectedExceptions any line in the method can throw the expected type. assertThrows wraps just the call that must throw.

Summary

  • dependsOnMethods and dependsOnGroups make a test run after others and be skipped when they did not pass; alwaysRun = true overrides the skip for cleanup.
  • priority orders tests by integer (lower first, default 0, ties by name); dependencies always beat priority.
  • Wrong dependency names and cycles are rejected before the run starts.
  • invocationCount, threadPoolSize, successPercentage and invocationTimeOut repeat, parallelize and bound a test; do not use a success percentage to excuse a flaky test.
  • expectedExceptions works but covers the entire method; prefer Assert.assertThrows or expectThrows.
  • Prefer independent tests; use dependencies for real sequences and coarse guards.

Next: you now know the TestNG core. The next TestNG lessons in this track cover data providers and factories for data-driven tests.