0
# XML Configuration
1

2
TestNG's XML configuration system provides powerful declarative test orchestration through XML files. This enables complex test suite organization, parameterization, parallel execution, and group management without requiring code changes.
3

4
## Capabilities
5

6
### XmlSuite Class
7

8
The root configuration class representing a test suite with comprehensive settings for execution behavior, parallel processing, and test organization.
9

10
```java { .api }
11
/**
12
 * Root configuration class for TestNG test suites
13
 */
14
public class XmlSuite {
15
    
16
    // Parallel execution modes
17
    public enum ParallelMode {
18
        TESTS,      // Run tests in parallel
19
        METHODS,    // Run test methods in parallel
20
        CLASSES,    // Run test classes in parallel  
21
        INSTANCES,  // Run test instances in parallel
22
        NONE        // No parallel execution
23
    }
24
    
25
    // Configuration failure policies
26
    public enum FailurePolicy {
27
        SKIP,       // Skip dependent tests on configuration failure
28
        CONTINUE    // Continue with dependent tests on configuration failure
29
    }
30
    
31
    // Constructor
32
    public XmlSuite();
33
    public XmlSuite(XmlSuite parent);
34
    
35
    // Basic configuration
36
    public void setName(String name);
37
    public String getName();
38
    public void setVerbose(int verbose);
39
    public int getVerbose();
40
    public void setPreserveOrder(boolean preserveOrder);
41
    public boolean getPreserveOrder();
42
    
43
    // Parallel execution configuration
44
    public void setParallel(ParallelMode parallel);
45
    public ParallelMode getParallel();
46
    public void setThreadCount(int threadCount);
47
    public int getThreadCount();
48
    public void setDataProviderThreadCount(int dataProviderThreadCount);
49
    public int getDataProviderThreadCount();
50
    public void setTimeOut(String timeOut);
51
    public String getTimeOut();
52
    
53
    // Group configuration
54
    public void setGroups(XmlGroups groups);
55
    public XmlGroups getGroups();
56
    
57
    // Test management
58
    public void setTests(List<XmlTest> tests);
59
    public List<XmlTest> getTests();
60
    public void addTest(XmlTest test);
61
    
62
    // Suite-level parameters
63
    public void setParameters(Map<String, String> parameters);
64
    public Map<String, String> getParameters();
65
    public void addParameter(String name, String value);
66
    public String getParameter(String name);
67
    
68
    // Listener configuration
69
    public void setListeners(List<String> listeners);
70
    public List<String> getListeners();
71
    public void addListener(String listener);
72
    
73
    // Suite files (for suite-of-suites)
74
    public void setSuiteFiles(List<String> suiteFiles);
75
    public List<String> getSuiteFiles();
76
    public void addSuiteFile(String suiteFile);
77
    
78
    // Failure handling
79
    public void setConfigFailurePolicy(FailurePolicy configFailurePolicy);
80
    public FailurePolicy getConfigFailurePolicy();
81
    public void setSkipFailedInvocationCounts(boolean skipFailedInvocationCounts);
82
    public boolean skipFailedInvocationCounts();
83
    
84
    // Method selectors
85
    public void setMethodSelectors(List<XmlMethodSelector> methodSelectors);
86
    public List<XmlMethodSelector> getMethodSelectors();
87
    
88
    // Object factory
89
    public void setObjectFactory(String objectFactory);
90
    public String getObjectFactory();
91
    
92
    // Utility methods
93
    public XmlSuite shallowCopy();
94
    public Object clone();
95
    public void setFileName(String fileName);
96
    public String getFileName();
97
}
98
```
99

100
**Usage Examples:**
101

