0
# Test Annotations
1

2
TestNG's annotation system provides declarative test configuration, eliminating the need for naming conventions and providing flexible test orchestration through groups, dependencies, and data providers.
3

4
## Capabilities
5

6
### @Test Annotation
7

8
The primary annotation for marking methods and classes as tests. Provides extensive configuration options for test behavior, dependencies, grouping, and execution parameters.
9

10
```java { .api }
11
/**
12
 * Marks a method or class as a test
13
 * @param groups - Groups this test belongs to (for selective execution)
14
 * @param dependsOnMethods - Methods this test depends on (must succeed first)
15
 * @param dependsOnGroups - Groups this test depends on (must succeed first)
16
 * @param enabled - Whether this test is enabled (default: true)
17
 * @param timeOut - Maximum time in milliseconds for test execution
18
 * @param invocationCount - Number of times to invoke this method
19
 * @param threadPoolSize - Size of thread pool for invocationCount > 1
20
 * @param successPercentage - Success percentage for invocationCount > 1
21
 * @param dataProvider - Name of data provider method
22
 * @param dataProviderClass - Class containing the data provider method
23
 * @param expectedExceptions - Expected exception types (test passes if thrown)
24
 * @param priority - Priority for test method ordering
25
 * @param description - Human-readable description of the test
26
 * @param suiteName - Override suite name for this test
27
 * @param testName - Override test name for this test
28
 * @param singleThreaded - Whether test methods should run in single thread
29
 * @param retryAnalyzer - Class to determine if failed test should be retried
30
 */
31
@Test(
32
    groups = {"unit", "smoke"}, 
33
    dependsOnMethods = {"setupMethod"}, 
34
    dependsOnGroups = {"initialization"}, 
35
    enabled = true,
36
    timeOut = 5000,
37
    invocationCount = 1,
38
    threadPoolSize = 1,
39
    successPercentage = 100,
40
    dataProvider = "testData",
41
    dataProviderClass = DataProviders.class,
42
    expectedExceptions = {IllegalArgumentException.class},
43
    priority = 0,
44
    description = "Test description",
45
    suiteName = "Custom Suite",
46
    testName = "Custom Test",
47
    singleThreaded = false,
48
    retryAnalyzer = RetryAnalyzer.class
49
)
50
public void testMethod() { }
51
```
52

53
**Usage Examples:**
54

55
```java
56
// Basic test
57
@Test
58
public void simpleTest() {
59
    Assert.assertTrue(true);
60
}
61

62
// Test with groups
63
@Test(groups = {"unit", "fast"})
64
public void groupedTest() {
65
    Assert.assertEquals(2 + 2, 4);
66
}
67

68
// Test with dependencies
69
@Test
70
public void setupData() {
71
    // Setup code
72
}
73

74
@Test(dependsOnMethods = "setupData")
75
public void testWithDependency() {
76
    // This runs after setupData succeeds
77
}
78

79
// Test with timeout
80
@Test(timeOut = 1000)
81
public void fastTest() {
82
    // Must complete within 1 second
83
}
84

85
// Test expecting exception
86
@Test(expectedExceptions = IllegalArgumentException.class)
87
public void testExpectedException() {
88
    throw new IllegalArgumentException("Expected");
89
}
90

91
// Multiple invocations
92
@Test(invocationCount = 5, threadPoolSize = 2)
93
public void repeatedTest() {
94
    // Runs 5 times with 2 threads
95
}
96
```
97

98
### @DataProvider Annotation
99

100
Marks methods that supply data for parameterized tests. Enables data-driven testing by providing test data from various sources.
101

102
```java { .api }
103
/**
104
 * Marks a method as a data provider for parameterized tests
105
 * @param name - Name of the data provider (defaults to method name)
106
 * @param parallel - Whether data provider should run in parallel
107
 * @param indices - Specific indices of data to use from the provider
108
 * @param propagateFailureAsTestFailure - Whether data provider failures should be test failures
109
 * @param cacheDataForTestRetries - Whether to cache data for test retries
110
 * @param retryUsing - Retry analyzer for data provider failures
111
 */
112
@DataProvider(
113
    name = "customName",
114
    parallel = false,
115
    indices = {0, 2, 4},
116
    propagateFailureAsTestFailure = true,
117
    cacheDataForTestRetries = false,
118
    retryUsing = DataProviderRetryAnalyzer.class
119
)
120
public Object[][] dataProviderMethod() {
121
    return new Object[][] {
122
        {"param1", 123},
123
        {"param2", 456}
124
    };
125
}
126
```
127

