A hands-on Java testing workshop with runnable examples using TestNG 7.
Learn TestNG from scratch, explore advanced features, and compare TestNG with JUnit. Includes Maven and Gradle support, step-by-step learning paths, and practical examples for articles, workshops, tech talks, and self-study.
Originally created as 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:
- π§ͺ JUnit Workshop β companion JUnit 6 examples to compare side-by-side with this repo
- π Selenium Example β real-world Selenium WebDriver framework built on top of TestNG
- Why this repository?
- Who Is This For?
- Quick Start
- Prerequisites
- Project Structure
- Feature Map
- Beginner Learning Path
- Advanced Learning Path
- Command Examples
- Supported Versions
- CI / CD
- AI Assistant Support
- Additional Resources
- Useful Links
- Found it useful?
- License
TestNG is more than @Test, assertions, and @DataProvider.
This project covers fundamental and advanced TestNG 7 features with practical, runnable Java examples you can clone, execute, and adapt to your own projects.
Use this repository if you want to:
- learn TestNG from scratch with a structured, step-by-step learning path
- explore runnable examples that demonstrate TestNG features in practice
- master advanced features β listeners, retry strategies, parallel execution, groups, dependencies, and data-driven testing
- study automated testing patterns in Java β soft assertions, conditional execution, parameterized tests, and more
- understand test and suite orchestration β lifecycle annotations (
@BeforeSuite,@BeforeTest,@BeforeClass), XML suites, listeners, and execution hooks - work with Maven and Gradle β run the same test examples using either build tool
- compare TestNG and JUnit patterns and idioms side-by-side with the companion JUnit Workshop
- use it as material for workshops, tech talks, onboarding sessions, and self-study
| Audience | What you will get |
|---|---|
| QA engineers new to TestNG | A guided tour of every major feature with runnable examples |
| Java developers migrating from JUnit 4 / JUnit 5+ | Side-by-side comparison of patterns and idioms |
| Senior / lead engineers | Deep-dives into listeners, retry strategies, parallel execution, and groups |
| Workshop facilitators | A ready-made project you can hand to attendees |
This checkout supports Maven and Gradle independently, using the same
src/main/java, src/test/java, and src/test/resources directories.
git clone https://github.com/a-oleynik/testng-workshop.git
cd testng-workshop
# Maven
./mvnw clean test
# Gradle
./gradlew clean testOn Windows PowerShell, use .\mvnw.cmd clean test or .\gradlew.bat clean test.
Locally installed tools also work: mvn clean test or gradle clean test.
Import pom.xml for Maven or settings.gradle / build.gradle for Gradle.
In IntelliJ IDEA, choose one build model for the current IDE project when both
are detected, as in the companion JUnit Workshop.
π‘ Need help setting up your environment?
Check the comprehensive Java, Maven & Gradle Setup Guide (Windows, macOS, Ubuntu) covering JDK installation,JAVA_HOMEconfiguration, build tools setup, and troubleshooting.
| Tool | Minimum version | Notes |
|---|---|---|
| JDK | 21 LTS | |
| Maven | 3.9+ (optional but recommended) | Not required if using the included Maven Wrapper (mvnw) |
| Gradle | 9.6.0 (optional) | Not required if using the included Gradle Wrapper (gradlew) |
| Git | 2.x+ (optional) | For cloning and managing repository revisions |
| IDE | Any (IntelliJ IDEA recommended) | Lombok plugin required for IDE support |
| Lombok plugin | Latest | IntelliJ: Settings β Plugins β Lombok |
π‘ Maven and Gradle Wrappers included β no local build-tool installation is required. Each wrapper downloads its pinned version on first run (internet access required): Maven 3.9.12 or Gradle 9.6.0. Both builds require JDK 21 on
PATH/JAVA_HOME.# Linux / macOS (or Git Bash on Windows) ./mvnw clean test ./gradlew clean test # Windows PowerShell .\mvnw.cmd clean test .\gradlew.bat clean test
The tree shows the current checkout, with Java files grouped by package. Generated directories are ignored by Git; their contents depend on the build commands you run. The Feature Map lists the test classes for each topic.
.github/
βββ workflows/
β βββ maven.yml # GitHub Actions CI β all tests and optional group selection
βββ copilot-instructions.md # GitHub Copilot workspace instructions
.gradle/ # Generated local Gradle cache
.junie/
βββ guidelines.md # JetBrains Junie project guidelines
.mvn/
βββ wrapper/
βββ maven-wrapper.properties # Maven Wrapper configuration β Maven 3.9.12
build/ # Generated Gradle output
βββ classes/java/
β βββ main/ # Compiled shared utilities, models, and listeners
β βββ test/ # Compiled tests
βββ libs/ # Workshop utilities JAR after build
βββ reports/tests/
β βββ suiteTest/
β β βββ index.html # HTML report for the selected XML suite
β βββ test/
β βββ index.html # HTML report for ordinary test discovery
βββ resources/test/ # Copied test resources
βββ test-results/
βββ suiteTest/ # XML results for suiteTest
βββ test/ # XML results for test
gradle/
βββ wrapper/
βββ gradle-wrapper.jar # Committed Gradle Wrapper bootstrap JAR
βββ gradle-wrapper.properties # Gradle Wrapper configuration β Gradle 9.6.0
src/
βββ main/java/com/oleynik/qa/workshop/testng/
β βββ annotations/ # Custom annotations (@Retries, @DataSource)
β βββ dataproviders/ # Reusable data provider (MyDataProvider)
β βββ listeners/ # ITestListener, IInvokedMethodListener, IAnnotationTransformer (RetryTransformer)
β βββ model/ # Domain models (MyDoubleWrapper, ShoppingCart, User)
β βββ retry/ # IRetryAnalyzer implementation (RetryAnalyzer)
β βββ suites/ # ISuiteListener (MySuiteListener), IExecutionListener (MyExecutionListener)
β βββ Factorial.java # Utility class used by data-driven tests
β βββ Utils.java # Shared test utilities (e.g. waitFor)
βββ test/
βββ java/com/oleynik/qa/workshop/testng/
β βββ conditional/ # Assumptions (AssertJ assumeThat)
β βββ ddt/ # Data-driven tests (@DataProvider, CSV, external provider)
β βββ dependencies/ # Test dependencies (dependsOnMethods / dependsOnGroups)
β βββ execution/order/ # Test execution ordering (priority)
β βββ fixtures/ # Fresh / Shared Fixture; Inline / Implicit Setup
β βββ general/ # Core assertions, lifecycle, exceptions, descriptions, timeouts
β βββ group/asserts/ # Soft assertions (SoftAssertTest)
β βββ grouping/ # TestNG groups (@Test(groups = β¦))
β βββ listeners/ # Tests demonstrating listener hooks
β βββ nested/ # Inner-class test grouping
β βββ repeat/ # Repeated execution (invocationCount)
β βββ retry/ # Retry strategies (IRetryAnalyzer, IAnnotationTransformer)
β βββ suites/ # @BeforeSuite/@AfterSuite, @BeforeTest/@AfterTest, ISuiteListener, IExecutionListener
βββ resources/
βββ numbers.csv # Input / expected factorial values for CSV data providers
βββ testnested.xml # Discover nested tests by package
βββ testng1.xml # Include / exclude specific test methods
βββ testng2.xml # Run fixed classes in parallel
βββ testnggroups1.xml # Groups-of-groups
βββ testnggroups2.xml # Smoke group only
βββ testngretrylistener.xml # Register RetryTransformer globally for this suite
βββ testngsuites.xml # Suite / execution listeners and lifecycle annotations
target/ # Generated Maven output
βββ classes/ # Compiled shared utilities, models, and listeners
βββ reports/
β βββ surefire.html # Standalone surefire-report:report output
βββ site/ # Maven project website after site
βββ surefire-reports/
β βββ emailable-report.html # TestNG emailable report
β βββ index.html # TestNG HTML report after Maven test
β βββ TEST-*.xml # JUnit-compatible XML results for CI
β βββ testng-results.xml # Native TestNG results
βββ test-classes/ # Compiled tests and copied test resources
.gitattributes # Wrapper script line endings
.gitignore # Generated output, caches, and IDE exclusions
AGENTS.md # AI agent instructions and verification commands
build.gradle # Java 21, dependencies, test, suiteTest, and local publication
gradlew # Gradle Wrapper for Unix
gradlew.bat # Gradle Wrapper for Windows
LICENSE # MIT license
mvnw # Maven Wrapper for Unix
mvnw.cmd # Maven Wrapper for Windows
pom.xml # Maven dependencies, Lombok processor, and Surefire configuration
README.md # Project documentation and run commands
settings.gradle # Gradle project name
π‘ New to TestNG? Follow the Learning Path for a recommended study order.
| Package / folder | Feature demonstrated | Test class(es) |
|---|---|---|
general |
Basic assertions (assertEquals, assertTrue, assertNull, assertSame, β¦) |
AssertTest |
general |
Exception testing (expectedExceptions, expectedExceptionsMessageRegExp) |
ExceptionTest |
general |
Test lifecycle (@BeforeSuite, @AfterSuite, @BeforeClass, @AfterClass, @BeforeTest, @AfterTest, @BeforeMethod, @AfterMethod) |
LifecycleTest |
fixtures |
Fresh Fixture, Shared Fixture, Inline Setup, and Implicit Setup | InlineFixtureTest, ImplicitFixtureTest, SharedFixtureTest |
general |
Hamcrest matchers | HamcrestTest |
general |
Timeouts (timeOut attribute on @Test) |
TimeoutTest |
general |
Disabling & skipping tests (enabled = false, SkipException) |
DisabledTest |
general |
Test descriptions (description attribute on @Test) |
DescriptionTest |
group/asserts |
Soft assertions (SoftAssert) |
SoftAssertTest |
conditional |
Assumptions via AssertJ (assumeThat) per method |
AssumeTest |
conditional |
Assumptions in @BeforeClass to skip entire class |
AssumeBeforeClassTest |
ddt |
Static inline @DataProvider |
StaticDataProviderTest |
ddt |
Dynamic CSV-file @DataProvider (Iterator-based) |
DynamicDataProviderTest |
ddt |
External @DataProvider class (dataProviderClass) |
OuterDataProviderTest |
nested |
Inner test classes grouped under a parent class | NestedTest |
grouping |
Groups (@Test(groups = β¦)), @BeforeGroups, @AfterGroups |
GroupTest |
dependencies |
Method & group dependencies (dependsOnMethods, dependsOnGroups) |
DependenciesTest |
execution/order |
Test execution ordering via priority attribute |
ExecutionOrderTest |
suites |
Suite lifecycle annotations (@BeforeSuite, @AfterSuite) |
SuiteAnnotationsTest |
suites |
Test-block lifecycle annotations (@BeforeTest, @AfterTest) |
TestAnnotationsTest |
suites |
ISuiteListener β suite-scoped setup/teardown via listener |
SuiteListenerTest |
suites |
IExecutionListener β execution-wide lifecycle (registrable via @Listeners, XML, or ServiceLoader) |
ExecutionListenerTest |
listeners |
ITestListener β observe test start, success, failure, skip |
TestListenerTest |
listeners |
IInvokedMethodListener β intercept before/after every method invocation |
MethodListenerTest |
listeners |
TestListenerAdapter β extend the adapter and override only the callbacks you need |
TestListenerTest |
retry |
Retry with IRetryAnalyzer + custom @Retries annotation |
RetryTest |
retry |
Retry with IAnnotationTransformer (RetryTransformer) applied globally via XML |
RetryTransformerTest |
repeat |
Repeated execution (invocationCount attribute on @Test) |
RepeatedTest |
Work through these topics in order; each builds on the previous one.
AssertTest
Learn assertEquals, assertTrue, assertNull, assertSame, assertNotSame, and fail.
Understand the scopes of TestNG configuration methods: @BeforeSuite β @BeforeTest β @BeforeClass β @BeforeMethod, with the corresponding @After* callbacks. @BeforeTest belongs to an XML <test> block; @BeforeMethod runs before each test method.
This example logs lifecycle callbacks. The fixture examples in the next topic show the state those callbacks can prepare. LifecycleTest runs its test methods in one thread to make the trace easier to follow; the rest of the workshop keeps its parallel defaults.
./mvnw clean test -Dtest=LifecycleTest
./gradlew clean test --tests "LifecycleTest"InlineFixtureTest,
ImplicitFixtureTest,
SharedFixtureTest
A fixture is the prepared state, data, objects, or resources needed by a test.
Lifecycle callbacks such as @BeforeMethod prepare it; the callbacks are the setup mechanism.
The examples use the same small ShoppingCart and cart scenarios as the companion JUnit Workshop. Prices and totals use integer minor currency units.
| Concept | What it describes | Example |
|---|---|---|
| Fresh Fixture | State created separately for each test. | Every test gets a new empty ShoppingCart. |
| Shared Fixture | A fixture, or part of it, reused by several tests. | SharedFixtureTest creates one immutable price catalog per test-class instance in @BeforeClass. |
| Inline Setup | Preparation written directly inside the test method. | InlineFixtureTest constructs the cart in each test. |
| Implicit Setup | Common preparation invoked automatically before each test. | ImplicitFixtureTest and SharedFixtureTest create their carts in @BeforeMethod. |
Fresh/Shared Fixture describes reuse; Inline/Implicit Setup describes how preparation is invoked. The first two classes compare the same cart scenarios with different setup locations. Their scenario-specific prices and quantities stay visible in each test. All three examples assert an initial cart total of zero and then expected totals of 400 or 450. The shared example combines reusable read-only reference data with a fresh mutable cart, so tests do not depend on each other's changes or execution order.
TestNG reuses a test-class instance across its methods. With the workshop's parallel=methods default, replacing a cart field in @BeforeMethod needs isolation.
ImplicitFixtureTest and SharedFixtureTest use class-level @Test(singleThreaded = true)
so their test methods run in one thread; @BeforeMethod still creates a fresh cart for each test.
The global methods/3 configuration is unchanged.
These in-memory fixtures need no explicit teardown; external resources may need cleanup in
the matching @After* callback.
./mvnw clean test -Dtest=InlineFixtureTest,ImplicitFixtureTest,SharedFixtureTest
./gradlew clean test --tests "InlineFixtureTest" --tests "ImplicitFixtureTest" --tests "SharedFixtureTest"ExceptionTest
Use expectedExceptions and expectedExceptionsMessageRegExp on @Test to assert thrown exceptions.
DisabledTest
Disable tests with @Test(enabled = false) or skip them dynamically by throwing SkipException.
DescriptionTest
Add human-readable descriptions to tests with @Test(description = "β¦") for better report output.
SoftAssertTest
Collect all assertion failures with SoftAssert before reporting β no early bail-out.
AssumeTest
Skip tests dynamically when preconditions aren't met using AssertJ's assumeThat.
StaticDataProviderTest
Drive one test method with multiple data rows using an inline @DataProvider.
GroupTest
Mark tests as Smoke or Regression and run subsets from the command line or via XML suites.
SuiteAnnotationsTest, TestAnnotationsTest
See @BeforeSuite / @AfterSuite run once around the entire suite, and @BeforeTest / @AfterTest run once per <test> block in a testng.xml file. Having seen XML suites in step 10, the distinction between @BeforeTest and @BeforeClass now makes full sense β and this topic bridges directly into the Advanced Learning Path section.
./mvnw clean surefire-report:report
./gradlew clean test
# or
./mvnw clean site
./gradlew clean testMaven Surefire Report output:
target/reports/surefire.htmlforsurefire-report:report(current standalone-plugin default). Maven Site usestarget/site/; Gradle HTML test reports usebuild/reports/tests/test/index.html.
For this test-only project, ./gradlew clean test provides the test-report equivalent
of either Maven command above. It does not generate the Maven project website.
Run all workshop tests:
./mvnw clean test
./gradlew clean testThese topics assume familiarity with TestNG basics.
SuiteAnnotationsTest, TestAnnotationsTest, SuiteListenerTest, ExecutionListenerTest β suites/ package
TestNG provides callbacks at suite scope and at the enclosing execution scope:
| Strategy | Class | When to use |
|---|---|---|
@BeforeSuite / @AfterSuite |
SuiteAnnotationsTest |
Simplest option; lives inside a test class |
ISuiteListener |
SuiteListenerTest + MySuiteListener |
Infrastructure code outside the test hierarchy; fires per suite |
IExecutionListener |
ExecutionListenerTest + MyExecutionListener |
Fires once per TestNG execution, across all its suites; registrable via @Listeners, XML, or ServiceLoader |
Lifecycle callback order:
IExecutionListener.onExecutionStart() β once per TestNG execution
ISuiteListener.onStart(suite) β once per suite
@BeforeSuite β annotation-based, once per suite
@BeforeTest β once per <test> block in testng.xml
@BeforeClass β once per test class
@BeforeMethod / @Test / @AfterMethod
@AfterClass
@AfterTest
@AfterSuite
ISuiteListener.onFinish(suite)
IExecutionListener.onExecutionFinish()
JUnit comparison: JUnit Platform Suite API provides
@BeforeSuite/@AfterSuitefor a suite entry point. Jupiter's@BeforeAll/@AfterAllandBeforeAllCallback/AfterAllCallbackhave class-level scope; placing them in a base class or registering an extension through ServiceLoader does not make them suite-wide.
@BeforeTest / @AfterTest (TestAnnotationsTest) fire once per <test> XML element β coarser than @BeforeClass but finer than @BeforeSuite. They are TestNG-specific and have no direct JUnit 5 counterpart.
IExecutionListener extends ITestNGListener, so it can be registered via @Listeners on a test class, in the <listeners> block of a testng.xml, or auto-detected via ServiceLoader. The "XML only, @Listeners is ignored" restriction applies to IAnnotationTransformer, not to IExecutionListener. This Workshop uses XML registration for MyExecutionListener so it reliably wraps every suite in the demo run:
<suite name="SuitesDemo" parallel="none">
<listeners>
<listener class-name="com.oleynik.qa.workshop.testng.suites.MySuiteListener"/>
<listener class-name="com.oleynik.qa.workshop.testng.suites.MyExecutionListener"/>
</listeners>
<!-- ... -->
</suite>Run the full suites demo:
./mvnw clean test -Dsurefire.suiteXmlFiles=src/test/resources/testngsuites.xml
./gradlew clean suiteTest -Psuite=src/test/resources/testngsuites.xmlGroupTest β grouping/ package
Assign tests to named groups. Use @BeforeGroups and @AfterGroups for group-scoped setup/teardown.
Run groups from the command line:
./mvnw clean test -Dgroups=Regression,Smoke
./gradlew clean test -PincludeGroups=Regression,SmokeOr target a specific XML suite that filters by group:
# Run only Smoke tests via XML
./mvnw clean test -Dsurefire.suiteXmlFiles=src/test/resources/testnggroups2.xml
./gradlew clean suiteTest -Psuite=src/test/resources/testnggroups2.xml
# Run groups-of-groups (Smoke + Regression + Fail) via XML
./mvnw clean test -Dsurefire.suiteXmlFiles=src/test/resources/testnggroups1.xml
./gradlew clean suiteTest -Psuite=src/test/resources/testnggroups1.xmlDependenciesTest β dependencies/ package
Chain tests so that a downstream test is skipped (not failed) when its upstream dependency fails, using dependsOnMethods or dependsOnGroups.
DynamicDataProviderTest, OuterDataProviderTest β ddt/ package
- Load test data lazily from CSV files via an
Iterator-based@DataProvider. Test data lives insrc/test/resources/numbers.csv. - Separate data-provider logic into a dedicated
MyDataProviderclass and reference it withdataProviderClass. - Use the custom
@DataSource(path = "β¦")annotation to bind a CSV file path to a test method at runtime.
HamcrestTest
Write expressive assertions with assertThat, equalTo, is, closeTo, bothβ¦and, and more.
NestedTest β nested/ package
Group related scenarios (Multiply, Divide, Add) as public inner classes inside a parent class. Run them via testnested.xml:
./mvnw clean test -Dsurefire.suiteXmlFiles=src/test/resources/testnested.xml
./gradlew clean suiteTest -Psuite=src/test/resources/testnested.xmlExecutionOrderTest β execution/order/ package
Control method execution order with the priority attribute on @Test (lower value = earlier execution). Methods without a priority run before prioritized ones.
TestListenerTest, MethodListenerTest β listeners/ package
ITestListener(MyTestListener) β react to test start, success, failure, and skip events. Ideal for screenshot capture on failure.IInvokedMethodListener(MyMethodListener) β intercept every method invocation (including@Before*/@After*).TestListenerAdapter(MyExtendedTestListener) β extend the adapter and override only the callbacks you need.
Attach listeners declaratively with@Listeners(value = MyTestListener.class)or globally via atestng.xml<listeners>block.
RetryTest β IRetryAnalyzer + custom @Retries(limit = N) annotation applied per test method
RetryTransformerTest β IAnnotationTransformer (RetryTransformer) injects RetryAnalyzer globally for every test in the suite without touching test source code
Run the transformer-based retry suite:
./mvnw clean test -Dsurefire.suiteXmlFiles=src/test/resources/testngretrylistener.xml
./gradlew clean suiteTest -Psuite=src/test/resources/testngretrylistener.xmlConfigured globally in pom.xml via Surefire:
<parallel>methods</parallel>
<threadCount>3</threadCount>Tests run concurrently by default. Fine-tune parallelism per suite with parallel="classes" or parallel="tests" and a custom thread-count in any testng.xml. For example, testng2.xml runs a fixed set of classes in parallel with thread-count="2":
./mvnw clean test -Dsurefire.suiteXmlFiles=src/test/resources/testng2.xml
./gradlew clean suiteTest -Psuite=src/test/resources/testng2.xmlGradle uses native TestNG integration with the same method-level parallelism:
test {
maxParallelForks = 1
useTestNG {
parallel = 'methods'
threadCount = 3
}
}maxParallelForks = 1 allows one Gradle test worker JVM. TestNG's threadCount = 3
controls the method threads inside that JVM. Gradle's --max-workers limits
Gradle task workers separately; it does not set the TestNG thread count.
All suite XML files live in src/test/resources/. They demonstrate:
| File | What it shows |
|---|---|
testng1.xml |
Include / exclude specific test methods per class |
testng2.xml |
Run a fixed set of classes in parallel |
testnggroups1.xml |
Groups-of-groups β combine named groups under one alias |
testnggroups2.xml |
Include only the Smoke group |
testngretrylistener.xml |
Register RetryTransformer listener globally |
testnested.xml |
Run all tests from a package (including inner classes) |
testngsuites.xml |
ISuiteListener + IExecutionListener + suite lifecycle annotations |
Run any suite directly:
./mvnw clean test -Dsurefire.suiteXmlFiles=src/test/resources/testng1.xml
./gradlew clean suiteTest -Psuite=src/test/resources/testng1.xmlsuiteTest and -Psuite are implemented in this project's build.gradle;
-Psuite is not a built-in Gradle option. The path is relative to the repository
root (an absolute path also works). A missing parameter, missing file, or directory
fails the task instead of falling back to ordinary test discovery.
This task uses the test runtime classpath and passes the selected XML to native
TestNG. XML controls classes/packages, method includes/excludes, listeners,
preserve-order, parallel, and thread-count. The methods/3 defaults of the
ordinary test task are not applied to suiteTest: testngsuites.xml stays
sequential with parallel="none", while testng2.xml uses classes and two threads.
Without group parameters, XML group selections are also preserved. The project
parameters -PincludeGroups and -PexcludeGroups explicitly override the respective
XML group selections when supplied; omit them to run the suite as authored.
See TestNGOptions.
The tasks write separate results:
| Task | HTML report | XML results |
|---|---|---|
test |
build/reports/tests/test/index.html |
build/test-results/test/ |
suiteTest |
build/reports/tests/suiteTest/index.html |
build/test-results/suiteTest/ |
Run ./gradlew suiteTest -Psuite=src/test/resources/testngsuites.xml without
clean to retain an existing ordinary test report. Changing -Psuite or the
selected XML file invalidates the suite task's up-to-date result.
# Maven
./mvnw clean test
# Gradle (Windows PowerShell: .\gradlew.bat clean test)
./gradlew clean testReports are written to:
- Surefire report:
target/surefire-reports/index.html- TestNG emailable report:
target/surefire-reports/emailable-report.html
Gradle writes its HTML report to build/reports/tests/test/index.html and XML
results to build/test-results/test/. Maven outputs to target/; Gradle outputs
to build/. Each build compiles and tests the shared sources independently.
Gradle's test task can be up-to-date on repeat runs; use clean test or
test --rerun-tasks to force execution. The paired commands below show both build tools.
The examples use Bash syntax (Linux/macOS or Git Bash on Windows). Simple
-D... / -P... arguments do not need quotes in Bash; quote wildcard patterns
and paths containing spaces so the shell passes them as one literal argument.
In PowerShell, use .\mvnw.cmd and .\gradlew.bat, and quote complete property
arguments, especially dotted property names and XML paths:
.\mvnw.cmd clean test "-Dtest=AssertTest"
.\gradlew.bat clean test --tests "AssertTest"
.\mvnw.cmd clean test "-Dsurefire.suiteXmlFiles=src/test/resources/testng1.xml"
.\gradlew.bat clean suiteTest "-Psuite=src/test/resources/testng1.xml"./mvnw clean test -Dtest=AssertTest
./gradlew clean test --tests "AssertTest"./mvnw clean test -Dtest=AssertTest#assert_equals_multiplication_test
./gradlew clean test --tests "AssertTest.assert_equals_multiplication_test"./mvnw clean test -Dtest=AssertTest,HamcrestTest
./gradlew clean test --tests "AssertTest" --tests "HamcrestTest"./mvnw clean test "-Dtest=AssertTest#assert_equals*"
./gradlew clean test --tests "AssertTest.assert_equals*"./mvnw clean test "-Dtest=AssertTest#assert_equals*+assert_boolean*"
./gradlew clean test --tests "AssertTest.assert_equals*" --tests "AssertTest.assert_boolean*"./mvnw clean test -Dgroups=Regression,Smoke
./gradlew clean test -PincludeGroups=Regression,SmokeUse Smoke or Regression alone to select a single group. These case-sensitive,
comma-separated project parameters are connected to TestNG's includeGroups
and excludeGroups; Gradle does not interpret Maven's -Dgroups automatically.
Whitespace around each group name is ignored. For example, run Regression
methods except those also assigned to Smoke:
./mvnw clean test -Dgroups=Regression -DexcludedGroups=Smoke
./gradlew clean test -PincludeGroups=Regression -PexcludeGroups=Smoke./mvnw clean test -Dsurefire.suiteXmlFiles=src/test/resources/testng1.xml
./gradlew clean suiteTest -Psuite=src/test/resources/testng1.xml./mvnw clean install
./gradlew clean build publishToMavenLocalThe Gradle maven-publish plugin publishes the Java component (JAR and POM) to
the local Maven repository with the same com.oleynik.qa.workshop:testng-examples:2.0-SNAPSHOT
coordinates as Maven. build runs verification before local publication.
./mvnw clean install -DskipTests
./gradlew clean build testClasses publishToMavenLocal -x testtestClasses still compiles the tests, matching Maven's -DskipTests behavior.
Neither command executes the tests.
./mvnw clean surefire-report:report
./gradlew clean testSurefire report is written to:
- Surefire report:
target/reports/surefire.html
./mvnw clean test -X
./gradlew clean test --debug| Library | Version used |
|---|---|
| TestNG | 7.12.0 |
| AssertJ | 3.27.7 |
| Hamcrest | 3.0 |
| Lombok | 1.18.48 |
| OpenCSV | 5.12.0 |
| SLF4J | 2.0.18 |
| Maven Surefire Plugin | 3.5.6 |
| Gradle Wrapper | 9.6.0 |
Java --release |
21 |
This project uses GitHub Actions with a manually triggered workflow.
Triggered manually from Actions β Run workflow on GitHub.
| Input | Required | Description |
|---|---|---|
groups |
No | Group filter for the by-group job (e.g. Smoke, Regression). Leave empty to skip that job. |
| Job | Name | Runs when | Maven command | Equivalent Gradle command |
|---|---|---|---|---|
regression |
Regression β all tests | Always | ./mvnw -B clean test |
./gradlew --no-daemon clean test |
by-group |
By group β {groups} |
Only when groups input is filled in |
./mvnw -B clean test -Dgroups={groups} |
./gradlew --no-daemon clean test -PincludeGroups={groups} |
The current workflow executes Maven. The Gradle column gives the equivalent local/CI commands; it does not change the workflow or its artifact paths.
Each job uploads two artifacts after completion β including on failure (if: always()):
| Artifact | Source path | Contents |
|---|---|---|
testng-reports / testng-reports-{groups} |
target/surefire-reports/ |
Full HTML report β open index.html in a browser |
junit-xml-results / junit-xml-results-{groups} |
target/surefire-reports/ |
Raw JUnit XML files β compatible with CI dashboards and report parsers |
- Go to the Actions tab on GitHub
- Select Java CI with Maven in the left panel
- Click Run workflow
- Optionally fill in the
groupsfield (e.g.Smoke) to also run the by-group job - Click Run workflow
- Click the completed workflow run
- Scroll to Artifacts β download
testng-reports(HTML) orjunit-xml-results(XML) - Open
index.html(from the TestNG report) in a browser
# All tests
./mvnw clean test
./gradlew clean test
# By group
./mvnw clean test -Dgroups=Smoke
./gradlew clean test -PincludeGroups=Smoke
./mvnw clean test -Dgroups=Regression
./gradlew clean test -PincludeGroups=RegressionThis project ships configuration files for AI coding assistants so they have full context about the tech stack, package layout, coding conventions, and TestNG-specific rules.
| Assistant | File | Description |
|---|---|---|
| GitHub Copilot (chat / completions / agent mode) | .github/copilot-instructions.md |
Always-on workspace instructions β project overview, conventions, key patterns, task recipes, what NOT to do |
| JetBrains Junie | .junie/guidelines.md |
Project guidelines β full source layout, naming rules, threading constraints, learning path |
| OpenAI Codex / Claude Code / Gemini CLI | AGENTS.md |
Agentic guidance β build & verify commands, feature index, common patterns, important rules |
All files cover:
- Full tech stack and versions
src/mainandsrc/testpackage breakdown with class inventory- Naming conventions (
snake_casetest methods,PascalCaseclasses) - TestNG-specific rules (e.g.
IExecutionListenercan be registered via@Listeners, XML, orServiceLoaderβ unlikeIAnnotationTransformer, which requires XML) - Thread-safety constraints (
parallel=methods,threadCount=3enabled by default) - All run commands including Maven Wrapper
- TestNG Documentation
- TestNG GitHub
- AssertJ Documentation
- Hamcrest Tutorial
- Lombok Features
- OpenCSV Documentation
- Maven Surefire Plugin
- Maven Surefire Report Plugin
- Maven Wrapper β run Maven without a local installation
- Gradle Java Plugin
- Gradle Wrapper β run Gradle without a local installation
- JUnit Workshop β companion JUnit 6 examples (there are also branches with JUnit 5 & 4)
- Selenium Example β real-world Selenium framework using TestNG
- testng.xml Is Legacy. Hereβs What Modern TestNG Suites Should Look Like β article on modern TestNG suite configuration
- Maven Surefire 3.6.0: What Happened to TestNG and testng.xml β article about updates in Maven Surefire / Failsafe 3.6.0 connected with TestNG
- Maven Wrapper: Why You Need It and How to Use It β article about Maven Wrapper and how to use it in your project
- How to Install and Set Up Java on Windows, macOS, and Ubuntu: JDK, Maven, and Gradle β comprehensive setup guide for JDK, Maven, and Gradle on all major OS
- Java Download
- Maven Download
- TestNG Releases
- JUnit 6 Released β Clean-Up, Modernization & Minimal Disruption
- What Is a Test Fixture in JUnit, and Why Is @BeforeEach Not a Fixture?
- Lombok Download
- IntelliJ Lombok Plugin
If you found useful examples or information in this repository, please give it a β
Your support helps the project reach more Java and QA engineers.
This project is licensed under the MIT License β see the LICENSE file for details.