102
```java
103
import org.testng.xml.*;
104
import java.util.*;
105

106
public class XmlSuiteExamples {
107
    
108
    public void createBasicSuite() {
109
        // Create a basic test suite
110
        XmlSuite suite = new XmlSuite();
111
        suite.setName("Basic Test Suite");
112
        suite.setVerbose(1);
113
        suite.setPreserveOrder(true);
114
        
115
        // Add suite-level parameters
116
        suite.addParameter("environment", "staging");
117
        suite.addParameter("browser", "chrome");
118
        
119
        // Create and add a test
120
        XmlTest test = new XmlTest(suite);
121
        test.setName("Smoke Tests");
122
        
123
        // Add test classes
124
        XmlClass xmlClass1 = new XmlClass("com.example.LoginTest");
125
        XmlClass xmlClass2 = new XmlClass("com.example.HomePageTest");
126
        test.setXmlClasses(Arrays.asList(xmlClass1, xmlClass2));
127
        
128
        suite.addTest(test);
129
        
130
        System.out.println("Created suite: " + suite.getName());
131
    }
132
    
133
    public void createParallelSuite() {
134
        XmlSuite suite = new XmlSuite();
135
        suite.setName("Parallel Execution Suite");
136
        
137
        // Configure parallel execution
138
        suite.setParallel(XmlSuite.ParallelMode.METHODS);
139
        suite.setThreadCount(4);
140
        suite.setDataProviderThreadCount(2);
141
        suite.setTimeOut("300000"); // 5 minutes
142
        
143
        // Configure failure handling
144
        suite.setConfigFailurePolicy(XmlSuite.FailurePolicy.CONTINUE);
145
        suite.setSkipFailedInvocationCounts(true);
146
        
147
        XmlTest test = new XmlTest(suite);
148
        test.setName("Parallel Test Execution");
149
        test.setParallel(XmlSuite.ParallelMode.METHODS);
150
        test.setThreadCount(2);
151
        
152
        suite.addTest(test);
153
    }
154
    
155
    public void createSuiteWithGroups() {
156
        XmlSuite suite = new XmlSuite();
157
        suite.setName("Grouped Test Suite");
158
        
159
        // Configure groups at suite level
160
        XmlGroups groups = new XmlGroups();
161
        
162
        // Run groups
163
        XmlRun run = new XmlRun();
164
        run.onInclude("smoke");
165
        run.onInclude("regression");
166
        groups.setRun(run);
167
        
168
        // Group dependencies
169
        XmlDependencies dependencies = new XmlDependencies();
170
        Map<String, String> dependencyMap = new HashMap<>();
171
        dependencyMap.put("regression", "smoke");
172
        dependencies.setDependencies(dependencyMap);
173
        groups.setDependencies(dependencies);
174
        
175
        suite.setGroups(groups);
176
        
177
        XmlTest test = new XmlTest(suite);
178
        test.setName("Grouped Tests");
179
        
180
        suite.addTest(test);
181
    }
182
    
183
    public void createSuiteOfSuites() {
184
        // Parent suite that includes other suites
185
        XmlSuite parentSuite = new XmlSuite();
186
        parentSuite.setName("Master Test Suite");
187
        
188
        // Add child suite files
189
        parentSuite.addSuiteFile("smoke-tests.xml");
190
        parentSuite.addSuiteFile("regression-tests.xml");
191
        parentSuite.addSuiteFile("integration-tests.xml");
192
        
193
        // Configure parallel execution of suites
194
        parentSuite.setParallel(XmlSuite.ParallelMode.TESTS);
195
        parentSuite.setThreadCount(3);
196
        
197
        System.out.println("Created suite-of-suites: " + parentSuite.getName());
198
    }
199
    
200
    public void createSuiteWithListeners() {
201
        XmlSuite suite = new XmlSuite();
202
        suite.setName("Suite with Listeners");
203
        
204
        // Add listeners
205
        suite.addListener("com.example.CustomTestListener");
206
        suite.addListener("com.example.CustomSuiteListener");
207
        suite.addListener("com.example.EmailReporter");
208
        
209
        // Set custom object factory
210
        suite.setObjectFactory("com.example.GuiceObjectFactory");
211
        
212
        XmlTest test = new XmlTest(suite);
213
        test.setName("Listener Test");
214
        
215
        suite.addTest(test);
216
    }
217
}
218
```
219

220
### XmlTest Class
221

222
Represents an individual test within a suite, providing test-specific configuration and class/method selection.
223