128
**Usage Examples:**
129

130
```java
131
// Basic data provider
132
@DataProvider
133
public Object[][] basicData() {
134
    return new Object[][] {
135
        {"test1", 1},
136
        {"test2", 2},
137
        {"test3", 3}
138
    };
139
}
140

141
@Test(dataProvider = "basicData")
142
public void testWithData(String name, int value) {
143
    Assert.assertNotNull(name);
144
    Assert.assertTrue(value > 0);
145
}
146

147
// Named data provider
148
@DataProvider(name = "usernames")
149
public Object[][] getUsernames() {
150
    return new Object[][] {
151
        {"alice"},
152
        {"bob"},
153
        {"charlie"}
154
    };
155
}
156

157
@Test(dataProvider = "usernames")
158
public void testUsernames(String username) {
159
    Assert.assertTrue(username.length() > 0);
160
}
161

162
// Parallel data provider
163
@DataProvider(parallel = true)
164
public Object[][] parallelData() {
165
    return new Object[][] {
166
        {1}, {2}, {3}, {4}, {5}
167
    };
168
}
169

170
// Data provider with specific indices
171
@DataProvider(indices = {0, 2})
172
public Object[][] selectiveData() {
173
    return new Object[][] {
174
        {"first"},   // index 0 - will be used
175
        {"second"},  // index 1 - will be skipped
176
        {"third"}    // index 2 - will be used
177
    };
178
}
179

180
// Data provider from external class
181
public class ExternalDataProvider {
182
    @DataProvider
183
    public static Object[][] externalData() {
184
        return new Object[][] { {"external"} };
185
    }
186
}
187

188
@Test(dataProvider = "externalData", dataProviderClass = ExternalDataProvider.class)
189
public void testExternalData(String data) {
190
    Assert.assertEquals(data, "external");
191
}
192
```
193

194
### Configuration Annotations
195

196
Lifecycle annotations for setup and teardown methods that run at different scopes (method, class, test, suite, groups).
197

198
```java { .api }
199
// Method-level configuration
200
@BeforeMethod
201
public void beforeEachTest() { }
202

203
@AfterMethod  
204
public void afterEachTest() { }
205

206
// Class-level configuration
207
@BeforeClass
208
public void beforeAllTestsInClass() { }
209

210
@AfterClass
211
public void afterAllTestsInClass() { }
212

213
// Test-level configuration (from testng.xml)
214
@BeforeTest
215
public void beforeTest() { }
216

217
@AfterTest
218
public void afterTest() { }
219

220
// Suite-level configuration
221
@BeforeSuite
222
public void beforeEntireSuite() { }
223

224
@AfterSuite
225
public void afterEntireSuite() { }
226

227
// Group-level configuration
228
@BeforeGroups(groups = {"database", "integration"})
229
public void beforeDatabaseTests() { }
230

231
@AfterGroups(groups = {"database", "integration"})
232
public void afterDatabaseTests() { }
233
```
234

235
**Configuration Attributes:**
236

237
All configuration annotations support these common attributes:
238

239
```java { .api }
240
@BeforeMethod(
241
    groups = {"setup"},
242
    dependsOnMethods = {"globalSetup"},
243
    dependsOnGroups = {"initialization"},
244
    enabled = true,
245
    alwaysRun = false,
246
    description = "Setup method description"
247
)
248
public void setupMethod() { }
249
```
250

251
**Usage Examples:**
252

253
```java
254
public class ConfigurationExample {
255
    
256
    @BeforeSuite
257
    public void globalSetup() {
258
        System.out.println("Suite started");
259
        // Database connection, global resources
260
    }
261
    
262
    @BeforeClass
263
    public void classSetup() {
264
        System.out.println("Class setup");
265
        // Class-level initialization
266
    }
267
    
268
    @BeforeMethod
269
    public void methodSetup() {
270
        System.out.println("Method setup");
271
        // Fresh state for each test
272
    }
273
    
274
    @Test
275
    public void testMethod1() {
276
        System.out.println("Test 1");
277
    }
278
    
279
    @Test
280
    public void testMethod2() {
281
        System.out.println("Test 2");
282
    }
283
    
284
    @AfterMethod
285
    public void methodCleanup() {
286
        System.out.println("Method cleanup");
287
    }
288
    
289
    @AfterClass
290
    public void classCleanup() {
291
        System.out.println("Class cleanup");
292
    }
293
    
294
    @AfterSuite
295
    public void globalCleanup() {
296
        System.out.println("Suite finished");
297
        // Release global resources
298
    }
299
}
300
```
301

