0
# TestNG
1

2
TestNG is a comprehensive testing framework for Java that provides powerful testing capabilities including data-driven testing, parallel execution, test configuration through annotations, flexible test configuration through XML files, and integration with build tools and IDEs. It supports advanced features like test dependencies, parameterized tests, groups, test listeners, and reporters.
3

4
## Package Information
5

6
- **Package Name**: org.testng:testng
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.testng</groupId>
13
    <artifactId>testng</artifactId>
14
    <version>7.11.0</version>
15
    <scope>test</scope>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import org.testng.annotations.Test;
23
import org.testng.Assert;
24
import org.testng.TestNG;
25
import org.testng.annotations.DataProvider;
26
import org.testng.annotations.BeforeMethod;
27
import org.testng.annotations.AfterMethod;
28
```
29

30
## Basic Usage
31

32
```java
33
import org.testng.annotations.Test;
34
import org.testng.Assert;
35
import org.testng.annotations.BeforeMethod;
36
import org.testng.annotations.DataProvider;
37

38
public class BasicTestExample {
39
    
40
    @BeforeMethod
41
    public void setUp() {
42
        // Setup code before each test method
43
        System.out.println("Setting up test");
44
    }
45
    
46
    @Test
47
    public void testSimpleAssertion() {
48
        String expected = "Hello TestNG";
49
        String actual = "Hello TestNG";
50
        Assert.assertEquals(actual, expected);
51
    }
52
    
53
    @Test(groups = "unit")
54
    public void testWithGroup() {
55
        Assert.assertTrue(true, "This should pass");
56
    }
57
    
58
    @Test(dataProvider = "testData")
59
    public void testWithDataProvider(String input, int expected) {
60
        Assert.assertEquals(input.length(), expected);
61
    }
62
    
63
    @DataProvider(name = "testData")
64
    public Object[][] createTestData() {
65
        return new Object[][] {
66
            {"Hello", 5},
67
            {"TestNG", 6},
68
            {"Framework", 9}
69
        };
70
    }
71
}
72
```
73

74
## Architecture
75

76
TestNG is built around several key components:
77

78
- **Annotations System**: Declarative test configuration using @Test, @DataProvider, and lifecycle annotations
79
- **Test Execution Engine**: TestNG class orchestrates test discovery, dependency resolution, and parallel execution
80
- **Assertion Framework**: Assert class provides comprehensive static assertion methods for test verification
81
- **Event System**: Listener interfaces enable custom behavior during test lifecycle events
82
- **Configuration System**: XML-based suite configuration with XmlSuite and XmlTest classes
83
- **Group Management**: Flexible test organization using groups and dependencies
84
- **Parallel Execution**: Built-in support for parallel test execution at multiple levels
85

86
## Capabilities
87

88
### Test Annotations
89

90
Core annotations for marking and configuring test methods and classes. The @Test annotation is the primary way to mark methods as tests, with extensive configuration options for groups, dependencies, timeouts, and data providers.
91

92
```java { .api }
93
@Test(
94
    groups = {"unit", "integration"}, 
95
    dependsOnMethods = {"setUp"}, 
96
    timeOut = 5000,
97
    dataProvider = "testData",
98
    enabled = true,
99
    priority = 1
100
)
101
public void testMethod() { }
102

103
@DataProvider(name = "testData", parallel = true)
104
public Object[][] provideTestData() { }
105
```
106

107
[Test Annotations](./annotations.md)
108

109
### Assertions
110

111
Comprehensive assertion library providing static methods for test verification. Supports basic assertions, object comparison, array/collection comparison, and exception testing with detailed failure messages.
112

113
```java { .api }
114
public class Assert {
115
    public static void assertEquals(Object actual, Object expected);
116
    public static void assertTrue(boolean condition, String message);
117
    public static void assertNotNull(Object object);
118
    public static <T extends Throwable> T expectThrows(Class<T> expectedType, Executable executable);
119
    public static void fail(String message);
120
}
121