224
```java { .api }
225
/**
226
 * Configuration class for individual tests within a suite
227
 */
228
public class XmlTest {
229
    
230
    // Constructor
231
    public XmlTest();
232
    public XmlTest(XmlSuite suite);
233
    
234
    // Basic configuration
235
    public void setName(String name);
236
    public String getName();
237
    public void setVerbose(int verbose);
238
    public int getVerbose();
239
    public void setPreserveOrder(boolean preserveOrder);
240
    public boolean getPreserveOrder();
241
    
242
    // Suite relationship
243
    public void setSuite(XmlSuite suite);
244
    public XmlSuite getSuite();
245
    
246
    // Parallel execution (overrides suite settings)
247
    public void setParallel(XmlSuite.ParallelMode parallel);
248
    public XmlSuite.ParallelMode getParallel();
249
    public void setThreadCount(int threadCount);
250
    public int getThreadCount();
251
    public void setTimeOut(long timeOut);
252
    public long getTimeOut();
253
    
254
    // Test-level parameters
255
    public void setParameters(Map<String, String> parameters);
256
    public Map<String, String> getParameters();
257
    public void addParameter(String name, String value);
258
    public String getParameter(String name);
259
    
260
    // Class configuration
261
    public void setXmlClasses(List<XmlClass> xmlClasses);
262
    public List<XmlClass> getXmlClasses();
263
    public void addClass(XmlClass xmlClass);
264
    
265
    // Package configuration
266
    public void setXmlPackages(List<XmlPackage> xmlPackages);
267
    public List<XmlPackage> getXmlPackages();
268
    public void addPackage(XmlPackage xmlPackage);
269
    
270
    // Group configuration (overrides suite groups)
271
    public void setGroups(XmlGroups groups);
272
    public XmlGroups getGroups();
273
    public void setIncludedGroups(List<String> includedGroups);
274
    public List<String> getIncludedGroups();
275
    public void setExcludedGroups(List<String> excludedGroups);
276
    public List<String> getExcludedGroups();
277
    
278
    // Method selectors
279
    public void setMethodSelectors(List<XmlMethodSelector> methodSelectors);
280
    public List<XmlMethodSelector> getMethodSelectors();
281
    
282
    // Utility methods
283
    public Object clone();
284
    public void setIndex(int index);
285
    public int getIndex();
286
}
287
```
288

289
**Usage Examples:**
290

291
```java
292
public class XmlTestExamples {
293
    
294
    public void createParameterizedTest() {
295
        XmlSuite suite = new XmlSuite();
296
        suite.setName("Parameterized Suite");
297
        
298
        XmlTest test = new XmlTest(suite);
299
        test.setName("Browser Compatibility Test");
300
        
301
        // Add test-specific parameters
302
        test.addParameter("browser", "chrome");
303
        test.addParameter("version", "latest");
304
        test.addParameter("platform", "linux");
305
        
306
        // Configure classes
307
        XmlClass browserTest = new XmlClass("com.example.BrowserCompatibilityTest");
308
        test.addClass(browserTest);
309
        
310
        suite.addTest(test);
311
    }
312
    
313
    public void createGroupedTest() {
314
        XmlSuite suite = new XmlSuite();
315
        suite.setName("Grouped Test Suite");
316
        
317
        XmlTest smokeTest = new XmlTest(suite);
318
        smokeTest.setName("Smoke Tests");
319
        smokeTest.setIncludedGroups(Arrays.asList("smoke", "critical"));
320
        smokeTest.setExcludedGroups(Arrays.asList("slow", "flaky"));
321
        
322
        XmlClass testClass = new XmlClass("com.example.SmokeTest");
323
        smokeTest.addClass(testClass);
324
        
325
        XmlTest regressionTest = new XmlTest(suite);
326
        regressionTest.setName("Regression Tests");
327
        regressionTest.setIncludedGroups(Arrays.asList("regression"));
328
        regressionTest.setExcludedGroups(Arrays.asList("manual"));
329
        
330
        XmlClass regressionClass = new XmlClass("com.example.RegressionTest");
331
        regressionTest.addClass(regressionClass);
332
        
333
        suite.addTest(smokeTest);
334
        suite.addTest(regressionTest);
335
    }
336
    
337
    public void createPackageBasedTest() {
338
        XmlSuite suite = new XmlSuite();
339
        suite.setName("Package-based Suite");
340
        
341
        XmlTest test = new XmlTest(suite);
342
        test.setName("Package Tests");
343
        
344
        // Include entire packages
345
        XmlPackage unitTestPackage = new XmlPackage("com.example.unit.*");
346
        XmlPackage integrationTestPackage = new XmlPackage("com.example.integration.*");
347
        
348
        test.addPackage(unitTestPackage);
349
        test.addPackage(integrationTestPackage);
350
        
351
        suite.addTest(test);
352
    }
353
    
354
    public void createMethodSelectorTest() {
355
        XmlSuite suite = new XmlSuite();
356
        suite.setName("Method Selector Suite");
357
        
358
        XmlTest test = new XmlTest(suite);
359
        test.setName("Selective Method Execution");
360
        
361
        // Create method selector
362
        XmlMethodSelector methodSelector = new XmlMethodSelector();
363
        methodSelector.setClassName("com.example.CustomMethodSelector");
364
        methodSelector.setPriority(1);
365
        
366
        test.setMethodSelectors(Arrays.asList(methodSelector));
367
        
368
        suite.addTest(test);
369
    }
370
}
371
```
372

