@Execution annotation in JUnit - Deep Dive

Overview - @Execution annotation

What is it?

The @Execution annotation in JUnit 5 controls how test methods or classes are run in terms of concurrency. It lets you specify whether tests should run sequentially or concurrently. This helps manage test execution behavior to improve speed or avoid conflicts. It is used to optimize test runs and handle shared resources safely.

Why it matters

Without controlling test execution concurrency, tests might run in an unpredictable order or interfere with each other, causing flaky or incorrect results. The @Execution annotation solves this by letting you explicitly choose parallel or sequential execution. This improves test reliability and can speed up testing by running safe tests in parallel. Without it, developers waste time debugging random failures or waiting for slow sequential tests.

Where it fits

Before learning @Execution, you should understand basic JUnit 5 test structure and annotations like @Test. Knowing about test lifecycle and parallel execution concepts helps. After this, you can explore JUnit 5's full parallel execution configuration and advanced concurrency controls.

Mental Model

Core Idea

The @Execution annotation tells JUnit whether to run tests one after another or at the same time to balance speed and safety.

Think of it like...

It's like deciding if you want to cook dishes one by one on a single stove or use multiple stoves to cook several dishes at once without burning anything.

┌─────────────────────────────┐
│        Test Class           │
├─────────────┬───────────────┤
│ @Execution  │ ExecutionMode │
│ Annotation  │ ──────────────┤
│             │ CONCURRENT or  │
│             │ SAME_THREAD    │
└─────────────┴───────────────┘
        │
        ▼
┌─────────────────────────────┐
│ Test Methods Execution Flow  │
├─────────────┬───────────────┤
│ SAME_THREAD │ Run tests one │
│             │ after another │
├─────────────┼───────────────┤
│ CONCURRENT  │ Run tests at  │
│             │ the same time │
└─────────────┴───────────────┘

Build-Up - 6 Steps

1

Foundation

JUnit 5 Basic Test Execution

Concept: Tests run sequentially by default in JUnit 5.

In JUnit 5, when you write test methods annotated with @Test, they run one after another in the same thread. This means each test waits for the previous one to finish before starting.

Result

Tests execute in order, no overlap or concurrency.

Understanding the default sequential execution helps you appreciate why controlling concurrency is needed for faster or safer test runs.

2

Foundation

Introduction to Test Concurrency

Concept: Tests can run in parallel to save time if they don't interfere with each other.

Running tests concurrently means multiple tests execute at the same time in different threads. This can speed up the total test run but requires tests to be independent and thread-safe.

Result

Potentially faster test execution but risk of conflicts if tests share resources.

Knowing concurrency basics prepares you to control when to allow parallel test execution.

3

Intermediate

Using @Execution Annotation

🤔Before reading on: do you think @Execution can be applied only to test methods or also to test classes? Commit to your answer.

Concept: @Execution controls concurrency at class or method level with ExecutionMode values.

You can add @Execution(ExecutionMode.CONCURRENT) or @Execution(ExecutionMode.SAME_THREAD) on a test class or method. CONCURRENT means tests run in parallel threads. SAME_THREAD means tests run sequentially in the same thread. Applying at class level affects all methods inside unless overridden.

Result

JUnit runs tests according to the specified execution mode, either concurrently or sequentially.

Understanding that @Execution can be scoped to class or method level gives fine control over test concurrency.

4

Intermediate

Interaction with JUnit Parallel Execution

🤔Before reading on: does @Execution override JUnit's global parallel execution settings or work alongside them? Commit to your answer.

Concept: @Execution works with JUnit's global parallel configuration to decide actual concurrency.

JUnit 5 has a global parallel execution mode configured via junit-platform.properties or programmatically. @Execution annotation refines this by marking specific tests as concurrent or same-thread. If global parallel is off, @Execution(CONCURRENT) has no effect. If global parallel is on, @Execution(SAME_THREAD) forces sequential execution for marked tests.

Result

Test execution respects both global and local concurrency settings for flexible control.

Knowing how @Execution interacts with global settings prevents confusion about why tests run sequentially or concurrently.

