0
# Test Execution
1

2
TestNG's test execution system centers around the TestNG class, which orchestrates test discovery, dependency resolution, parallel execution, and result reporting. It provides both command-line and programmatic interfaces for running tests.
3

4
## Capabilities
5

6
### TestNG Class
7

8
The main entry point for running TestNG tests programmatically. Provides comprehensive configuration options for test execution, parallel processing, and result collection.
9

10
```java { .api }
11
/**
12
 * Main class for running TestNG tests programmatically
13
 */
14
public class TestNG {
15
    
16
    // Constants
17
    public static final String DEFAULT_COMMAND_LINE_SUITE_NAME = "Command line suite";
18
    public static final String DEFAULT_COMMAND_LINE_TEST_NAME = "Command line test";
19
    public static final String DEFAULT_OUTPUTDIR = "test-output";
20
    
21
    // Constructors
22
    public TestNG();
23
    public TestNG(boolean useDefaultListeners);
24
    
25
    // Test Configuration Methods
26
    public void setTestClasses(Class[] classes);
27
    public void setTestSuites(List<String> testSuites);
28
    public void setXmlSuites(List<XmlSuite> xmlSuites);
29
    public void setMethodInterceptor(IMethodInterceptor interceptor);
30
    public void setObjectFactory(ITestObjectFactory objectFactory);
31
    public void setTestRunnerFactory(ITestRunnerFactory testRunnerFactory);
32
    
33
    // Group Configuration
34
    public void setGroups(String groups);
35
    public void setExcludedGroups(String excludedGroups);
36
    public void setGroupByInstances(boolean groupByInstances);
37
    
38
    // Parallel Execution Configuration
39
    public void setParallel(XmlSuite.ParallelMode parallel);
40
    public void setThreadCount(int threadCount);
41
    public void setDataProviderThreadCount(int dataProviderThreadCount);
42
    public void setSuiteThreadPoolSize(int suiteThreadPoolSize);
43
    public void setConfigFailurePolicy(XmlSuite.FailurePolicy configFailurePolicy);
44
    
45
    // Output Configuration
46
    public void setOutputDirectory(String outputDirectory);
47
    public void setVerbose(int verbose);
48
    public void setUseDefaultListeners(boolean useDefaultListeners);
49
    
50
    // Listener Management
51
    public void addListener(Object listener);
52
    public void setListenerClasses(List<Class<? extends ITestNGListener>> listenerClasses);
53
    public void addClassLoader(ClassLoader loader);
54
    
55
    // Execution Methods
56
    public void run();
57
    public int getStatus();
58
    public List<ISuite> getSuites();
59
    
60
    // Command Line Interface
61
    public static void main(String[] argv);
62
    public void configure(CommandLineArgs cla);
63
    
64
    // Utility Methods
65
    public void initializeEverything();
66
    public void setPreserveOrder(boolean preserveOrder);
67
    public void setRandomizeSuites(boolean randomizeSuites);
68
    public void setSkipFailedInvocationCounts(boolean skipFailedInvocationCounts);
69
    public void setAnnotations(IAnnotationFinder finder);
70
}
71
```
72

73
**Usage Examples:**
74

