JUnit 6 Workshop Examples

Companion code for the IT Talk "JUnit 6 vs TestNG 7". Previous edition: TestNG vs. JUnit 4 slides · TestNG vs. JUnit 4 webinar

Related projects:

• 🧪 TestNG Workshop — companion TestNG examples to compare side-by-side with this repo
• 🌐 Selenium Example (JUnit 6 branch) — real-world Selenium WebDriver framework built on top of JUnit 6

---

📋 Table of Contents

• Who Is This For?
• Prerequisites
• Quick Start
• Supported Versions
• Feature Map
• Learning Path — Beginners
• Advanced Topics — Path for Senior Engineers
• Command Examples
• Project Structure
• License
• Additional Resources
• Useful Links

---

👥 Who Is This For?

Audience	What you will get
QA engineers new to JUnit 6	A guided tour of every major feature with runnable examples
Java developers migrating from JUnit 4 / TestNG	Side-by-side comparison of patterns and idioms
Senior / lead engineers	Deep-dives into extensions, retry strategies, parallel execution, and tagging
Workshop facilitators	A ready-made project you can hand to attendees

---

📦 Prerequisites

Tool	Minimum version	Notes
JDK	21 LTS
Maven	3.9+
IDE	Any (IntelliJ IDEA recommended)	Lombok plugin required for IDE support
Lombok plugin	Latest	IntelliJ: Settings → Plugins → Lombok

---

🚀 Quick Start

git clone https://github.com/a-oleynik/junit-workshop.git
cd junit-workshop
mvn clean test

---

🧩 Supported Versions

Library	Version used
JUnit Jupiter (JUnit 5)	6.1.0-M1
JUnit Platform	6.1.0-M1
JUnit Pioneer	2.3.0
TNG DataProvider for JUnit 5	2.12
AssertJ	3.27.7
Hamcrest	3.0
Lombok	1.18.42
Rerunner Jupiter	2.1.6
OpenCSV	5.12.0
Java source / target	21

---

🌍 Feature Map

Package / folder	Feature demonstrated	Test class(es)
general	Basic assertions (assertEquals, assertTrue, assertNull, …)	AssertTest
general	Exception testing (assertThrows)	ExceptionTest
general	Test fixtures (@BeforeEach, @AfterEach, @BeforeAll, @AfterAll)	FixturesTest
general	Hamcrest matchers	HamcrestTest
general	Timeouts (@Timeout)	TimeoutTest
general	Disabling tests (@Disabled)	DisabledTest
general	Display names & name generators	DisplayNameTest, DisplayNameGenerationTest
group/asserts	Grouped / soft assertions (assertAll)	AssertAllTest
group/asserts	AssertJ soft assertions	SoftAssertionsAssertJTest, SoftAssertionsAssertJBDDTest
group/asserts	JUnit 5 soft assert pattern	SoftAssertTest
conditional	Assumptions (assumeTrue, assumeThat)	AssumptionsTest, AssumptionsBeforeAllTest
ddt	Parameterized tests — @MethodSource	ParameterizationTest
ddt	Parameterized tests — @ValueSource / @CsvSource	ValueSourceTest
ddt	CSV file data source	CSVParameterizationTest
ddt	TNG DataProvider integration	DataProviderTest
ddt	JUnit Pioneer Cartesian product	PioneerCartesianProductTest
nested	@Nested test classes	NestedTest
grouping	Tagging with @Tag and custom tag annotations	TagsTest
execution/order	Test execution ordering (@TestMethodOrder)	ExecutionOrderWithTest
extensions	Custom Extension (@RegisterExtension)	DBResourceExtensionTest
extensions	TestWatcher extension	TestWatcherExtensionTest
retry	Retry with JUnit Pioneer (@RetryingTest)	RetryPioneerTest
retry	Retry with Rerunner Jupiter	RetryRerunnerTest
repeat	@RepeatedTest	RetryRepeatedTest

---

🌱 Learning Path — Beginners

Work through these topics in order; each builds on the previous one.

1. Basic assertions → AssertTest
   Learn assertEquals, assertTrue, assertNull, assertAll, and fail.

2. Test lifecycle → FixturesTest
   Understand @BeforeEach, @AfterEach, @BeforeAll, @AfterAll.

3. Exception testing → ExceptionTest
   Use assertThrows to assert that code throws the right exception.

4. Disabling & display names → DisabledTest, DisplayNameTest
   Skip tests cleanly and make reports human-readable.

5. Hamcrest matchers → HamcrestTest
   Write expressive assertions with assertThat.

6. Grouped assertions → AssertAllTest
   Use assertAll so multiple failures are reported together.

7. Assumptions → AssumptionsTest
   Skip tests dynamically when preconditions aren't met.

8. Parameterized tests → ValueSourceTest, ParameterizationTest
   Drive one test method with many data rows.