5

Advanced

Best Practices for Using @Execution

🤔Before reading on: do you think marking all tests as CONCURRENT is always safe? Commit to your answer.

Concept: Use @Execution selectively to avoid flaky tests caused by shared state or resources.

Tests that modify shared data or depend on external systems should run sequentially to avoid conflicts. Use @Execution(SAME_THREAD) for these. Tests that are independent and thread-safe can be marked CONCURRENT to speed up runs. Combining both in a suite optimizes speed and reliability.

Result

Balanced test suite with faster execution and fewer flaky failures.

Understanding test dependencies and resource sharing is key to applying @Execution effectively.

6

Expert

Surprising Behavior with Nested Tests and @Execution

🤔Before reading on: do you think @Execution on a nested test class overrides the outer class's setting? Commit to your answer.

Concept: Nested test classes can have their own @Execution settings that override outer classes.

In JUnit 5, nested test classes can specify @Execution independently. This means an outer class might run tests sequentially, but an inner nested class can run tests concurrently if annotated. This allows fine-grained concurrency control but can cause unexpected execution order if not carefully managed.

Result

Nested tests execute with their own concurrency mode, potentially mixing sequential and concurrent runs.

Knowing nested @Execution overrides helps avoid surprises in complex test hierarchies.

Under the Hood

JUnit 5 uses a test engine that schedules test execution. When @Execution is present, the engine checks the ExecutionMode and assigns tests to threads accordingly. For CONCURRENT mode, tests are submitted to a thread pool allowing parallel execution. For SAME_THREAD, tests run on the main test thread sequentially. The engine respects global parallel settings and merges them with local @Execution annotations to decide final scheduling.

Why designed this way?

JUnit 5 was designed to support flexible parallelism to speed up testing while maintaining backward compatibility. The @Execution annotation provides fine-grained control without forcing global parallelism. This design balances performance gains with test reliability, allowing gradual adoption and safe concurrency.

┌───────────────────────────────┐
│         Test Engine           │
├───────────────┬───────────────┤
│ Reads @Execution Annotation   │
│ and Global Parallel Settings  │
├───────────────┴───────────────┤
│ Determines Execution Mode      │
│ ┌───────────────────────────┐ │
│ │ SAME_THREAD: Run tests     │ │
│ │ sequentially on main thread│ │
│ └───────────────────────────┘ │
│ ┌───────────────────────────┐ │
│ │ CONCURRENT: Submit tests   │ │
│ │ to thread pool for parallel│ │
│ │ execution                 │ │
│ └───────────────────────────┘ │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does @Execution(CONCURRENT) guarantee all tests run in parallel? Commit to yes or no.

Common Belief: Marking tests with @Execution(CONCURRENT) means all tests will run at the same time.

Reality: Tests run concurrently only if global parallel execution is enabled; otherwise, they run sequentially despite @Execution(CONCURRENT).

Why it matters: Assuming concurrency without enabling global parallelism leads to slower tests and confusion about test behavior.

Quick: Can @Execution be used to fix flaky tests caused by shared state? Commit to yes or no.

Common Belief: Simply adding @Execution(SAME_THREAD) to flaky tests will always fix concurrency issues.

Reality: While @Execution(SAME_THREAD) forces sequential execution, flaky tests often require deeper fixes like isolating shared state or proper synchronization.

Why it matters: Relying only on @Execution to fix flaky tests can mask underlying problems, leading to fragile test suites.

Quick: Does @Execution on a test method override the class-level @Execution? Commit to yes or no.

Common Belief: The class-level @Execution annotation always applies and cannot be overridden by methods.

Reality: Method-level @Execution annotations override class-level settings, allowing different concurrency modes within the same class.

Why it matters: Misunderstanding override rules can cause unexpected test execution order and concurrency.

Quick: Is @Execution annotation available in JUnit 4? Commit to yes or no.

Common Belief: @Execution is a standard annotation available in all JUnit versions.

Reality: @Execution is introduced in JUnit 5 and does not exist in JUnit 4.