373
### XmlClass Class
374

375
Represents a test class configuration with specific method inclusion/exclusion and parameter settings.
376

377
```java { .api }
378
/**
379
 * Configuration class for test classes within a test
380
 */
381
public class XmlClass {
382
    
383
    // Constructors
384
    public XmlClass();
385
    public XmlClass(String className);
386
    public XmlClass(Class<?> clazz);
387
    
388
    // Basic configuration
389
    public void setName(String name);
390
    public String getName();
391
    public void setClass(Class<?> clazz);
392
    public Class<?> getSupportClass();
393
    
394
    // Method inclusion/exclusion
395
    public void setIncludedMethods(List<XmlInclude> includedMethods);
396
    public List<XmlInclude> getIncludedMethods();
397
    public void setExcludedMethods(List<String> excludedMethods);
398
    public List<String> getExcludedMethods();
399
    
400
    // Parameters
401
    public void setParameters(Map<String, String> parameters);
402
    public Map<String, String> getParameters();
403
    public void addParameter(String name, String value);
404
    
405
    // Utility methods
406
    public Object clone();
407
    public void setIndex(int index);
408
    public int getIndex();
409
}
410
```
411

412
**Usage Examples:**
413

414
```java
415
public class XmlClassExamples {
416
    
417
    public void createSelectiveMethodExecution() {
418
        XmlSuite suite = new XmlSuite();
419
        suite.setName("Selective Method Suite");
420
        
421
        XmlTest test = new XmlTest(suite);
422
        test.setName("Specific Methods Only");
423
        
424
        XmlClass xmlClass = new XmlClass("com.example.CompleteTestClass");
425
        
426
        // Include only specific methods
427
        XmlInclude method1 = new XmlInclude("testCriticalFeature");
428
        XmlInclude method2 = new XmlInclude("testSecurityValidation");
429
        XmlInclude method3 = new XmlInclude("testPerformance");
430
        
431
        xmlClass.setIncludedMethods(Arrays.asList(method1, method2, method3));
432
        
433
        // Exclude flaky methods
434
        xmlClass.setExcludedMethods(Arrays.asList("testFlakyBehavior", "testUnstableFeature"));
435
        
436
        // Add class-specific parameters
437
        xmlClass.addParameter("testData", "critical-data.json");
438
        xmlClass.addParameter("timeout", "30000");
439
        
440
        test.addClass(xmlClass);
441
        suite.addTest(test);
442
    }
443
    
444
    public void createParameterizedMethodExecution() {
445
        XmlSuite suite = new XmlSuite();
446
        suite.setName("Parameterized Method Suite");
447
        
448
        XmlTest test = new XmlTest(suite);
449
        test.setName("Data-Driven Tests");
450
        
451
        XmlClass xmlClass = new XmlClass("com.example.DataDrivenTest");
452
        
453
        // Include parameterized methods with invocation numbers
454
        XmlInclude parameterizedMethod = new XmlInclude("testWithMultipleDataSets");
455
        parameterizedMethod.setInvocationNumbers(Arrays.asList(0, 2, 4)); // Run only specific data sets
456
        
457
        xmlClass.setIncludedMethods(Arrays.asList(parameterizedMethod));
458
        
459
        test.addClass(xmlClass);
460
        suite.addTest(test);
461
    }
462
}
463
```
464

465
### XML Configuration File Structure
466

467
Complete XML configuration file examples showing real-world usage patterns.
468