75
```java
76
import org.testng.TestNG;
77
import org.testng.xml.XmlSuite;
78
import java.util.Arrays;
79
import java.util.List;
80

81
public class TestExecutionExamples {
82
    
83
    public void runTestClasses() {
84
        // Basic test execution with classes
85
        TestNG testng = new TestNG();
86
        testng.setTestClasses(new Class[] { 
87
            MyTestClass1.class, 
88
            MyTestClass2.class 
89
        });
90
        testng.run();
91
        
92
        System.out.println("Test execution status: " + testng.getStatus());
93
    }
94
    
95
    public void runWithConfiguration() {
96
        TestNG testng = new TestNG();
97
        
98
        // Configure test classes
99
        testng.setTestClasses(new Class[] { MyTestClass.class });
100
        
101
        // Configure output
102
        testng.setOutputDirectory("target/test-results");
103
        testng.setVerbose(2);
104
        
105
        // Configure groups
106
        testng.setGroups("unit,integration");
107
        testng.setExcludedGroups("slow");
108
        
109
        // Configure parallel execution
110
        testng.setParallel(XmlSuite.ParallelMode.METHODS);
111
        testng.setThreadCount(4);
112
        
113
        // Add listeners
114
        testng.addListener(new CustomTestListener());
115
        testng.addListener(new CustomSuiteListener());
116
        
117
        // Run tests
118
        testng.run();
119
        
120
        // Check results
121
        if (testng.getStatus() == 0) {
122
            System.out.println("All tests passed");
123
        } else {
124
            System.out.println("Some tests failed");
125
        }
126
    }
127
    
128
    public void runWithXmlSuites() {
129
        TestNG testng = new TestNG();
130
        
131
        // Create XML suite programmatically
132
        XmlSuite suite = new XmlSuite();
133
        suite.setName("Programmatic Suite");
134
        suite.setParallel(XmlSuite.ParallelMode.CLASSES);
135
        suite.setThreadCount(3);
136
        
137
        // Add tests to suite
138
        XmlTest test = new XmlTest(suite);
139
        test.setName("Unit Tests");
140
        test.setXmlClasses(Arrays.asList(
141
            new XmlClass("com.example.UnitTest1"),
142
            new XmlClass("com.example.UnitTest2")
143
        ));
144
        
145
        // Set XML suites
146
        testng.setXmlSuites(Arrays.asList(suite));
147
        testng.run();
148
    }
149
    
150
    public void runTestSuiteFiles() {
151
        TestNG testng = new TestNG();
152
        
153
        // Run from XML files
154
        testng.setTestSuites(Arrays.asList(
155
            "src/test/resources/smoke-tests.xml",
156
            "src/test/resources/integration-tests.xml"
157
        ));
158
        
159
        testng.run();
160
    }
161
    
162
    public void runWithAdvancedConfiguration() {
163
        TestNG testng = new TestNG();
164
        
165
        // Advanced configuration
166
        testng.setTestClasses(new Class[] { AdvancedTestClass.class });
167
        testng.setPreserveOrder(true);
168
        testng.setRandomizeSuites(false);
169
        testng.setSkipFailedInvocationCounts(true);
170
        testng.setConfigFailurePolicy(XmlSuite.FailurePolicy.CONTINUE);
171
        testng.setDataProviderThreadCount(2);
172
        testng.setSuiteThreadPoolSize(1);
173
        
174
        // Custom object factory for dependency injection
175
        testng.setObjectFactory(new GuiceObjectFactory());
176
        
177
        // Method interceptor for custom test selection
178
        testng.setMethodInterceptor(new CustomMethodInterceptor());
179
        
180
        testng.run();
181
    }
182
    
183
    public static void main(String[] args) {
184
        // Command line execution
185
        TestNG.main(new String[] {
186
            "-testclass", "com.example.MyTestClass",
187
            "-groups", "unit",
188
            "-parallel", "methods",
189
            "-threadcount", "4",
190
            "-outputdir", "test-results"
191
        });
192
    }
193
}
194
```
195

196
### Command Line Interface
197

198
TestNG provides a comprehensive command-line interface for test execution with extensive configuration options.
199

200
```bash
201
# Basic usage
202
java org.testng.TestNG testng.xml
203

204
# Run specific test classes
205
java org.testng.TestNG -testclass com.example.TestClass1,com.example.TestClass2
206

207
# Run with groups
208
java org.testng.TestNG -groups unit,integration -excludegroups slow testng.xml
209

210
# Parallel execution
211
java org.testng.TestNG -parallel methods -threadcount 4 testng.xml
212

213
# Output configuration
214
java org.testng.TestNG -d test-results -verbose 2 testng.xml
215

216
# Custom listeners
217
java org.testng.TestNG -listener com.example.CustomListener testng.xml
218
```
219

220
**Command Line Options:**
221