Why it matters: Trying to use @Execution in JUnit 4 leads to compilation errors and confusion.

Expert Zone

1

Tests marked CONCURRENT still depend on the global thread pool size; too many concurrent tests can exhaust resources and slow down execution.

2

Nested test classes can have different @Execution modes, allowing mixed concurrency strategies within a single test suite.

3

@Execution does not control order of test execution; it only controls concurrency mode, so tests may run in any order when concurrent.

When NOT to use

Avoid using @Execution(CONCURRENT) for tests that share mutable state, access external systems without isolation, or depend on execution order. Instead, use @Execution(SAME_THREAD) or redesign tests for thread safety. For full control, consider JUnit's parallel execution configuration or external test orchestration tools.

Production Patterns

In real projects, teams mark stable, stateless unit tests as CONCURRENT to speed up CI pipelines, while integration or UI tests run SAME_THREAD to avoid conflicts. Nested test classes often separate fast concurrent tests from slower sequential ones. Combining @Execution with tags and conditions helps run subsets of tests with different concurrency modes.

Connections

Thread Pool Management

Builds-on

Understanding how thread pools allocate and manage threads helps grasp how @Execution(CONCURRENT) schedules tests efficiently without overwhelming system resources.

Race Conditions in Software

Opposite

Knowing race conditions explains why some tests must run sequentially with @Execution(SAME_THREAD) to avoid flaky failures caused by concurrent access to shared data.

Project Management - Task Scheduling

Similar pattern

Just like scheduling tasks in a project to run in parallel or sequence to optimize time and avoid conflicts, @Execution manages test execution order and concurrency for efficiency and safety.

Common Pitfalls

#1 Marking all tests as CONCURRENT without checking thread safety.

Wrong approach:

@Execution(ExecutionMode.CONCURRENT)
class AllTests {
@Test
void test1() { sharedList.add(1); }
@Test
void test2() { sharedList.add(2); }
}

Correct approach:

@Execution(ExecutionMode.SAME_THREAD)
class AllTests {
@Test
void test1() { sharedList.add(1); }
@Test
void test2() { sharedList.add(2); }
}

Root cause:

Misunderstanding that concurrent execution requires thread-safe tests and shared mutable state causes flaky or corrupted test results.

#2 Expecting @Execution(CONCURRENT) to work without enabling global parallel execution.

Wrong approach:

@Execution(ExecutionMode.CONCURRENT)
class MyTests {
@Test
void testA() { /*...*/ }
@Test
void testB() { /*...*/ }
}

Correct approach:

Enable global parallel execution in junit-platform.properties:
junit.jupiter.execution.parallel.enabled = true

@Execution(ExecutionMode.CONCURRENT)
class MyTests {
@Test
void testA() { /*...*/ }
@Test
void testB() { /*...*/ }
}

Root cause:

Not configuring JUnit's global parallel execution disables concurrency despite @Execution annotations.

#3 Applying @Execution only at class level when some methods need different concurrency modes.

Wrong approach:

@Execution(ExecutionMode.CONCURRENT)
class MixedTests {
@Test
void safeTest() { /* thread-safe */ }
@Test
void unsafeTest() { /* modifies shared state */ }
}

Correct approach:

@Execution(ExecutionMode.CONCURRENT)
class MixedTests {
@Test
void safeTest() { /* thread-safe */ }

@Execution(ExecutionMode.SAME_THREAD)
@Test
void unsafeTest() { /* modifies shared state */ }
}

Root cause:

Assuming class-level @Execution applies perfectly to all methods ignores method-level override capability and test safety differences.

Key Takeaways

@Execution annotation controls whether JUnit 5 tests run sequentially or concurrently to balance speed and safety.

It can be applied at class or method level, with method-level annotations overriding class-level settings.

@Execution works together with JUnit's global parallel execution configuration to determine actual concurrency behavior.

Using @Execution without understanding test thread safety can cause flaky tests or corrupted results.

Advanced use includes mixing concurrency modes in nested test classes and optimizing CI test suites.