122
public class SoftAssert {
123
    public void assertEquals(Object actual, Object expected);
124
    public void assertAll();
125
}
126
```
127

128
[Assertions](./assertions.md)
129

130
### Test Execution
131

132
Main TestNG class for programmatic test execution with extensive configuration options. Supports test class registration, suite configuration, listener management, and parallel execution control.
133

134
```java { .api }
135
public class TestNG {
136
    public TestNG();
137
    public void setTestClasses(Class[] classes);
138
    public void setXmlSuites(List<XmlSuite> suites);
139
    public void addListener(Object listener);
140
    public void setParallel(XmlSuite.ParallelMode parallel);
141
    public void setThreadCount(int threadCount);
142
    public void run();
143
    public static void main(String[] argv);
144
}
145
```
146

147
[Test Execution](./test-execution.md)
148

149
### Event Listeners and Hooks
150

151
Comprehensive event system for customizing test behavior through listener interfaces. Provides hooks for test execution events, configuration methods, and suite lifecycle events.
152

153
```java { .api }
154
public interface ITestListener {
155
    void onTestStart(ITestResult result);
156
    void onTestSuccess(ITestResult result);
157
    void onTestFailure(ITestResult result);
158
    void onTestSkipped(ITestResult result);
159
}
160

161
public interface ISuiteListener {
162
    void onStart(ISuite suite);
163
    void onFinish(ISuite suite);
164
}
165

166
public interface ITestResult {
167
    int getStatus();
168
    ITestNGMethod getMethod();
169
    Object[] getParameters();
170
    Throwable getThrowable();
171
    long getStartMillis();
172
    long getEndMillis();
173
}
174
```
175

176
[Event Listeners and Hooks](./listeners-hooks.md)
177

178
### XML Configuration
179

180
XML-based configuration system for defining test suites, tests, classes, and execution parameters. Enables complex test orchestration and parameterization without code changes.
181

182
```java { .api }
183
public class XmlSuite {
184
    public enum ParallelMode { TESTS, METHODS, CLASSES, INSTANCES, NONE }
185
    public enum FailurePolicy { SKIP, CONTINUE }
186
    
187
    public void setName(String name);
188
    public void setParallel(ParallelMode parallel);
189
    public void setThreadCount(int threadCount);
190
    public void setTests(List<XmlTest> tests);
191
}
192

193
public class XmlTest {
194
    public void setName(String name);
195
    public void setXmlClasses(List<XmlClass> classes);
196
    public void addParameter(String name, String value);
197
}
198
```
199

200
[XML Configuration](./xml-configuration.md)
201

202
### Collections and Utilities
203

204
Utility classes for collections, string manipulation, and reflection operations. Includes factory methods for creating lists, maps, and sets, plus helper utilities for common operations.
205

206
```java { .api }
207
public class Lists {
208
    public static <T> List<T> newArrayList();
209
    public static <T> List<T> newLinkedList();
210
    public static <T> List<T> intersection(List<T> list1, List<T> list2);
211
}
212

213
public class Maps {
214
    public static <K, V> Map<K, V> newHashMap();
215
    public static <K, V> Map<K, V> newConcurrentMap();
216
    public static <K, V> ListMultiMap<K, V> newListMultiMap();
217
}
218

219
public class Reporter {
220
    public static void log(String message);
221
    public static ITestResult getCurrentTestResult();
222
    public static List<String> getOutput(ITestResult result);
223
}
224
```
225

226
[Collections and Utilities](./collections-utilities.md)
227

228
## Types
229

230
```java { .api }
231
// Test result constants
232
public interface ITestResult {
233
    int SUCCESS = 1;
234
    int FAILURE = 2;
235
    int SKIP = 3;
236
    int SUCCESS_PERCENTAGE_FAILURE = 4;
237
    int STARTED = 16;
238
    int CREATED = -1;
239
}
240

241
// Common interfaces
242
public interface ITestContext {
243
    String getName();
244
    Date getStartDate();
245
    Date getEndDate();
246
    IResultMap getPassedTests();
247
    IResultMap getFailedTests();
248
    IResultMap getSkippedTests();
249
}
250

251
public interface ITestNGMethod {
252
    String getMethodName();
253
    ITestClass getTestClass();
254
    String[] getGroups();
255
    String[] getDependsOnGroups();
256
    String[] getDependsOnMethods();
257
    boolean isTest();
258
    IRetryAnalyzer getRetryAnalyzer();
259
}
260

261
// Exception types
262
public class TestNGException extends RuntimeException {
263
    public TestNGException(String message);
264
    public TestNGException(String message, Throwable cause);
265
}
266
```