469
```xml
470
<!-- Basic TestNG Suite Configuration -->
471
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
472
<suite name="Complete Test Suite" verbose="1" preserve-order="true">
473
    
474
    <!-- Suite-level parameters -->
475
    <parameter name="environment" value="staging"/>
476
    <parameter name="browser" value="chrome"/>
477
    <parameter name="timeout" value="30000"/>
478
    
479
    <!-- Suite-level listeners -->
480
    <listeners>
481
        <listener class-name="com.example.CustomTestListener"/>
482
        <listener class-name="com.example.EmailReporter"/>
483
    </listeners>
484
    
485
    <!-- Group definitions -->
486
    <groups>
487
        <run>
488
            <include name="smoke"/>
489
            <include name="regression"/>
490
            <exclude name="manual"/>
491
            <exclude name="flaky"/>
492
        </run>
493
        <dependencies>
494
            <group name="regression" depends-on="smoke"/>
495
            <group name="integration" depends-on="unit"/>
496
        </dependencies>
497
    </groups>
498
    
499
    <!-- Test definitions -->
500
    <test name="Smoke Tests" preserve-order="true">
501
        <parameter name="testType" value="smoke"/>
502
        <groups>
503
            <run>
504
                <include name="smoke"/>
505
                <include name="critical"/>
506
            </run>
507
        </groups>
508
        <classes>
509
            <class name="com.example.LoginTest"/>
510
            <class name="com.example.HomePageTest">
511
                <methods>
512
                    <include name="testPageLoad"/>
513
                    <include name="testNavigation"/>
514
                    <exclude name="testSlowFeature"/>
515
                </methods>
516
            </class>
517
        </classes>
518
    </test>
519
    
520
    <test name="Regression Tests" parallel="methods" thread-count="3">
521
        <parameter name="testType" value="regression"/>
522
        <groups>
523
            <run>
524
                <include name="regression"/>
525
            </run>
526
        </groups>
527
        <packages>
528
            <package name="com.example.regression.*"/>
529
        </packages>
530
    </test>
531
    
532
</suite>
533
```
534

535
```xml
536
<!-- Parallel Execution Configuration -->
537
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
538
<suite name="Parallel Suite" parallel="methods" thread-count="4" 
539
       data-provider-thread-count="2" preserve-order="false">
540
    
541
    <parameter name="parallel" value="true"/>
542
    
543
    <test name="Parallel Method Execution" parallel="methods" thread-count="2">
544
        <classes>
545
            <class name="com.example.ParallelTest1"/>
546
            <class name="com.example.ParallelTest2"/>
547
        </classes>
548
    </test>
549
    
550
    <test name="Parallel Class Execution" parallel="classes" thread-count="2">
551
        <classes>
552
            <class name="com.example.ClassParallelTest1"/>
553
            <class name="com.example.ClassParallelTest2"/>
554
        </classes>
555
    </test>
556
    
557
</suite>
558
```
559

560
```xml
561
<!-- Suite of Suites Configuration -->
562
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
563
<suite name="Master Suite" parallel="tests" thread-count="3">
564
    
565
    <suite-files>
566
        <suite-file path="smoke-tests.xml"/>
567
        <suite-file path="regression-tests.xml"/>
568
        <suite-file path="integration-tests.xml"/>
569
    </suite-files>
570
    
571
</suite>
572
```
573

574
## Types
575

576
```java { .api }
577
// Supporting configuration classes
578
public class XmlGroups {
579
    public void setRun(XmlRun run);
580
    public XmlRun getRun();
581
    public void setDependencies(XmlDependencies dependencies);
582
    public XmlDependencies getDependencies();
583
}
584

585
public class XmlRun {
586
    public void onInclude(String name);
587
    public void onExclude(String name);
588
    public List<String> getIncludes();
589
    public List<String> getExcludes();
590
}
591

592
public class XmlDependencies {
593
    public void setDependencies(Map<String, String> dependencies);
594
    public Map<String, String> getDependencies();
595
}
596

597
public class XmlInclude {
598
    public XmlInclude(String name);
599
    public void setName(String name);
600
    public String getName();
601
    public void setInvocationNumbers(List<Integer> invocationNumbers);
602
    public List<Integer> getInvocationNumbers();
603
    public void setDescription(String description);
604
    public String getDescription();
605
}
606

607
public class XmlPackage {
608
    public XmlPackage(String name);
609
    public void setName(String name);
610
    public String getName();
611
    public void setInclude(List<String> include);
612
    public List<String> getInclude();
613
    public void setExclude(List<String> exclude);
614
    public List<String> getExclude();
615
}
616

617
public class XmlMethodSelector {
618
    public void setClassName(String className);
619
    public String getClassName();
620
    public void setPriority(int priority);
621
    public int getPriority();
622
    public void setScript(XmlScript script);
623
    public XmlScript getScript();
624
}
625

626
public class XmlScript {
627
    public void setLanguage(String language);
628
    public String getLanguage();
629
    public void setScript(String script);
630
    public String getScript();
631
}
632
```