302
### @Factory Annotation
303

304
Marks methods that create test instances dynamically. Enables creation of multiple test instances with different parameters or configurations.
305

306
```java { .api }
307
/**
308
 * Marks a method as a factory for creating test instances
309
 * @param dataProvider - Data provider for factory parameters
310
 * @param dataProviderClass - Class containing the data provider
311
 * @param enabled - Whether factory is enabled
312
 * @param indices - Specific indices to use from data provider
313
 */
314
@Factory(
315
    dataProvider = "factoryData",
316
    dataProviderClass = FactoryDataProvider.class,
317
    enabled = true,
318
    indices = {0, 1, 2}
319
)
320
public Object[] createInstances() {
321
    return new Object[] { new TestClass() };
322
}
323
```
324

325
**Usage Examples:**
326

327
```java
328
// Factory creating multiple instances
329
public class TestFactory {
330
    
331
    @Factory
332
    public Object[] createTests() {
333
        return new Object[] {
334
            new WebTest("Chrome"),
335
            new WebTest("Firefox"),
336
            new WebTest("Safari")
337
        };
338
    }
339
}
340

341
public class WebTest {
342
    private String browser;
343
    
344
    public WebTest(String browser) {
345
        this.browser = browser;
346
    }
347
    
348
    @Test
349
    public void testBrowser() {
350
        System.out.println("Testing with " + browser);
351
    }
352
}
353

354
// Factory with data provider
355
public class ParameterizedFactory {
356
    
357
    @DataProvider
358
    public Object[][] browsers() {
359
        return new Object[][] {
360
            {"Chrome"},
361
            {"Firefox"},
362
            {"Safari"}
363
        };
364
    }
365
    
366
    @Factory(dataProvider = "browsers")
367
    public Object[] createBrowserTests(String browser) {
368
        return new Object[] { new BrowserTest(browser) };
369
    }
370
}
371
```
372

373
### Parameter and Dependency Injection Annotations
374

375
Annotations for parameter injection from testng.xml and dependency injection frameworks.
376

377
```java { .api }
378
// Parameter injection from testng.xml
379
@Parameters({"username", "password"})
380
@Test
381
public void testLogin(String username, String password) { }
382

383
// Optional parameters (no error if missing)
384
@Parameters("optionalParam")  
385
@Test
386
public void testOptional(@Optional("defaultValue") String param) { }
387

388
// Guice dependency injection
389
@Guice(modules = {TestModule.class})
390
public class GuiceTest {
391
    
392
    @Inject
393
    private UserService userService;
394
    
395
    @Test
396
    public void testWithInjection() {
397
        // userService is injected by Guice
398
    }
399
}
400
```
401

402
### Listener and Custom Annotations
403

404
Annotations for configuring listeners and custom test attributes.
405

406
```java { .api }
407
// Listener configuration
408
@Listeners({TestListener.class, SuiteListener.class})
409
public class ListenerTest {
410
    
411
    @Test
412
    public void testWithListeners() { }
413
}
414

415
// Custom attributes
416
@Test
417
@CustomAttribute(name = "category", values = {"smoke"})
418
@CustomAttribute(name = "owner", values = {"john.doe"})
419
public void testWithAttributes() { }
420
```
421

422
## Types
423

424
```java { .api }
425
// Annotation interfaces (for reflection/programmatic access)
426
public interface Test {
427
    String[] groups() default {};
428
    String[] dependsOnMethods() default {};
429
    String[] dependsOnGroups() default {};
430
    boolean enabled() default true;
431
    long timeOut() default 0L;
432
    int invocationCount() default 1;
433
    int threadPoolSize() default 0;
434
    int successPercentage() default 100;
435
    String dataProvider() default "";
436
    Class<?> dataProviderClass() default Object.class;
437
    Class<? extends Throwable>[] expectedExceptions() default {};
438
    int priority() default 0;
439
    String description() default "";
440
    String suiteName() default "";
441
    String testName() default "";
442
    boolean singleThreaded() default false;
443
    Class<? extends IRetryAnalyzer> retryAnalyzer() default IRetryAnalyzer.class;
444
}
445

446
public interface DataProvider {
447
    String name() default "";
448
    boolean parallel() default false;
449
    int[] indices() default {};
450
    boolean propagateFailureAsTestFailure() default false;
451
    boolean cacheDataForTestRetries() default false;
452
    Class<? extends IRetryDataProvider> retryUsing() default IRetryDataProvider.class;
453
}
454
```