222
```java { .api }
223
/**
224
 * Command line argument configuration
225
 */
226
public class CommandLineArgs {
227
    
228
    // Test selection
229
    public String testClass;           // -testclass: Comma-separated test classes
230
    public List<String> suiteFiles;   // Suite XML files
231
    public String groups;              // -groups: Included groups
232
    public String excludedGroups;     // -excludegroups: Excluded groups
233
    public String methods;             // -methods: Specific methods to run
234
    
235
    // Parallel execution
236
    public String parallel;            // -parallel: none|methods|tests|classes|instances
237
    public Integer threadCount;        // -threadcount: Number of threads
238
    public Integer dataProviderThreadCount; // -dataproviderthreadcount
239
    public Integer suiteThreadPoolSize;     // -suitethreadpoolsize
240
    
241
    // Output configuration
242
    public String outputDirectory;     // -d: Output directory
243
    public Integer verbose;            // -verbose: Verbosity level
244
    public Boolean useDefaultListeners; // -usedefaultlisteners
245
    
246
    // Listeners and factories
247
    public String listener;            // -listener: Comma-separated listener classes
248
    public String objectFactory;      // -objectfactory: Object factory class
249
    public String testRunnerFactory;   // -testrunner: Test runner factory
250
    
251
    // Execution behavior
252
    public String configFailurePolicy; // -configfailurepolicy: skip|continue
253
    public Boolean skipFailedInvocationCounts; // -skipfailedinvocationcounts
254
    public Boolean preserveOrder;      // -preserveorder
255
    public Boolean randomizeSuites;    // -randomizesuites
256
    public Boolean groupByInstances;   // -groupbyinstances
257
    
258
    // Miscellaneous
259
    public String xmlPathInJar;        // -xmlpathinjar: XML path in JAR
260
    public List<String> commandLineMethods; // Individual methods
261
    public String junit;               // -junit: Run in JUnit mode
262
    public Boolean mixed;              // -mixed: Mixed mode
263
}
264
```
265

266
### Test Result Collection
267

268
TestNG provides comprehensive result collection through the ISuite and ITestResult interfaces.
269

270
```java { .api }
271
/**
272
 * Suite execution results
273
 */
274
public interface ISuite {
275
    String getName();
276
    Map<String, ISuiteResult> getResults();
277
    String getOutputDirectory();
278
    String getParameter(String parameterName);
279
    Map<String, Collection<ITestNGMethod>> getMethodsByGroups();
280
    Collection<ITestNGMethod> getAllInvokedMethods();
281
    Collection<ITestNGMethod> getExcludedMethods();
282
    void run();
283
    String getXmlSuite();
284
    IObjectFactory getObjectFactory();
285
    IObjectFactory2 getObjectFactory2();
286
    List<IInvokedMethod> getAllInvokedMethods();
287
}
288

289
/**
290
 * Individual test execution results
291
 */
292
public interface ISuiteResult {
293
    ITestContext getTestContext();
294
    String getName();
295
}
296

297
/**
298
 * Test context providing execution information
299
 */
300
public interface ITestContext {
301
    String getName();
302
    Date getStartDate();
303
    Date getEndDate();
304
    IResultMap getPassedTests();
305
    IResultMap getFailedTests();
306
    IResultMap getSkippedTests();
307
    IResultMap getFailedButWithinSuccessPercentageTests();
308
    String[] getIncludedGroups();
309
    String[] getExcludedGroups();
310
    String getOutputDirectory();
311
    ISuite getSuite();
312
    Object getAttribute(String name);
313
    void setAttribute(String name, Object value);
314
    Set<String> getAttributeNames();
315
    Object removeAttribute(String name);
316
}
317
```
318

319
**Usage Examples:**
320