9. Nested tests → NestedTest
   Organise related scenarios using inner @Nested classes.

10. Tagging → TagsTest
    Mark tests as Smoke or Regression and run subsets from the command line.

Run the whole beginner suite:

mvn clean test

---

🎯 "Advanced Topics" — Path for Senior Engineers

These topics assume familiarity with JUnit 5+ basics.

1. Custom Tag Annotations

TagsTest → tags/ package
Compose @Tag into reusable meta-annotations (@Smoke, @Regression).

2. CSV & External Data Providers

CSVParameterizationTest, DataProviderTest, ParameterizationTest
Load test data from CSV files and external ArgumentsProvider / @MethodSource classes.

3. Cartesian Product (JUnit Pioneer)

PioneerCartesianProductTest
Generate all combinations of parameter sets automatically.

4. Soft Assertions (AssertJ)

SoftAssertionsAssertJTest, SoftAssertionsAssertJBDDTest
Collect all assertion failures before reporting — no early bail-out.

5. Custom JUnit 5 Extensions

DBResourceExtensionTest, TestWatcherExtensionTest
Implement BeforeAllCallback, AfterAllCallback, and TestWatcher to manage external resources and observe test outcomes.

6. Test Execution Order

ExecutionOrderWithTest
Control method execution order with @TestMethodOrder and @Order.

7. Retry Strategies

RetryPioneerTest — @RetryingTest(maxAttempts, minSuccess) via JUnit Pioneer
RetryRerunnerTest — Rerunner Jupiter integration
RetryRepeatedTest — JUnit 5 native @RepeatedTest

8. Parallel Execution

Configured globally in pom.xml via Surefire:

junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=concurrent

Tests run concurrently by default. Use @ResourceLock or @Execution(SAME_THREAD) to serialise where needed.

9. Maven Profiles (Tag-based filtering)

# Run only Smoke tests
mvn clean test -P SmokeTests

# Run only Regression tests
mvn clean test -P RegressionTests

10. Surefire HTML Report Generation

mvn clean site
# or
mvn clean surefire-report:report

---

💻 Command Examples

Run all tests

mvn clean test

Run a single test class

mvn clean test -Dtest=AssertTest

Run a single test method

mvn clean test -Dtest=AssertTest#assert_equals_multiplication_test

Run multiple test classes

mvn clean test -Dtest=AssertTest,HamcrestTest

Run test methods matching a pattern

mvn clean test -Dtest=AssertTest#assert_equals*

Run test methods matching multiple patterns

mvn clean test -Dtest=AssertTest#assert_equals*+assert_boolean*

Rerun failing tests automatically (e.g. flaky tests)

mvn clean test -Dsurefire.rerunFailingTestsCount=2

Run tests by tag

mvn clean test -Dgroups=Regression,Smoke

Compile, test, package, and install to local repo

mvn clean install

Skip tests (compile + package + install to local repo without running tests)

mvn clean install -DskipTests

Generate Surefire HTML report (quick)

mvn clean surefire-report:report

Generate full Maven site with Surefire report

mvn clean site

Reports are written to target/site/surefire-report.html

Enable full debug logging for troubleshooting

mvn clean test -X

---

📁 Project Structure

src/
├── main/java/com/oleynik/qa/workshop/junit/
│   └── model/          # Domain model (User, MyDoubleWrapper, MyServer)
└── test/java/com/oleynik/qa/workshop/junit/
    ├── general/         # Core assertions, fixtures, exceptions, display names
    ├── group/asserts/   # Grouped / soft assertions
    ├── conditional/     # Assumptions
    ├── ddt/             # Parameterized & data-driven tests
    ├── nested/          # @Nested test classes
    ├── grouping/        # @Tag / custom tag annotations
    ├── execution/order/ # Test execution ordering
    ├── extensions/      # Custom JUnit 5 extensions
    ├── retry/           # Retry strategies (Pioneer, Rerunner)
    └── repeat/          # @RepeatedTest

---

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

📚 Additional Resources

• JUnit 6 User Guide
• JUnit Pioneer Documentation
• AssertJ Documentation
• Hamcrest Tutorial
• Lombok Features
• Maven Surefire Plugin
• Maven Surefire Report Plugin
• TestNG Workshop — companion TestNG examples
• Selenium Example — JUnit 6 branch — real-world Selenium framework using JUnit 6

---

🔗 Useful Links

• Java Download: https://www.oracle.com/java/technologies/downloads/
• Maven Download: https://maven.apache.org/download.cgi
• JUnit 6 Releases: https://github.com/junit-team/junit5/releases
• JUnit Pioneer Releases: https://github.com/junit-pioneer/junit-pioneer/releases
• Lombok Download: https://projectlombok.org/download
• IntelliJ Lombok Plugin: https://plugins.jetbrains.com/plugin/6317-lombok