321
```java
322
public class ResultCollectionExamples {
323
    
324
    public void collectTestResults() {
325
        TestNG testng = new TestNG();
326
        testng.setTestClasses(new Class[] { MyTestClass.class });
327
        testng.run();
328
        
329
        // Get suite results
330
        List<ISuite> suites = testng.getSuites();
331
        for (ISuite suite : suites) {
332
            System.out.println("Suite: " + suite.getName());
333
            
334
            Map<String, ISuiteResult> results = suite.getResults();
335
            for (ISuiteResult result : results.values()) {
336
                ITestContext context = result.getTestContext();
337
                
338
                System.out.println("Test: " + context.getName());
339
                System.out.println("Start: " + context.getStartDate());
340
                System.out.println("End: " + context.getEndDate());
341
                
342
                // Passed tests
343
                System.out.println("Passed: " + context.getPassedTests().size());
344
                
345
                // Failed tests
346
                System.out.println("Failed: " + context.getFailedTests().size());
347
                for (ITestResult testResult : context.getFailedTests().getAllResults()) {
348
                    System.out.println("  Failed: " + testResult.getMethod().getMethodName());
349
                    if (testResult.getThrowable() != null) {
350
                        System.out.println("  Error: " + testResult.getThrowable().getMessage());
351
                    }
352
                }
353
                
354
                // Skipped tests
355
                System.out.println("Skipped: " + context.getSkippedTests().size());
356
            }
357
        }
358
    }
359
    
360
    public void analyzeTestExecution() {
361
        TestNG testng = new TestNG();
362
        testng.setTestClasses(new Class[] { AnalysisTestClass.class });
363
        testng.addListener(new ITestListener() {
364
            @Override
365
            public void onTestStart(ITestResult result) {
366
                System.out.println("Starting: " + result.getMethod().getMethodName());
367
            }
368
            
369
            @Override
370
            public void onTestSuccess(ITestResult result) {
371
                long duration = result.getEndMillis() - result.getStartMillis();
372
                System.out.println("Passed: " + result.getMethod().getMethodName() 
373
                    + " (" + duration + "ms)");
374
            }
375
            
376
            @Override
377
            public void onTestFailure(ITestResult result) {
378
                System.out.println("Failed: " + result.getMethod().getMethodName());
379
                System.out.println("Parameters: " + Arrays.toString(result.getParameters()));
380
            }
381
        });
382
        
383
        testng.run();
384
        
385
        // Final status check
386
        int status = testng.getStatus();
387
        System.out.println("Execution completed with status: " + status);
388
    }
389
}
390
```
391

392
### Execution Control Interfaces
393

394
Interfaces for controlling test execution behavior, method selection, and object creation.
395

396
```java { .api }
397
/**
398
 * Interface for intercepting and modifying test methods
399
 */
400
public interface IMethodInterceptor {
401
    List<IMethodInstance> intercept(List<IMethodInstance> methods, ITestContext context);
402
}
403

404
/**
405
 * Interface for selecting test methods
406
 */
407
public interface IMethodSelector {
408
    boolean includeMethod(IMethodSelectorContext context, ITestNGMethod method, boolean isTestMethod);
409
    void setTestMethods(List<ITestNGMethod> testMethods);
410
}
411

412
/**
413
 * Interface for creating test instances
414
 */
415
public interface ITestObjectFactory {
416
    Object newInstance(Constructor constructor, Object... params);
417
}
418

419
/**
420
 * Enhanced object factory interface
421
 */
422
public interface IObjectFactory2 extends ITestObjectFactory {
423
    Object newInstance(Class<?> cls);
424
}
425

426
/**
427
 * Interface for creating test runners
428
 */
429
public interface ITestRunnerFactory {
430
    TestRunner newTestRunner(ISuite suite, XmlTest test, 
431
                           Collection<IInvokedMethodListener> listeners,
432
                           List<IClassListener> classListeners);
433
}
434
```
435

436
## Types
437

438
```java { .api }
439
// Test execution status constants
440
public static final int HAS_NO_TEST = 1;
441
public static final int HAS_FAILURE = 2;  
442
public static final int HAS_SKIPPED = 4;
443
public static final int HAS_FSP = 8; // Failed but within success percentage
444

445
// Parallel execution modes (from XmlSuite)
446
public enum ParallelMode {
447
    TESTS,      // Parallel test execution
448
    METHODS,    // Parallel method execution  
449
    CLASSES,    // Parallel class execution
450
    INSTANCES,  // Parallel instance execution
451
    NONE        // No parallel execution
452
}
453

454
// Configuration failure policies
455
public enum FailurePolicy {
456
    SKIP,       // Skip dependent tests on configuration failure
457
    CONTINUE    // Continue with dependent tests
458
}
459

460
// Method instance for interceptors
461
public interface IMethodInstance {
462
    ITestNGMethod getMethod();
463
    Object getInstance();
464
}
465

466
// Method selector context
467
public interface IMethodSelectorContext {
468
    boolean isStopped();
469
    void setStopped(boolean stopped);
470
    Map<Object, Object> getUserData();
471
}
472
```