xref: /aosp_15_r20/external/testng/doc/documentation-main.html (revision 83a54b2f2026052c38867f4cde56111edcd60b56)
1*83a54b2fSSadaf Ebrahimi<html>
2*83a54b2fSSadaf Ebrahimi    <head>
3*83a54b2fSSadaf Ebrahimi        <title>TestNG</title>
4*83a54b2fSSadaf Ebrahimi
5*83a54b2fSSadaf Ebrahimi        <link rel="stylesheet" href="testng.css" type="text/css" />
6*83a54b2fSSadaf Ebrahimi        <link type="text/css" rel="stylesheet" href="http://beust.com/beust.css"  />
7*83a54b2fSSadaf Ebrahimi        <script type="text/javascript" src="banner.js"></script>
8*83a54b2fSSadaf Ebrahimi
9*83a54b2fSSadaf Ebrahimi      <script type="text/javascript" src="http://beust.com/scripts/shCore.js"></script>
10*83a54b2fSSadaf Ebrahimi      <script type="text/javascript" src="http://beust.com/scripts/shBrushJava.js"></script>
11*83a54b2fSSadaf Ebrahimi      <script type="text/javascript" src="http://beust.com/scripts/shBrushXml.js"></script>
12*83a54b2fSSadaf Ebrahimi      <script type="text/javascript" src="http://beust.com/scripts/shBrushBash.js"></script>
13*83a54b2fSSadaf Ebrahimi      <script type="text/javascript" src="http://beust.com/scripts/shBrushPlain.js"></script>
14*83a54b2fSSadaf Ebrahimi      <link type="text/css" rel="stylesheet" href="http://beust.com/styles/shCore.css"/>
15*83a54b2fSSadaf Ebrahimi      <link type="text/css" rel="stylesheet" href="http://beust.com/styles/shThemeCedric.css"/>
16*83a54b2fSSadaf Ebrahimi      <script type="text/javascript">
17*83a54b2fSSadaf Ebrahimi        SyntaxHighlighter.config.clipboardSwf = 'scripts/clipboard.swf';
18*83a54b2fSSadaf Ebrahimi        SyntaxHighlighter.defaults['gutter'] = false;
19*83a54b2fSSadaf Ebrahimi        SyntaxHighlighter.all();
20*83a54b2fSSadaf Ebrahimi      </script>
21*83a54b2fSSadaf Ebrahimi      <script type="text/javascript" src="http://beust.com/toc.js"></script>
22*83a54b2fSSadaf Ebrahimi
23*83a54b2fSSadaf Ebrahimi        <style type="text/css">
24*83a54b2fSSadaf Ebrahimi            /* Set the command-line table option column width. */
25*83a54b2fSSadaf Ebrahimi            #command-line colgroup.option {
26*83a54b2fSSadaf Ebrahimi                 width: 7em;
27*83a54b2fSSadaf Ebrahimi            }
28*83a54b2fSSadaf Ebrahimi        </style>
29*83a54b2fSSadaf Ebrahimi    </head>
30*83a54b2fSSadaf Ebrahimi<body onLoad="generateToc();">
31*83a54b2fSSadaf Ebrahimi
32*83a54b2fSSadaf Ebrahimi<script type="text/javascript">
33*83a54b2fSSadaf Ebrahimi    displayMenu("documentation-main.html")
34*83a54b2fSSadaf Ebrahimi</script>
35*83a54b2fSSadaf Ebrahimi
36*83a54b2fSSadaf Ebrahimi<h2 align="center">TestNG</h2>
37*83a54b2fSSadaf Ebrahimi
38*83a54b2fSSadaf Ebrahimi<!-- --------------------------
39*83a54b2fSSadaf Ebrahimi
40*83a54b2fSSadaf Ebrahimi<table class="float-right">
41*83a54b2fSSadaf Ebrahimi  <tr>
42*83a54b2fSSadaf Ebrahimi    <td>
43*83a54b2fSSadaf Ebrahimi<script type="text/javascript"><!--
44*83a54b2fSSadaf Ebrahimigoogle_ad_client = "pub-1467757024002850";
45*83a54b2fSSadaf Ebrahimigoogle_ad_width = 120;
46*83a54b2fSSadaf Ebrahimigoogle_ad_height = 600;
47*83a54b2fSSadaf Ebrahimigoogle_ad_format = "120x600_as";
48*83a54b2fSSadaf Ebrahimigoogle_ad_channel ="5560744946";
49*83a54b2fSSadaf Ebrahimi//-->
50*83a54b2fSSadaf Ebrahimi<!--
51*83a54b2fSSadaf Ebrahimi
52*83a54b2fSSadaf Ebrahimi</script>
53*83a54b2fSSadaf Ebrahimi
54*83a54b2fSSadaf Ebrahimi<script type="text/javascript"
55*83a54b2fSSadaf Ebrahimi  src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
56*83a54b2fSSadaf Ebrahimi</script>
57*83a54b2fSSadaf Ebrahimi    </td>
58*83a54b2fSSadaf Ebrahimi  </tr>
59*83a54b2fSSadaf Ebrahimi</table>
60*83a54b2fSSadaf Ebrahimi
61*83a54b2fSSadaf Ebrahimi------------------------------- -->
62*83a54b2fSSadaf Ebrahimi
63*83a54b2fSSadaf Ebrahimi<!-------------------------------------
64*83a54b2fSSadaf Ebrahimi  TOC
65*83a54b2fSSadaf Ebrahimi  ------------------------------------>
66*83a54b2fSSadaf Ebrahimi
67*83a54b2fSSadaf Ebrahimi<h3>Table of Contents</h3>
68*83a54b2fSSadaf Ebrahimi
69*83a54b2fSSadaf Ebrahimi<div id="table-of-contents">
70*83a54b2fSSadaf Ebrahimi</div>
71*83a54b2fSSadaf Ebrahimi
72*83a54b2fSSadaf Ebrahimi
73*83a54b2fSSadaf Ebrahimi<!-------------------------------------
74*83a54b2fSSadaf Ebrahimi  INTRODUCTION
75*83a54b2fSSadaf Ebrahimi  ------------------------------------>
76*83a54b2fSSadaf Ebrahimi<h3><a class="section" name="introduction">Introduction</a></h3>
77*83a54b2fSSadaf Ebrahimi
78*83a54b2fSSadaf EbrahimiTestNG is a testing framework designed to simplify a broad range of testing needs, from unit testing (testing a class in isolation of the others) to integration testing (testing entire systems made of several classes, several packages and even several external frameworks, such as application servers).
79*83a54b2fSSadaf Ebrahimi
80*83a54b2fSSadaf Ebrahimi<p>
81*83a54b2fSSadaf Ebrahimi
82*83a54b2fSSadaf EbrahimiWriting a test is typically a three-step process:
83*83a54b2fSSadaf Ebrahimi
84*83a54b2fSSadaf Ebrahimi<ul>
85*83a54b2fSSadaf Ebrahimi<li>Write the business logic of your test and insert <a href="#annotations">TestNG annotations</a> in your code.
86*83a54b2fSSadaf Ebrahimi</li>
87*83a54b2fSSadaf Ebrahimi<li>Add the information about your test (e.g. the class name, the groups you wish to run, etc...) in a <tt><a href="#testng-xml">testng.xml</a></tt> file or in build.xml.
88*83a54b2fSSadaf Ebrahimi</li>
89*83a54b2fSSadaf Ebrahimi<li><a href="ant.html">Run TestNG</a>.
90*83a54b2fSSadaf Ebrahimi</li>
91*83a54b2fSSadaf Ebrahimi</ul>
92*83a54b2fSSadaf EbrahimiYou can find a quick example on the <a href="index.html">Welcome page</a>.
93*83a54b2fSSadaf Ebrahimi<p>
94*83a54b2fSSadaf EbrahimiThe concepts used in this documentation are as follows:
95*83a54b2fSSadaf Ebrahimi
96*83a54b2fSSadaf Ebrahimi<ul>
97*83a54b2fSSadaf Ebrahimi<li>
98*83a54b2fSSadaf EbrahimiA suite is represented by one XML file.  It can contain one or more tests and is defined by the <tt>&lt;suite&gt;</tt> tag.
99*83a54b2fSSadaf Ebrahimi</li>
100*83a54b2fSSadaf Ebrahimi<li>
101*83a54b2fSSadaf EbrahimiA test is represented by <tt>&lt;test&gt;</tt> and can contain one or more TestNG classes.
102*83a54b2fSSadaf Ebrahimi</li>
103*83a54b2fSSadaf Ebrahimi<li>
104*83a54b2fSSadaf EbrahimiA TestNG class is a Java class that contains at least one TestNG annotation.  It is represented by the <tt>&lt;class&gt;</tt> tag and can contain one or more test methods.
105*83a54b2fSSadaf Ebrahimi</li>
106*83a54b2fSSadaf Ebrahimi<li>
107*83a54b2fSSadaf EbrahimiA test method is a Java method annotated by <tt>@Test</tt> in your source.
108*83a54b2fSSadaf Ebrahimi</li></ul>A TestNG test can be configured by <tt>@BeforeXXX and @AfterXXX </tt>annotations which allows to perform some Java logic before and after a certain point, these points being either of the items listed above.<p>
109*83a54b2fSSadaf EbrahimiThe rest of this manual will explain the following:
110*83a54b2fSSadaf Ebrahimi<p>
111*83a54b2fSSadaf Ebrahimi<ul>
112*83a54b2fSSadaf Ebrahimi<li>A list of all the annotations with a brief explanation.  This will give you an idea of the various functionalities offered by TestNG but you will probably want to consult the section dedicated to each of these annotations to learn the details.
113*83a54b2fSSadaf Ebrahimi</li>
114*83a54b2fSSadaf Ebrahimi<li>A description of the testng.xml file, its syntax and what you can specify in it.
115*83a54b2fSSadaf Ebrahimi</li>
116*83a54b2fSSadaf Ebrahimi<li>A detailed list of the various features and how to use them with a combination of annotations and testng.xml.
117*83a54b2fSSadaf Ebrahimi</li>
118*83a54b2fSSadaf Ebrahimi</ul>
119*83a54b2fSSadaf Ebrahimi
120*83a54b2fSSadaf Ebrahimi
121*83a54b2fSSadaf Ebrahimi<!-------------------------------------
122*83a54b2fSSadaf Ebrahimi  ANNOTATIONS
123*83a54b2fSSadaf Ebrahimi  ------------------------------------>
124*83a54b2fSSadaf Ebrahimi
125*83a54b2fSSadaf Ebrahimi<h3><a class="section" name="annotations">Annotations</a></h3>
126*83a54b2fSSadaf Ebrahimi
127*83a54b2fSSadaf EbrahimiHere is a quick overview of the annotations available in TestNG along with their attributes.
128*83a54b2fSSadaf Ebrahimi
129*83a54b2fSSadaf Ebrahimi<p>
130*83a54b2fSSadaf Ebrahimi
131*83a54b2fSSadaf Ebrahimi<table>
132*83a54b2fSSadaf Ebrahimi
133*83a54b2fSSadaf Ebrahimi<tr>
134*83a54b2fSSadaf Ebrahimi<td colspan="2"><b><tt>@BeforeSuite<br>@AfterSuite<br>@BeforeTest<br>@AfterTest<br>@BeforeGroups<br>@AfterGroups<br>@BeforeClass<br>@AfterClass<br>@BeforeMethod<br>@AfterMethod</tt></b></td><td><b>Configuration information for a TestNG class:</b>
135*83a54b2fSSadaf Ebrahimi
136*83a54b2fSSadaf Ebrahimi<br>
137*83a54b2fSSadaf Ebrahimi
138*83a54b2fSSadaf Ebrahimi<br><b>@BeforeSuite: </b>The annotated method will be run before all tests in this suite have run.
139*83a54b2fSSadaf Ebrahimi
140*83a54b2fSSadaf Ebrahimi<br><b>@AfterSuite: </b> The annotated method will be run after all tests in this suite have run.
141*83a54b2fSSadaf Ebrahimi
142*83a54b2fSSadaf Ebrahimi<br><b>@BeforeTest</b>: The annotated method will be run before any test method belonging to the classes inside the &lt;test&gt; tag is run.
143*83a54b2fSSadaf Ebrahimi
144*83a54b2fSSadaf Ebrahimi<br><b>@AfterTest</b>: The annotated method will be run after all the test methods belonging to the classes inside the &lt;test&gt; tag have run.
145*83a54b2fSSadaf Ebrahimi
146*83a54b2fSSadaf Ebrahimi<br><b>@BeforeGroups</b>:   The list of groups that this configuration method will run before. This method is guaranteed to run shortly before the first test method that belongs to any of these groups is invoked.
147*83a54b2fSSadaf Ebrahimi
148*83a54b2fSSadaf Ebrahimi<br><b>@AfterGroups</b>:   The list of groups that this configuration method will run after.  This method is guaranteed to run shortly after the last test method that belongs to any of these groups is invoked.
149*83a54b2fSSadaf Ebrahimi
150*83a54b2fSSadaf Ebrahimi<br><b>@BeforeClass</b>: The annotated method will be run before the first test method in the current class is invoked.
151*83a54b2fSSadaf Ebrahimi
152*83a54b2fSSadaf Ebrahimi<br><b>@AfterClass</b>: The annotated method will be run after all the test methods in the current class have been run.
153*83a54b2fSSadaf Ebrahimi
154*83a54b2fSSadaf Ebrahimi<br><b>@BeforeMethod</b>: The annotated method will be run before each test method.
155*83a54b2fSSadaf Ebrahimi
156*83a54b2fSSadaf Ebrahimi<br><b>@AfterMethod</b>: The annotated method will be run after each test method.
157*83a54b2fSSadaf Ebrahimi
158*83a54b2fSSadaf Ebrahimi</td>
159*83a54b2fSSadaf Ebrahimi</tr>
160*83a54b2fSSadaf Ebrahimi
161*83a54b2fSSadaf Ebrahimi<tr>
162*83a54b2fSSadaf Ebrahimi<td>
163*83a54b2fSSadaf Ebrahimi</td>
164*83a54b2fSSadaf Ebrahimi<td>
165*83a54b2fSSadaf Ebrahimi<tt>alwaysRun</tt>
166*83a54b2fSSadaf Ebrahimi</td>
167*83a54b2fSSadaf Ebrahimi<td>
168*83a54b2fSSadaf Ebrahimi   For before methods (beforeSuite, beforeTest, beforeTestClass and
169*83a54b2fSSadaf Ebrahimi   beforeTestMethod, but not beforeGroups):
170*83a54b2fSSadaf Ebrahimi   If set to true, this configuration method will be run
171*83a54b2fSSadaf Ebrahimi   regardless of what groups it belongs to.
172*83a54b2fSSadaf Ebrahimi   <br>
173*83a54b2fSSadaf Ebrahimi   For after methods (afterSuite, afterClass, ...):
174*83a54b2fSSadaf Ebrahimi   If set to true, this configuration method will be run
175*83a54b2fSSadaf Ebrahimi   even if one or more methods invoked previously failed or
176*83a54b2fSSadaf Ebrahimi   was skipped.
177*83a54b2fSSadaf Ebrahimi</td>
178*83a54b2fSSadaf Ebrahimi</tr>
179*83a54b2fSSadaf Ebrahimi
180*83a54b2fSSadaf Ebrahimi<tr>
181*83a54b2fSSadaf Ebrahimi<td>
182*83a54b2fSSadaf Ebrahimi</td>
183*83a54b2fSSadaf Ebrahimi<td>
184*83a54b2fSSadaf Ebrahimi<tt>dependsOnGroups</tt>
185*83a54b2fSSadaf Ebrahimi</td>
186*83a54b2fSSadaf Ebrahimi<td>
187*83a54b2fSSadaf Ebrahimi          The list of groups this method depends on.
188*83a54b2fSSadaf Ebrahimi</td>
189*83a54b2fSSadaf Ebrahimi</tr>
190*83a54b2fSSadaf Ebrahimi
191*83a54b2fSSadaf Ebrahimi<tr>
192*83a54b2fSSadaf Ebrahimi<td>
193*83a54b2fSSadaf Ebrahimi</td>
194*83a54b2fSSadaf Ebrahimi<td>
195*83a54b2fSSadaf Ebrahimi<tt>dependsOnMethods</tt>
196*83a54b2fSSadaf Ebrahimi</td>
197*83a54b2fSSadaf Ebrahimi<td>
198*83a54b2fSSadaf Ebrahimi          The list of methods this method depends on.
199*83a54b2fSSadaf Ebrahimi</td>
200*83a54b2fSSadaf Ebrahimi</tr>
201*83a54b2fSSadaf Ebrahimi
202*83a54b2fSSadaf Ebrahimi<tr>
203*83a54b2fSSadaf Ebrahimi<td>
204*83a54b2fSSadaf Ebrahimi</td>
205*83a54b2fSSadaf Ebrahimi<td>
206*83a54b2fSSadaf Ebrahimi<tt>enabled</tt>
207*83a54b2fSSadaf Ebrahimi</td>
208*83a54b2fSSadaf Ebrahimi<td>
209*83a54b2fSSadaf Ebrahimi          Whether methods on this class/method are enabled.
210*83a54b2fSSadaf Ebrahimi</td>
211*83a54b2fSSadaf Ebrahimi</tr>
212*83a54b2fSSadaf Ebrahimi
213*83a54b2fSSadaf Ebrahimi<tr>
214*83a54b2fSSadaf Ebrahimi<td>
215*83a54b2fSSadaf Ebrahimi</td>
216*83a54b2fSSadaf Ebrahimi<td>
217*83a54b2fSSadaf Ebrahimi<tt>groups</tt>
218*83a54b2fSSadaf Ebrahimi</td>
219*83a54b2fSSadaf Ebrahimi<td>
220*83a54b2fSSadaf Ebrahimi          The list of groups this class/method belongs to.
221*83a54b2fSSadaf Ebrahimi</td>
222*83a54b2fSSadaf Ebrahimi</tr>
223*83a54b2fSSadaf Ebrahimi
224*83a54b2fSSadaf Ebrahimi<tr>
225*83a54b2fSSadaf Ebrahimi<td>
226*83a54b2fSSadaf Ebrahimi</td>
227*83a54b2fSSadaf Ebrahimi<td>
228*83a54b2fSSadaf Ebrahimi<tt>inheritGroups</tt>
229*83a54b2fSSadaf Ebrahimi</td>
230*83a54b2fSSadaf Ebrahimi<td>
231*83a54b2fSSadaf Ebrahimi          If true, this method will belong to groups specified in the @Test annotation at the class level.
232*83a54b2fSSadaf Ebrahimi</td>
233*83a54b2fSSadaf Ebrahimi</tr>
234*83a54b2fSSadaf Ebrahimi
235*83a54b2fSSadaf Ebrahimi<tr class="separator">
236*83a54b2fSSadaf Ebrahimi<td colspan="3">&nbsp;</td>
237*83a54b2fSSadaf Ebrahimi</tr>
238*83a54b2fSSadaf Ebrahimi
239*83a54b2fSSadaf Ebrahimi<tr>
240*83a54b2fSSadaf Ebrahimi<td colspan="2"><tt><b>@DataProvider</b></tt></td><td><b>Marks a method as supplying data for a test method. The annotated method must return an Object[][] where each Object[] can be assigned the parameter list of the test method. The @Test method that wants to receive data from this DataProvider needs to use a dataProvider name equals to the name of this annotation.</b></td></tr><tr>
241*83a54b2fSSadaf Ebrahimi<td>
242*83a54b2fSSadaf Ebrahimi</td>
243*83a54b2fSSadaf Ebrahimi<td>
244*83a54b2fSSadaf Ebrahimi<tt>name</tt>
245*83a54b2fSSadaf Ebrahimi</td>
246*83a54b2fSSadaf Ebrahimi<td>
247*83a54b2fSSadaf EbrahimiThe name of this data provider. If it's not supplied, the name of this data provider will automatically be set to the name of the method.
248*83a54b2fSSadaf Ebrahimi</td>
249*83a54b2fSSadaf Ebrahimi</tr>
250*83a54b2fSSadaf Ebrahimi<tr>
251*83a54b2fSSadaf Ebrahimi<td>
252*83a54b2fSSadaf Ebrahimi</td>
253*83a54b2fSSadaf Ebrahimi<td>
254*83a54b2fSSadaf Ebrahimi<tt>parallel</tt>
255*83a54b2fSSadaf Ebrahimi</td>
256*83a54b2fSSadaf Ebrahimi<td>
257*83a54b2fSSadaf EbrahimiIf set to true, tests generated using this data provider are run in parallel. Default value is false.
258*83a54b2fSSadaf Ebrahimi</td>
259*83a54b2fSSadaf Ebrahimi</tr>
260*83a54b2fSSadaf Ebrahimi<tr>
261*83a54b2fSSadaf Ebrahimi<td colspan="3">&nbsp;</td>
262*83a54b2fSSadaf Ebrahimi</tr>
263*83a54b2fSSadaf Ebrahimi
264*83a54b2fSSadaf Ebrahimi<tr>
265*83a54b2fSSadaf Ebrahimi<td colspan="2"><b><tt>@Factory</tt></b></td><td><b> Marks a method as a factory that returns objects that will be used by TestNG as Test classes.  The method must return Object[].</b></td></tr><tr>
266*83a54b2fSSadaf Ebrahimi<td colspan="3">&nbsp;</td>
267*83a54b2fSSadaf Ebrahimi</tr>
268*83a54b2fSSadaf Ebrahimi
269*83a54b2fSSadaf Ebrahimi<tr>
270*83a54b2fSSadaf Ebrahimi<td colspan="2"><b><tt>@Listeners</tt></b></td><td><b>Defines listeners on a test class.</b></td></tr>
271*83a54b2fSSadaf Ebrahimi<tr>
272*83a54b2fSSadaf Ebrahimi  <td></td>
273*83a54b2fSSadaf Ebrahimi  <td>
274*83a54b2fSSadaf Ebrahimi    <tt>value</tt>
275*83a54b2fSSadaf Ebrahimi  </td>
276*83a54b2fSSadaf Ebrahimi  <td>
277*83a54b2fSSadaf Ebrahimi    An array of classes that extend <tt>org.testng.ITestNGListener</tt>.
278*83a54b2fSSadaf Ebrahimi  </td>
279*83a54b2fSSadaf Ebrahimi</tr>
280*83a54b2fSSadaf Ebrahimi
281*83a54b2fSSadaf Ebrahimi<tr>
282*83a54b2fSSadaf Ebrahimi<td colspan="3">&nbsp;</td>
283*83a54b2fSSadaf Ebrahimi</tr>
284*83a54b2fSSadaf Ebrahimi
285*83a54b2fSSadaf Ebrahimi<td colspan="2"><b><tt>@Parameters</tt></b></td><td><b>Describes how to pass parameters to a @Test method.</b></td></tr><tr>
286*83a54b2fSSadaf Ebrahimi<td>
287*83a54b2fSSadaf Ebrahimi</td>
288*83a54b2fSSadaf Ebrahimi<td>
289*83a54b2fSSadaf Ebrahimi<tt>value</tt>
290*83a54b2fSSadaf Ebrahimi</td>
291*83a54b2fSSadaf Ebrahimi<td>
292*83a54b2fSSadaf EbrahimiThe list of variables used to fill the parameters of this method.
293*83a54b2fSSadaf Ebrahimi</td>
294*83a54b2fSSadaf Ebrahimi</tr>
295*83a54b2fSSadaf Ebrahimi
296*83a54b2fSSadaf Ebrahimi<tr>
297*83a54b2fSSadaf Ebrahimi<td colspan="3">&nbsp;</td>
298*83a54b2fSSadaf Ebrahimi</tr>
299*83a54b2fSSadaf Ebrahimi
300*83a54b2fSSadaf Ebrahimi<tr>
301*83a54b2fSSadaf Ebrahimi<td colspan="2"><b>@Test</b></td><td><b>Marks a class or a method as part of the test.</b></td></tr><tr>
302*83a54b2fSSadaf Ebrahimi<td>
303*83a54b2fSSadaf Ebrahimi</td>
304*83a54b2fSSadaf Ebrahimi<td>
305*83a54b2fSSadaf Ebrahimi<tt>alwaysRun</tt>
306*83a54b2fSSadaf Ebrahimi</td>
307*83a54b2fSSadaf Ebrahimi<td>
308*83a54b2fSSadaf Ebrahimi          If set to true, this test method will always be run even if it depends on a method that failed.
309*83a54b2fSSadaf Ebrahimi</td>
310*83a54b2fSSadaf Ebrahimi</tr>
311*83a54b2fSSadaf Ebrahimi
312*83a54b2fSSadaf Ebrahimi<tr>
313*83a54b2fSSadaf Ebrahimi<td>
314*83a54b2fSSadaf Ebrahimi</td>
315*83a54b2fSSadaf Ebrahimi<td>
316*83a54b2fSSadaf Ebrahimi<tt>dataProvider</tt>
317*83a54b2fSSadaf Ebrahimi</td>
318*83a54b2fSSadaf Ebrahimi<td>
319*83a54b2fSSadaf EbrahimiThe name of the data provider for this test method.
320*83a54b2fSSadaf Ebrahimi</td>
321*83a54b2fSSadaf Ebrahimi</tr>
322*83a54b2fSSadaf Ebrahimi
323*83a54b2fSSadaf Ebrahimi
324*83a54b2fSSadaf Ebrahimi<tr>
325*83a54b2fSSadaf Ebrahimi<td>
326*83a54b2fSSadaf Ebrahimi</td>
327*83a54b2fSSadaf Ebrahimi<td>
328*83a54b2fSSadaf Ebrahimi<tt>dataProviderClass</tt>
329*83a54b2fSSadaf Ebrahimi</td>
330*83a54b2fSSadaf Ebrahimi<td>
331*83a54b2fSSadaf EbrahimiThe class where to look for the data provider.  If not specified, the data provider will be looked on the class of the current test method or one of its base classes. If this attribute is specified, the data provider method needs to be static on the specified class.
332*83a54b2fSSadaf Ebrahimi</td>
333*83a54b2fSSadaf Ebrahimi</tr>
334*83a54b2fSSadaf Ebrahimi
335*83a54b2fSSadaf Ebrahimi
336*83a54b2fSSadaf Ebrahimi
337*83a54b2fSSadaf Ebrahimi
338*83a54b2fSSadaf Ebrahimi
339*83a54b2fSSadaf Ebrahimi
340*83a54b2fSSadaf Ebrahimi<tr>
341*83a54b2fSSadaf Ebrahimi<td>
342*83a54b2fSSadaf Ebrahimi</td>
343*83a54b2fSSadaf Ebrahimi<td>
344*83a54b2fSSadaf Ebrahimi<tt>dependsOnGroups</tt>
345*83a54b2fSSadaf Ebrahimi</td>
346*83a54b2fSSadaf Ebrahimi<td>
347*83a54b2fSSadaf Ebrahimi          The list of groups this method depends on.
348*83a54b2fSSadaf Ebrahimi</td>
349*83a54b2fSSadaf Ebrahimi</tr>
350*83a54b2fSSadaf Ebrahimi
351*83a54b2fSSadaf Ebrahimi<tr>
352*83a54b2fSSadaf Ebrahimi<td>
353*83a54b2fSSadaf Ebrahimi</td>
354*83a54b2fSSadaf Ebrahimi<td>
355*83a54b2fSSadaf Ebrahimi<tt>dependsOnMethods</tt>
356*83a54b2fSSadaf Ebrahimi</td>
357*83a54b2fSSadaf Ebrahimi<td>
358*83a54b2fSSadaf Ebrahimi          The list of methods this method depends on.
359*83a54b2fSSadaf Ebrahimi</td>
360*83a54b2fSSadaf Ebrahimi</tr>
361*83a54b2fSSadaf Ebrahimi
362*83a54b2fSSadaf Ebrahimi<tr>
363*83a54b2fSSadaf Ebrahimi<td>
364*83a54b2fSSadaf Ebrahimi</td>
365*83a54b2fSSadaf Ebrahimi<td>
366*83a54b2fSSadaf Ebrahimi<tt>description</tt>
367*83a54b2fSSadaf Ebrahimi</td>
368*83a54b2fSSadaf Ebrahimi<td>
369*83a54b2fSSadaf Ebrahimi          The description for this method.
370*83a54b2fSSadaf Ebrahimi</td>
371*83a54b2fSSadaf Ebrahimi</tr>
372*83a54b2fSSadaf Ebrahimi
373*83a54b2fSSadaf Ebrahimi<tr>
374*83a54b2fSSadaf Ebrahimi<td>
375*83a54b2fSSadaf Ebrahimi</td>
376*83a54b2fSSadaf Ebrahimi<td>
377*83a54b2fSSadaf Ebrahimi<tt>enabled</tt>
378*83a54b2fSSadaf Ebrahimi</td>
379*83a54b2fSSadaf Ebrahimi<td>
380*83a54b2fSSadaf Ebrahimi          Whether methods on this class/method are enabled.
381*83a54b2fSSadaf Ebrahimi</td>
382*83a54b2fSSadaf Ebrahimi</tr>
383*83a54b2fSSadaf Ebrahimi
384*83a54b2fSSadaf Ebrahimi<tr>
385*83a54b2fSSadaf Ebrahimi<td>
386*83a54b2fSSadaf Ebrahimi</td>
387*83a54b2fSSadaf Ebrahimi<td>
388*83a54b2fSSadaf Ebrahimi<tt>expectedExceptions</tt>
389*83a54b2fSSadaf Ebrahimi</td>
390*83a54b2fSSadaf Ebrahimi<td>
391*83a54b2fSSadaf Ebrahimi           The list of exceptions that a test method is expected to throw.  If no exception or a different than one on this list is thrown, this test will be marked a failure.
392*83a54b2fSSadaf Ebrahimi</td>
393*83a54b2fSSadaf Ebrahimi</tr>
394*83a54b2fSSadaf Ebrahimi
395*83a54b2fSSadaf Ebrahimi<tr>
396*83a54b2fSSadaf Ebrahimi<td>
397*83a54b2fSSadaf Ebrahimi</td>
398*83a54b2fSSadaf Ebrahimi<td>
399*83a54b2fSSadaf Ebrahimi<tt>groups</tt>
400*83a54b2fSSadaf Ebrahimi</td>
401*83a54b2fSSadaf Ebrahimi<td>
402*83a54b2fSSadaf Ebrahimi          The list of groups this class/method belongs to.
403*83a54b2fSSadaf Ebrahimi</td>
404*83a54b2fSSadaf Ebrahimi</tr>
405*83a54b2fSSadaf Ebrahimi
406*83a54b2fSSadaf Ebrahimi<tr>
407*83a54b2fSSadaf Ebrahimi<td>
408*83a54b2fSSadaf Ebrahimi</td>
409*83a54b2fSSadaf Ebrahimi<td>
410*83a54b2fSSadaf Ebrahimi<tt>invocationCount</tt>
411*83a54b2fSSadaf Ebrahimi</td>
412*83a54b2fSSadaf Ebrahimi<td>
413*83a54b2fSSadaf Ebrahimi          The number of times this method should be invoked.
414*83a54b2fSSadaf Ebrahimi</td>
415*83a54b2fSSadaf Ebrahimi</tr>
416*83a54b2fSSadaf Ebrahimi
417*83a54b2fSSadaf Ebrahimi<tr>
418*83a54b2fSSadaf Ebrahimi<td>
419*83a54b2fSSadaf Ebrahimi</td>
420*83a54b2fSSadaf Ebrahimi<td>
421*83a54b2fSSadaf Ebrahimi<tt>invocationTimeOut</tt>
422*83a54b2fSSadaf Ebrahimi</td>
423*83a54b2fSSadaf Ebrahimi<td>
424*83a54b2fSSadaf Ebrahimi          The maximum number of milliseconds this test should take for the cumulated time of all the invocationcounts.  This attribute will be ignored if invocationCount is not specified.
425*83a54b2fSSadaf Ebrahimi</td>
426*83a54b2fSSadaf Ebrahimi</tr>
427*83a54b2fSSadaf Ebrahimi
428*83a54b2fSSadaf Ebrahimi<tr>
429*83a54b2fSSadaf Ebrahimi<td>
430*83a54b2fSSadaf Ebrahimi</td>
431*83a54b2fSSadaf Ebrahimi<td>
432*83a54b2fSSadaf Ebrahimi<tt>priority</tt>
433*83a54b2fSSadaf Ebrahimi</td>
434*83a54b2fSSadaf Ebrahimi<td>
435*83a54b2fSSadaf Ebrahimi          The priority for this test method. Lower priorities will be scheduled first.
436*83a54b2fSSadaf Ebrahimi</td>
437*83a54b2fSSadaf Ebrahimi</tr>
438*83a54b2fSSadaf Ebrahimi
439*83a54b2fSSadaf Ebrahimi<tr>
440*83a54b2fSSadaf Ebrahimi<td>
441*83a54b2fSSadaf Ebrahimi</td>
442*83a54b2fSSadaf Ebrahimi<td>
443*83a54b2fSSadaf Ebrahimi
444*83a54b2fSSadaf Ebrahimi<tt>successPercentage</tt>
445*83a54b2fSSadaf Ebrahimi</td>
446*83a54b2fSSadaf Ebrahimi<td>
447*83a54b2fSSadaf Ebrahimi          The percentage of success expected from this method
448*83a54b2fSSadaf Ebrahimi</td>
449*83a54b2fSSadaf Ebrahimi</tr>
450*83a54b2fSSadaf Ebrahimi
451*83a54b2fSSadaf Ebrahimi<tr>
452*83a54b2fSSadaf Ebrahimi<td>
453*83a54b2fSSadaf Ebrahimi</td>
454*83a54b2fSSadaf Ebrahimi<td>
455*83a54b2fSSadaf Ebrahimi<tt>singleThreaded</tt>
456*83a54b2fSSadaf Ebrahimi</td>
457*83a54b2fSSadaf Ebrahimi<td>
458*83a54b2fSSadaf Ebrahimi             If set to true, all the methods on this test class are guaranteed to run in the same thread, even if the tests are currently being run with parallel="methods". This attribute can only be used at the class level and it will be ignored if used at the method level. Note: this attribute used to be called <tt>sequential</tt> (now deprecated).
459*83a54b2fSSadaf Ebrahimi
460*83a54b2fSSadaf Ebrahimi</td>
461*83a54b2fSSadaf Ebrahimi</tr>
462*83a54b2fSSadaf Ebrahimi
463*83a54b2fSSadaf Ebrahimi<tr>
464*83a54b2fSSadaf Ebrahimi<td>
465*83a54b2fSSadaf Ebrahimi</td>
466*83a54b2fSSadaf Ebrahimi<td>
467*83a54b2fSSadaf Ebrahimi<tt>timeOut</tt>
468*83a54b2fSSadaf Ebrahimi</td>
469*83a54b2fSSadaf Ebrahimi<td>
470*83a54b2fSSadaf Ebrahimi          The maximum number of milliseconds this test should take.
471*83a54b2fSSadaf Ebrahimi</td>
472*83a54b2fSSadaf Ebrahimi</tr>
473*83a54b2fSSadaf Ebrahimi
474*83a54b2fSSadaf Ebrahimi<tr>
475*83a54b2fSSadaf Ebrahimi<td>
476*83a54b2fSSadaf Ebrahimi</td>
477*83a54b2fSSadaf Ebrahimi<td>
478*83a54b2fSSadaf Ebrahimi<tt>threadPoolSize</tt>
479*83a54b2fSSadaf Ebrahimi</td>
480*83a54b2fSSadaf Ebrahimi<td>
481*83a54b2fSSadaf Ebrahimi             The size of the thread pool for this method.
482*83a54b2fSSadaf EbrahimiThe method will be invoked from multiple threads as specified by
483*83a54b2fSSadaf EbrahimiinvocationCount. <br>Note:  this attribute is ignored if invocationCount is not specified
484*83a54b2fSSadaf Ebrahimi
485*83a54b2fSSadaf Ebrahimi</td>
486*83a54b2fSSadaf Ebrahimi</tr>
487*83a54b2fSSadaf Ebrahimi
488*83a54b2fSSadaf Ebrahimi</table>
489*83a54b2fSSadaf Ebrahimi
490*83a54b2fSSadaf Ebrahimi
491*83a54b2fSSadaf Ebrahimi
492*83a54b2fSSadaf Ebrahimi
493*83a54b2fSSadaf Ebrahimi</pre>
494*83a54b2fSSadaf Ebrahimi<!-------------------------------------
495*83a54b2fSSadaf Ebrahimi  TESTNG.XML
496*83a54b2fSSadaf Ebrahimi  ------------------------------------>
497*83a54b2fSSadaf Ebrahimi<h3><a class="section" name="testng-xml">testng.xml</a></h3>
498*83a54b2fSSadaf Ebrahimi
499*83a54b2fSSadaf Ebrahimi<p>You can invoke TestNG in several different ways:</p><ul>
500*83a54b2fSSadaf Ebrahimi	<li>With a <tt>testng.xml</tt> file</li><li><a href="http://testng.org/doc/ant.html">With ant</a></li><li>From the command line</li></ul><p>This section describes the format of <tt>testng.xml</tt> (you will find documentation
501*83a54b2fSSadaf Ebrahimion ant and the command line below).</p><p>The current DTD for <tt>testng.xml</tt> can be found on the main Web site:&nbsp;
502*83a54b2fSSadaf Ebrahimi<a href="http://testng.org/testng-1.0.dtd">http://testng.org/testng-1.0.dtd</a>
503*83a54b2fSSadaf Ebrahimi(for your convenience, you might prefer to browse the
504*83a54b2fSSadaf Ebrahimi<a href="http://testng.org/dtd">HTML version</a>).</p>
505*83a54b2fSSadaf Ebrahimi
506*83a54b2fSSadaf EbrahimiHere is an example <tt>testng.xml</tt> file:
507*83a54b2fSSadaf Ebrahimi
508*83a54b2fSSadaf Ebrahimi<p>
509*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
510*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
511*83a54b2fSSadaf Ebrahimi&lt;!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" &gt;
512*83a54b2fSSadaf Ebrahimi
513*83a54b2fSSadaf Ebrahimi&lt;suite name="Suite1" verbose="1" &gt;
514*83a54b2fSSadaf Ebrahimi  &lt;test name="Nopackage" &gt;
515*83a54b2fSSadaf Ebrahimi    &lt;classes&gt;
516*83a54b2fSSadaf Ebrahimi       &lt;class name="NoPackageTest" /&gt;
517*83a54b2fSSadaf Ebrahimi    &lt;/classes&gt;
518*83a54b2fSSadaf Ebrahimi  &lt;/test&gt;
519*83a54b2fSSadaf Ebrahimi
520*83a54b2fSSadaf Ebrahimi  &lt;test name="Regression1"&gt;
521*83a54b2fSSadaf Ebrahimi    &lt;classes&gt;
522*83a54b2fSSadaf Ebrahimi      &lt;class name="test.sample.ParameterSample"/&gt;
523*83a54b2fSSadaf Ebrahimi      &lt;class name="test.sample.ParameterTest"/&gt;
524*83a54b2fSSadaf Ebrahimi    &lt;/classes&gt;
525*83a54b2fSSadaf Ebrahimi  &lt;/test&gt;
526*83a54b2fSSadaf Ebrahimi&lt;/suite&gt;
527*83a54b2fSSadaf Ebrahimi</pre>
528*83a54b2fSSadaf Ebrahimi
529*83a54b2fSSadaf EbrahimiYou can specify package names instead of class names:
530*83a54b2fSSadaf Ebrahimi
531*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
532*83a54b2fSSadaf Ebrahimi<pre class="brush: xml; highlight: [5,6,7]">
533*83a54b2fSSadaf Ebrahimi&lt;!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" &gt;
534*83a54b2fSSadaf Ebrahimi
535*83a54b2fSSadaf Ebrahimi&lt;suite name="Suite1" verbose="1" &gt;
536*83a54b2fSSadaf Ebrahimi  &lt;test name="Regression1"   &gt;
537*83a54b2fSSadaf Ebrahimi    &lt;packages&gt;
538*83a54b2fSSadaf Ebrahimi      &lt;package name="test.sample" /&gt;
539*83a54b2fSSadaf Ebrahimi   &lt;/packages&gt;
540*83a54b2fSSadaf Ebrahimi &lt;/test&gt;
541*83a54b2fSSadaf Ebrahimi&lt;/suite&gt;
542*83a54b2fSSadaf Ebrahimi</pre>
543*83a54b2fSSadaf Ebrahimi
544*83a54b2fSSadaf Ebrahimi
545*83a54b2fSSadaf Ebrahimi<p>In this example, TestNG will look at all the classes in the package
546*83a54b2fSSadaf Ebrahimi	<tt>test.sample</tt> and will retain only classes that have TestNG annotations.</p>
547*83a54b2fSSadaf Ebrahimi
548*83a54b2fSSadaf EbrahimiYou can also specify groups and methods to be included and excluded:
549*83a54b2fSSadaf Ebrahimi
550*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
551*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
552*83a54b2fSSadaf Ebrahimi&lt;test name="Regression1"&gt;
553*83a54b2fSSadaf Ebrahimi  &lt;groups&gt;
554*83a54b2fSSadaf Ebrahimi    &lt;run&gt;
555*83a54b2fSSadaf Ebrahimi      &lt;exclude name="brokenTests"  /&gt;
556*83a54b2fSSadaf Ebrahimi      &lt;include name="checkinTests"  /&gt;
557*83a54b2fSSadaf Ebrahimi    &lt;/run&gt;
558*83a54b2fSSadaf Ebrahimi  &lt;/groups&gt;
559*83a54b2fSSadaf Ebrahimi
560*83a54b2fSSadaf Ebrahimi  &lt;classes&gt;
561*83a54b2fSSadaf Ebrahimi    &lt;class name="test.IndividualMethodsTest"&gt;
562*83a54b2fSSadaf Ebrahimi      &lt;methods&gt;
563*83a54b2fSSadaf Ebrahimi        &lt;include name="testMethod" /&gt;
564*83a54b2fSSadaf Ebrahimi      &lt;/methods&gt;
565*83a54b2fSSadaf Ebrahimi    &lt;/class&gt;
566*83a54b2fSSadaf Ebrahimi  &lt;/classes&gt;
567*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
568*83a54b2fSSadaf Ebrahimi</pre>
569*83a54b2fSSadaf Ebrahimi
570*83a54b2fSSadaf Ebrahimi<p>You can also define new groups inside <tt>testng.xml</tt> and specify additional details in attributes, such as whether to run the tests in parallel, how many threads to use, whether you are running JUnit tests, etc...&nbsp;
571*83a54b2fSSadaf Ebrahimi<p>
572*83a54b2fSSadaf Ebrahimi
573*83a54b2fSSadaf EbrahimiBy default, TestNG will run your tests in the order they are found in the XML
574*83a54b2fSSadaf Ebrahimifile. If you want the classes and methods listed in this file to be
575*83a54b2fSSadaf Ebrahimirun in an unpredictible order, set the <tt>preserve-order</tt>
576*83a54b2fSSadaf Ebrahimiattribute to <tt>false</tt>
577*83a54b2fSSadaf Ebrahimi
578*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
579*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
580*83a54b2fSSadaf Ebrahimi&lt;test name="Regression1" preserve-order="false"&gt;
581*83a54b2fSSadaf Ebrahimi  &lt;classes&gt;
582*83a54b2fSSadaf Ebrahimi
583*83a54b2fSSadaf Ebrahimi    &lt;class name="test.Test1"&gt;
584*83a54b2fSSadaf Ebrahimi      &lt;methods&gt;
585*83a54b2fSSadaf Ebrahimi        &lt;include name="m1" /&gt;
586*83a54b2fSSadaf Ebrahimi        &lt;include name="m2" /&gt;
587*83a54b2fSSadaf Ebrahimi      &lt;/methods&gt;
588*83a54b2fSSadaf Ebrahimi    &lt;/class&gt;
589*83a54b2fSSadaf Ebrahimi
590*83a54b2fSSadaf Ebrahimi    &lt;class name="test.Test2" /&gt;
591*83a54b2fSSadaf Ebrahimi
592*83a54b2fSSadaf Ebrahimi  &lt;/classes&gt;
593*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
594*83a54b2fSSadaf Ebrahimi</pre>
595*83a54b2fSSadaf Ebrahimi
596*83a54b2fSSadaf Ebrahimi<p>
597*83a54b2fSSadaf Ebrahimi
598*83a54b2fSSadaf EbrahimiPlease see the DTD for a complete list of the features, or read on.</p>
599*83a54b2fSSadaf Ebrahimi
600*83a54b2fSSadaf Ebrahimi<!-------------------------------------
601*83a54b2fSSadaf Ebrahimi  RUNNING TESTNG
602*83a54b2fSSadaf Ebrahimi  ------------------------------------>
603*83a54b2fSSadaf Ebrahimi
604*83a54b2fSSadaf Ebrahimi<h3><a class="section" name="running-testng">Running TestNG</a></h3>
605*83a54b2fSSadaf Ebrahimi
606*83a54b2fSSadaf EbrahimiTestNG can be invoked in different ways:
607*83a54b2fSSadaf Ebrahimi
608*83a54b2fSSadaf Ebrahimi<ul>
609*83a54b2fSSadaf Ebrahimi<li>Command line
610*83a54b2fSSadaf Ebrahimi</li>
611*83a54b2fSSadaf Ebrahimi<li><a href="ant.html">ant</a>
612*83a54b2fSSadaf Ebrahimi</li>
613*83a54b2fSSadaf Ebrahimi<li><a href="eclipse.html">Eclipse</a>
614*83a54b2fSSadaf Ebrahimi</li>
615*83a54b2fSSadaf Ebrahimi<li><a href="idea.html">IntelliJ's IDEA</a>
616*83a54b2fSSadaf Ebrahimi</li>
617*83a54b2fSSadaf Ebrahimi</ul>
618*83a54b2fSSadaf Ebrahimi
619*83a54b2fSSadaf EbrahimiThis section only explains how to invoke TestNG from the command line.  Please click on one of the links above if you are interested in one of the other ways.
620*83a54b2fSSadaf Ebrahimi<p>
621*83a54b2fSSadaf EbrahimiAssuming that you have TestNG in your class path, the simplest way to invoke TestNG is as follows:
622*83a54b2fSSadaf Ebrahimi
623*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
624*83a54b2fSSadaf Ebrahimijava org.testng.TestNG testng1.xml [testng2.xml testng3.xml ...]
625*83a54b2fSSadaf Ebrahimi</pre>
626*83a54b2fSSadaf Ebrahimi
627*83a54b2fSSadaf EbrahimiYou need to specify at least one XML file describing the TestNG suite you are trying to run.  Additionally, the following command-line switches are available:
628*83a54b2fSSadaf Ebrahimi
629*83a54b2fSSadaf Ebrahimi</p>
630*83a54b2fSSadaf Ebrahimi
631*83a54b2fSSadaf Ebrahimi<table id="command-line">
632*83a54b2fSSadaf Ebrahimi    <caption>Command Line Parameters</caption><colgroup class="option"/>
633*83a54b2fSSadaf Ebrahimi    <colgroup class="argument"/>
634*83a54b2fSSadaf Ebrahimi    <colgroup class="documentation"/>
635*83a54b2fSSadaf Ebrahimi    <thead>
636*83a54b2fSSadaf Ebrahimi
637*83a54b2fSSadaf Ebrahimi        <tr>
638*83a54b2fSSadaf Ebrahimi            <th>Option</th>
639*83a54b2fSSadaf Ebrahimi    	<th>Argument</th>
640*83a54b2fSSadaf Ebrahimi    	<th>Documentation</th>
641*83a54b2fSSadaf Ebrahimi        </tr>
642*83a54b2fSSadaf Ebrahimi    </thead>
643*83a54b2fSSadaf Ebrahimi
644*83a54b2fSSadaf Ebrahimi    <tbody>
645*83a54b2fSSadaf Ebrahimi        <tr>
646*83a54b2fSSadaf Ebrahimi            <td>-configfailurepolicy</td>
647*83a54b2fSSadaf Ebrahimi	    <td><tt>skip</tt>|<tt>continue</tt></td>
648*83a54b2fSSadaf Ebrahimi	    <td>Whether TestNG should <tt>continue</tt> to execute the remaining tests in the suite or <tt>skip</tt> them if
649*83a54b2fSSadaf Ebrahimi            an @Before* method fails.  Default behavior is <tt>skip</tt>.</td>
650*83a54b2fSSadaf Ebrahimi        </tr>
651*83a54b2fSSadaf Ebrahimi
652*83a54b2fSSadaf Ebrahimi        <tr>
653*83a54b2fSSadaf Ebrahimi            <td>-d</td>
654*83a54b2fSSadaf Ebrahimi	    <td>A directory</td>
655*83a54b2fSSadaf Ebrahimi	    <td>The directory where the reports will be generated (defaults to <tt>test-output</tt>).</td>
656*83a54b2fSSadaf Ebrahimi        </tr>
657*83a54b2fSSadaf Ebrahimi
658*83a54b2fSSadaf Ebrahimi        <tr>
659*83a54b2fSSadaf Ebrahimi            <td>-dataproviderthreadcount</td>
660*83a54b2fSSadaf Ebrahimi	    <td>The default number of threads to use for data
661*83a54b2fSSadaf Ebrahimi            providers when running tests in parallel.</td>
662*83a54b2fSSadaf Ebrahimi	    <td>This sets the default maximum number of threads to use
663*83a54b2fSSadaf Ebrahimi            for data providers when running tests in parallel. It will only take effect if the parallel mode has been selected (for example, with the -parallel option). This can be overridden in the suite definition.</td>
664*83a54b2fSSadaf Ebrahimi        </tr>
665*83a54b2fSSadaf Ebrahimi
666*83a54b2fSSadaf Ebrahimi	<tr>
667*83a54b2fSSadaf Ebrahimi            <td>-excludegroups</td>
668*83a54b2fSSadaf Ebrahimi	    <td>A comma-separated list of groups.</td><td>The list of groups you want to be excluded from this run.</td>
669*83a54b2fSSadaf Ebrahimi        </tr>
670*83a54b2fSSadaf Ebrahimi
671*83a54b2fSSadaf Ebrahimi        <tr>
672*83a54b2fSSadaf Ebrahimi            <td>-groups</td>
673*83a54b2fSSadaf Ebrahimi	    <td>A comma-separated list of groups.</td>
674*83a54b2fSSadaf Ebrahimi	    <td>The list of groups you want to run (e.g. <tt>"windows,linux,regression"</tt>).</td>
675*83a54b2fSSadaf Ebrahimi	</tr>
676*83a54b2fSSadaf Ebrahimi
677*83a54b2fSSadaf Ebrahimi        <tr>
678*83a54b2fSSadaf Ebrahimi            <td>-listener</td>
679*83a54b2fSSadaf Ebrahimi	    <td>A comma-separated list of Java classes that can be found on your classpath.</td>
680*83a54b2fSSadaf Ebrahimi	    <td>Lets you specify your own test listeners.  The classes need to implement <a href="../javadocs/org/testng/ITestListener.html"> <tt>org.testng.ITestListener</tt></a></td>
681*83a54b2fSSadaf Ebrahimi        </tr>
682*83a54b2fSSadaf Ebrahimi
683*83a54b2fSSadaf Ebrahimi	<tr>
684*83a54b2fSSadaf Ebrahimi            <td>-methods</td>
685*83a54b2fSSadaf Ebrahimi	    <td>A comma separated list of fully qualified class name and method. For example <tt>com.example.Foo.f1,com.example.Bar.f2</tt>.</td>
686*83a54b2fSSadaf Ebrahimi	    <td>Lets you specify individual methods to run.</tt></a></td>
687*83a54b2fSSadaf Ebrahimi        </tr>
688*83a54b2fSSadaf Ebrahimi
689*83a54b2fSSadaf Ebrahimi        <tr>
690*83a54b2fSSadaf Ebrahimi            <td>-methodselectors</td>
691*83a54b2fSSadaf Ebrahimi	    <td>A comma-separated list of Java classes and method
692*83a54b2fSSadaf Ebrahimi            priorities that define method selectors.</td>
693*83a54b2fSSadaf Ebrahimi	    <td>Lets you specify method selectors on the command
694*83a54b2fSSadaf Ebrahimi            line. For example: <tt>com.example.Selector1:3,com.example.Selector2:2</tt></td>
695*83a54b2fSSadaf Ebrahimi        </tr>
696*83a54b2fSSadaf Ebrahimi
697*83a54b2fSSadaf Ebrahimi	<tr>
698*83a54b2fSSadaf Ebrahimi            <td>-parallel</td>
699*83a54b2fSSadaf Ebrahimi	    <td>methods|tests|classes</td>
700*83a54b2fSSadaf Ebrahimi	    <td>If specified, sets the default mechanism used to determine how to use parallel threads when running tests. If not set, default mechanism is not to use parallel threads at all. This can be overridden in the suite definition.</td>
701*83a54b2fSSadaf Ebrahimi        </tr>
702*83a54b2fSSadaf Ebrahimi
703*83a54b2fSSadaf Ebrahimi        <tr>
704*83a54b2fSSadaf Ebrahimi            <td>-reporter</td>
705*83a54b2fSSadaf Ebrahimi	    <td>The extended configuration for a custom report listener.</td>
706*83a54b2fSSadaf Ebrahimi	    <td>Similar to the <tt>-listener</tt> option, except that it allows the configuration of JavaBeans-style properties on the reporter instance.
707*83a54b2fSSadaf Ebrahimi	      <br>
708*83a54b2fSSadaf Ebrahimi            Example: <tt>-reporter com.test.MyReporter:methodFilter=*insert*,enableFiltering=true</tt>
709*83a54b2fSSadaf Ebrahimi	      <br>
710*83a54b2fSSadaf Ebrahimi            You can have as many occurences of this option, one for each reporter that needs to be added.</td>
711*83a54b2fSSadaf Ebrahimi        </tr>
712*83a54b2fSSadaf Ebrahimi
713*83a54b2fSSadaf Ebrahimi        <tr>
714*83a54b2fSSadaf Ebrahimi            <td>-sourcedir</td>
715*83a54b2fSSadaf Ebrahimi    	    <td>A semi-colon separated list of directories.</td>
716*83a54b2fSSadaf Ebrahimi            <td>The directories where your javadoc annotated test sources are. This option is only necessary if you are using javadoc type annotations. (e.g. <tt>"src/test"</tt> or <tt>"src/test/org/testng/eclipse-plugin;src/test/org/testng/testng"</tt>).</td>
717*83a54b2fSSadaf Ebrahimi        </tr>
718*83a54b2fSSadaf Ebrahimi
719*83a54b2fSSadaf Ebrahimi       <tr>
720*83a54b2fSSadaf Ebrahimi           <td>-suitename</td>
721*83a54b2fSSadaf Ebrahimi	   <td>The default name to use for a test suite.</td>
722*83a54b2fSSadaf Ebrahimi	   <td>This specifies the suite name for a test suite defined on the command line. This option is ignored if the suite.xml file or the source code specifies a different suite name.  It is possible to create a suite name with spaces in it if you surround it with double-quotes "like this".</td>
723*83a54b2fSSadaf Ebrahimi        </tr>
724*83a54b2fSSadaf Ebrahimi
725*83a54b2fSSadaf Ebrahimi        <tr>
726*83a54b2fSSadaf Ebrahimi            <td>-testclass</td>
727*83a54b2fSSadaf Ebrahimi	    <td>A comma-separated list of classes that can be found in your classpath.</td><td>A list of class files separated by commas (e.g. <tt>"org.foo.Test1,org.foo.test2"</tt>).</td>
728*83a54b2fSSadaf Ebrahimi	</tr>
729*83a54b2fSSadaf Ebrahimi
730*83a54b2fSSadaf Ebrahimi         <tr>
731*83a54b2fSSadaf Ebrahimi            <td>-testjar</td>
732*83a54b2fSSadaf Ebrahimi	    <td>A jar file.</td>
733*83a54b2fSSadaf Ebrahimi	    <td>Specifies a jar file that contains test classes.  If a <tt>testng.xml</tt> file is found at the root of that jar file, it will be used, otherwise, all the test classes found in this jar file will be considered test classes.</td>
734*83a54b2fSSadaf Ebrahimi        </tr>
735*83a54b2fSSadaf Ebrahimi
736*83a54b2fSSadaf Ebrahimi        <tr>
737*83a54b2fSSadaf Ebrahimi            <td>-testname</td>
738*83a54b2fSSadaf Ebrahimi	    <td>The default name to use for a test.</td>
739*83a54b2fSSadaf Ebrahimi	    <td>This specifies the name for a test defined on the command line. This option is ignored if the suite.xml file or the source code specifies a different test name. It is possible to create a test name with spaces in it if you surround it with double-quotes "like this".</td>
740*83a54b2fSSadaf Ebrahimi        </tr>
741*83a54b2fSSadaf Ebrahimi
742*83a54b2fSSadaf Ebrahimi        <tr>
743*83a54b2fSSadaf Ebrahimi            <td>-testnames</td>
744*83a54b2fSSadaf Ebrahimi	    <td>A comma separated list of test names.</td>
745*83a54b2fSSadaf Ebrahimi	    <td>Only tests defined in a &lt;test&gt; tag matching one of these names will be run.</td>
746*83a54b2fSSadaf Ebrahimi        </tr>
747*83a54b2fSSadaf Ebrahimi
748*83a54b2fSSadaf Ebrahimi        <tr>
749*83a54b2fSSadaf Ebrahimi            <td>-testrunfactory</td>
750*83a54b2fSSadaf Ebrahimi	    <td>A Java classes that can be found on your classpath.</td>
751*83a54b2fSSadaf Ebrahimi	    <td>Lets you specify your own test runners.  The class needs to implement <a href="../javadocs/org/testng/ITestRunnerFactory.html"> <tt>org.testng.ITestRunnerFactory</tt></a>.</td>
752*83a54b2fSSadaf Ebrahimi        </tr>
753*83a54b2fSSadaf Ebrahimi
754*83a54b2fSSadaf Ebrahimi        <tr>
755*83a54b2fSSadaf Ebrahimi            <td>-threadcount</td>
756*83a54b2fSSadaf Ebrahimi	    <td>The default number of threads to use when running tests in parallel.</td>
757*83a54b2fSSadaf Ebrahimi	    <td>This sets the default maximum number of threads to use for running tests in parallel. It will only take effect if the parallel mode has been selected (for example, with the -parallel option). This can be overridden in the suite definition.</td>
758*83a54b2fSSadaf Ebrahimi        </tr>
759*83a54b2fSSadaf Ebrahimi
760*83a54b2fSSadaf Ebrahimi	<tr>
761*83a54b2fSSadaf Ebrahimi            <td>-xmlpathinjar</td>
762*83a54b2fSSadaf Ebrahimi	    <td>The path of the XML file inside the jar file.</td>
763*83a54b2fSSadaf Ebrahimi	    <td>This attribute should contain the path to a valid XML file inside the test jar (e.g. <tt>"resources/testng.xml"</tt>). The default is <tt>"testng.xml"</tt>, which means a file called "<tt>testng.xml</tt>" at the root of the jar file. This option will be ignored unless <tt>-testjar</tt> is specified.</td>
764*83a54b2fSSadaf Ebrahimi        </tr>
765*83a54b2fSSadaf Ebrahimi
766*83a54b2fSSadaf Ebrahimi      </tbody>
767*83a54b2fSSadaf Ebrahimi</table>
768*83a54b2fSSadaf Ebrahimi
769*83a54b2fSSadaf Ebrahimi<p>
770*83a54b2fSSadaf Ebrahimi
771*83a54b2fSSadaf EbrahimiThis documentation can be obtained by invoking TestNG without any arguments.
772*83a54b2fSSadaf Ebrahimi
773*83a54b2fSSadaf Ebrahimi<p>
774*83a54b2fSSadaf Ebrahimi
775*83a54b2fSSadaf EbrahimiYou can also put the command line switches in a text file, say <tt>c:\command.txt</tt>, and tell TestNG to use that file to retrieve its parameters:
776*83a54b2fSSadaf Ebrahimi
777*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
778*83a54b2fSSadaf Ebrahimi  C:> more c:\command.txt
779*83a54b2fSSadaf Ebrahimi  -d test-output testng.xml
780*83a54b2fSSadaf Ebrahimi  C:> java org.testng.TestNG @c:\command.txt
781*83a54b2fSSadaf Ebrahimi</pre>
782*83a54b2fSSadaf Ebrahimi
783*83a54b2fSSadaf Ebrahimi<p>
784*83a54b2fSSadaf Ebrahimi
785*83a54b2fSSadaf EbrahimiAdditionally, TestNG can be passed properties on the command line of the Java Virtual Machine, for example
786*83a54b2fSSadaf Ebrahimi
787*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
788*83a54b2fSSadaf Ebrahimijava -Dtestng.test.classpath="c:/build;c:/java/classes;" org.testng.TestNG testng.xml
789*83a54b2fSSadaf Ebrahimi</pre>
790*83a54b2fSSadaf Ebrahimi
791*83a54b2fSSadaf EbrahimiHere are the properties that TestNG understands:
792*83a54b2fSSadaf Ebrahimi
793*83a54b2fSSadaf Ebrahimi<table id="system=properties">
794*83a54b2fSSadaf Ebrahimi    <caption>System properties</caption>
795*83a54b2fSSadaf Ebrahimi    <colgroup class="option"/>
796*83a54b2fSSadaf Ebrahimi    <colgroup class="type"/>
797*83a54b2fSSadaf Ebrahimi    <colgroup class="documentation"/>
798*83a54b2fSSadaf Ebrahimi    <thead>
799*83a54b2fSSadaf Ebrahimi      <tr><th>Property</th>
800*83a54b2fSSadaf Ebrahimi      <th>Type</th>
801*83a54b2fSSadaf Ebrahimi      <th>Documentation</th></tr>
802*83a54b2fSSadaf Ebrahimi    </thead>
803*83a54b2fSSadaf Ebrahimi
804*83a54b2fSSadaf Ebrahimi    <tr>
805*83a54b2fSSadaf Ebrahimi    <td>testng.test.classpath</td>
806*83a54b2fSSadaf Ebrahimi    <td>A semi-colon separated series of directories that contain your test classes.</td>
807*83a54b2fSSadaf Ebrahimi    <td>If this property is set, TestNG will use it to look for your test classes instead of the class path.  This is convenient if you are using the <tt>package</tt> tag in your XML file and you have a lot of classes in your classpath, most of them not being test classes.
808*83a54b2fSSadaf Ebrahimi    </tr>
809*83a54b2fSSadaf Ebrahimi</table>
810*83a54b2fSSadaf Ebrahimi
811*83a54b2fSSadaf Ebrahimi<br>
812*83a54b2fSSadaf Ebrahimi
813*83a54b2fSSadaf Ebrahimi<b>Example:</b>
814*83a54b2fSSadaf Ebrahimi
815*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
816*83a54b2fSSadaf Ebrahimijava org.testng.TestNG -groups windows,linux -testclass org.test.MyTest
817*83a54b2fSSadaf Ebrahimi</pre>
818*83a54b2fSSadaf Ebrahimi
819*83a54b2fSSadaf EbrahimiThe <a href="ant.html">ant task</a> and <a href="#testng-xml">testng.xml</a> allow you to launch TestNG with more parameters (methods to include, specifying parameters, etc...), so you should consider using the command line only when you are trying to learn about TestNG and you want to get up and running quickly.
820*83a54b2fSSadaf Ebrahimi
821*83a54b2fSSadaf Ebrahimi<p>
822*83a54b2fSSadaf Ebrahimi
823*83a54b2fSSadaf Ebrahimi<em>Important</em>: The command line flags that specify what tests should be run will be ignored if you also specify a <tt>testng.xml</tt> file, with the exception of <tt>-includedgroups</tt> and <tt>-excludedgroups</tt>, which will override all the group inclusions/exclusions found in <tt>testng.xml</tt>.
824*83a54b2fSSadaf Ebrahimi
825*83a54b2fSSadaf Ebrahimi<!-------------------------------------
826*83a54b2fSSadaf Ebrahimi  METHODS
827*83a54b2fSSadaf Ebrahimi  ------------------------------------>
828*83a54b2fSSadaf Ebrahimi
829*83a54b2fSSadaf Ebrahimi<h3><a class="section" name="methods">Test methods, Test classes and Test groups</a></h3>
830*83a54b2fSSadaf Ebrahimi
831*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="test-methods">Test methods</a></h4>
832*83a54b2fSSadaf Ebrahimi
833*83a54b2fSSadaf EbrahimiTest methods are annotated with <tt>@Test</tt>. Methods annotated with <tt>@Test</tt> that happen to return a value will be ignored, unless you set <tt>allow-return-values</tt> to <tt>true</tt> in your <tt>testng.xml</tt>:
834*83a54b2fSSadaf Ebrahimi
835*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
836*83a54b2fSSadaf Ebrahimi&lt;suite allow-return-values="true"&gt;
837*83a54b2fSSadaf Ebrahimi
838*83a54b2fSSadaf Ebrahimior
839*83a54b2fSSadaf Ebrahimi
840*83a54b2fSSadaf Ebrahimi&lt;test allow-return-values="true"&gt;
841*83a54b2fSSadaf Ebrahimi</pre>
842*83a54b2fSSadaf Ebrahimi
843*83a54b2fSSadaf Ebrahimi
844*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="test-groups">Test groups</a></h4>
845*83a54b2fSSadaf Ebrahimi
846*83a54b2fSSadaf Ebrahimi<p>
847*83a54b2fSSadaf Ebrahimi
848*83a54b2fSSadaf EbrahimiTestNG allows you to perform sophisticated groupings of test methods. Not
849*83a54b2fSSadaf Ebrahimionly can you declare that methods belong to groups, but you can also specify
850*83a54b2fSSadaf Ebrahimigroups that contain other groups. Then TestNG can be invoked and asked to
851*83a54b2fSSadaf Ebrahimiinclude a certain set of groups (or regular expressions) while excluding another
852*83a54b2fSSadaf Ebrahimiset.&nbsp; This gives you maximum flexibility in how you partition your tests
853*83a54b2fSSadaf Ebrahimiand doesn't require you to recompile anything if you want to run two different
854*83a54b2fSSadaf Ebrahimisets of tests back to back.</p>
855*83a54b2fSSadaf Ebrahimi
856*83a54b2fSSadaf Ebrahimi<p>
857*83a54b2fSSadaf EbrahimiGroups are specified in your <tt>testng.xml</tt> file and can be found either under the <tt>&lt;test&gt;</tt> or <tt>&lt;suite&gt;</tt> tag. Groups specified in the <tt>&lt;suite&gt;</tt> tag apply to all the <tt>&lt;test&gt;</tt> tags underneath. Note that groups are accumulative in these tags: if you specify group "a" in <tt>&lt;suite&gt;</tt> and "b" in <tt>&lt;test&gt;</tt>, then both "a" and "b" will be included.
858*83a54b2fSSadaf Ebrahimi
859*83a54b2fSSadaf Ebrahimi<p>
860*83a54b2fSSadaf Ebrahimi
861*83a54b2fSSadaf Ebrahimi<p>For example, it is quite common to have at least two categories of tests</p><ul>
862*83a54b2fSSadaf Ebrahimi  <li>Check-in tests.&nbsp; These tests should be run before you submit new
863*83a54b2fSSadaf Ebrahimi	code.&nbsp; They should typically be fast and just make sure no basic
864*83a54b2fSSadaf Ebrahimi	functionality was broken.<br>
865*83a54b2fSSadaf Ebrahimi&nbsp;</li>
866*83a54b2fSSadaf Ebrahimi  <li>Functional tests.&nbsp; These tests should cover all the functionalities
867*83a54b2fSSadaf Ebrahimi	of your software and be run at least once a day, although ideally you would
868*83a54b2fSSadaf Ebrahimi	want to run them continuously.</li></ul>
869*83a54b2fSSadaf Ebrahimi
870*83a54b2fSSadaf Ebrahimi
871*83a54b2fSSadaf Ebrahimi	Typically, check-in tests are a subset of functional tests.&nbsp; TestNG
872*83a54b2fSSadaf Ebrahimiallows you to specify this in a very intuitive way with test groups.&nbsp; For
873*83a54b2fSSadaf Ebrahimiexample, you could structure your test by saying that your entire test class
874*83a54b2fSSadaf Ebrahimibelongs to the &quot;functest&quot; group, and additionally that a couple of methods
875*83a54b2fSSadaf Ebrahimibelong to the group &quot;checkintest&quot;:
876*83a54b2fSSadaf Ebrahimi
877*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Test1.java</h3>
878*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
879*83a54b2fSSadaf Ebrahimipublic class Test1 {
880*83a54b2fSSadaf Ebrahimi  @Test(groups = { "functest", "checkintest" })
881*83a54b2fSSadaf Ebrahimi  public void testMethod1() {
882*83a54b2fSSadaf Ebrahimi  }
883*83a54b2fSSadaf Ebrahimi
884*83a54b2fSSadaf Ebrahimi  @Test(groups = {"functest", "checkintest"} )
885*83a54b2fSSadaf Ebrahimi  public void testMethod2() {
886*83a54b2fSSadaf Ebrahimi  }
887*83a54b2fSSadaf Ebrahimi
888*83a54b2fSSadaf Ebrahimi  @Test(groups = { "functest" })
889*83a54b2fSSadaf Ebrahimi  public void testMethod3() {
890*83a54b2fSSadaf Ebrahimi  }
891*83a54b2fSSadaf Ebrahimi}
892*83a54b2fSSadaf Ebrahimi</pre>
893*83a54b2fSSadaf Ebrahimi
894*83a54b2fSSadaf EbrahimiInvoking TestNG with
895*83a54b2fSSadaf Ebrahimi	<br>
896*83a54b2fSSadaf Ebrahimi
897*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
898*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
899*83a54b2fSSadaf Ebrahimi&lt;test name="Test1"&gt;
900*83a54b2fSSadaf Ebrahimi  &lt;groups&gt;
901*83a54b2fSSadaf Ebrahimi    &lt;run&gt;
902*83a54b2fSSadaf Ebrahimi      &lt;include name="functest"/&gt;
903*83a54b2fSSadaf Ebrahimi    &lt;/run&gt;
904*83a54b2fSSadaf Ebrahimi  &lt;/groups&gt;
905*83a54b2fSSadaf Ebrahimi  &lt;classes&gt;
906*83a54b2fSSadaf Ebrahimi    &lt;class name="example1.Test1"/&gt;
907*83a54b2fSSadaf Ebrahimi  &lt;/classes&gt;
908*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
909*83a54b2fSSadaf Ebrahimi</pre>
910*83a54b2fSSadaf Ebrahimi
911*83a54b2fSSadaf Ebrahimi<p>will run all the test methods in that classes, while invoking it with <tt>checkintest</tt> will only run
912*83a54b2fSSadaf Ebrahimi<tt>testMethod1()</tt> and <tt>testMethod2()</tt>.</p>
913*83a54b2fSSadaf Ebrahimi
914*83a54b2fSSadaf Ebrahimi
915*83a54b2fSSadaf EbrahimiHere is another example, using regular expressions this time.&nbsp; Assume
916*83a54b2fSSadaf Ebrahimithat some of your test methods should not be run on Linux, your test would look
917*83a54b2fSSadaf Ebrahimilike:
918*83a54b2fSSadaf Ebrahimi
919*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Test1.java</h3>
920*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
921*83a54b2fSSadaf Ebrahimi@Test
922*83a54b2fSSadaf Ebrahimipublic class Test1 {
923*83a54b2fSSadaf Ebrahimi  @Test(groups = { "windows.checkintest" })
924*83a54b2fSSadaf Ebrahimi  public void testWindowsOnly() {
925*83a54b2fSSadaf Ebrahimi  }
926*83a54b2fSSadaf Ebrahimi
927*83a54b2fSSadaf Ebrahimi  @Test(groups = {"linux.checkintest"} )
928*83a54b2fSSadaf Ebrahimi  public void testLinuxOnly() {
929*83a54b2fSSadaf Ebrahimi  }
930*83a54b2fSSadaf Ebrahimi
931*83a54b2fSSadaf Ebrahimi  @Test(groups = { "windows.functest" )
932*83a54b2fSSadaf Ebrahimi  public void testWindowsToo() {
933*83a54b2fSSadaf Ebrahimi  }
934*83a54b2fSSadaf Ebrahimi}
935*83a54b2fSSadaf Ebrahimi</pre>
936*83a54b2fSSadaf Ebrahimi
937*83a54b2fSSadaf Ebrahimi
938*83a54b2fSSadaf EbrahimiYou could use the following testng.xml to launch only the Windows methods:
939*83a54b2fSSadaf Ebrahimi
940*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
941*83a54b2fSSadaf Ebrahimi<pre class="brush: xml; highlight: [4,9]">
942*83a54b2fSSadaf Ebrahimi&lt;test name="Test1"&gt;
943*83a54b2fSSadaf Ebrahimi  &lt;groups&gt;
944*83a54b2fSSadaf Ebrahimi    &lt;run&gt;
945*83a54b2fSSadaf Ebrahimi      &lt;include name="windows.*"/&gt;
946*83a54b2fSSadaf Ebrahimi    &lt;/run&gt;
947*83a54b2fSSadaf Ebrahimi  &lt;/groups&gt;
948*83a54b2fSSadaf Ebrahimi
949*83a54b2fSSadaf Ebrahimi  &lt;classes&gt;
950*83a54b2fSSadaf Ebrahimi    &lt;class name="example1.Test1"/&gt;
951*83a54b2fSSadaf Ebrahimi  &lt;/classes&gt;
952*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
953*83a54b2fSSadaf Ebrahimi</pre>
954*83a54b2fSSadaf Ebrahimi
955*83a54b2fSSadaf Ebrahimi<blockquote>
956*83a54b2fSSadaf Ebrahimi<em>Note:  TestNG uses <a href="http://en.wikipedia.org/wiki/Regular_expression">regular expressions</a>, and not <a href="http://en.wikipedia.org/wiki/Wildmat">wildmats</a>.  Be aware of the difference (for example, "anything" is matched by ".*" -- dot star -- and not "*").</em>
957*83a54b2fSSadaf Ebrahimi</blockquote>
958*83a54b2fSSadaf Ebrahimi
959*83a54b2fSSadaf Ebrahimi<h4><a name="method-groups">Method groups</a></h4>
960*83a54b2fSSadaf Ebrahimi
961*83a54b2fSSadaf EbrahimiYou can also exclude or include individual methods:
962*83a54b2fSSadaf Ebrahimi
963*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
964*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
965*83a54b2fSSadaf Ebrahimi&lt;test name="Test1"&gt;
966*83a54b2fSSadaf Ebrahimi  &lt;classes&gt;
967*83a54b2fSSadaf Ebrahimi    &lt;class name="example1.Test1"&gt;
968*83a54b2fSSadaf Ebrahimi      &lt;methods&gt;
969*83a54b2fSSadaf Ebrahimi        &lt;include name=".*enabledTestMethod.*"/&gt;
970*83a54b2fSSadaf Ebrahimi        &lt;exclude name=".*brokenTestMethod.*"/&gt;
971*83a54b2fSSadaf Ebrahimi      &lt;/methods&gt;
972*83a54b2fSSadaf Ebrahimi     &lt;/class&gt;
973*83a54b2fSSadaf Ebrahimi  &lt;/classes&gt;
974*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
975*83a54b2fSSadaf Ebrahimi</pre>
976*83a54b2fSSadaf Ebrahimi
977*83a54b2fSSadaf EbrahimiThis can come in handy to deactivate a single method without having to recompile
978*83a54b2fSSadaf Ebrahimianything, but I don't recommend using this technique too much since it makes
979*83a54b2fSSadaf Ebrahimiyour testing framework likely to break if you start refactoring your Java code
980*83a54b2fSSadaf Ebrahimi(the regular expressions used in the tags might not match your methods any
981*83a54b2fSSadaf Ebrahimimore).
982*83a54b2fSSadaf Ebrahimi
983*83a54b2fSSadaf Ebrahimi
984*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="groups-of-groups">Groups of groups</a></h4>
985*83a54b2fSSadaf Ebrahimi
986*83a54b2fSSadaf EbrahimiGroups can also include other groups.&nbsp;These groups are called &quot;MetaGroups&quot;.&nbsp;
987*83a54b2fSSadaf EbrahimiFor example, you might want to define a group &quot;all&quot; that includes &quot;checkintest&quot;
988*83a54b2fSSadaf Ebrahimiand &quot;functest&quot;.&nbsp; &quot;functest&quot; itself will contain the groups &quot;windows&quot; and
989*83a54b2fSSadaf Ebrahimi&quot;linux&quot; while &quot;checkintest will only contain &quot;windows&quot;.&nbsp; Here is how you
990*83a54b2fSSadaf Ebrahimiwould define this in your property file:
991*83a54b2fSSadaf Ebrahimi
992*83a54b2fSSadaf Ebrahimi
993*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
994*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
995*83a54b2fSSadaf Ebrahimi&lt;test name="Regression1"&gt;
996*83a54b2fSSadaf Ebrahimi  &lt;groups&gt;
997*83a54b2fSSadaf Ebrahimi    &lt;define name="functest"&gt;
998*83a54b2fSSadaf Ebrahimi      &lt;include name="windows"/&gt;
999*83a54b2fSSadaf Ebrahimi      &lt;include name="linux"/&gt;
1000*83a54b2fSSadaf Ebrahimi    &lt;/define&gt;
1001*83a54b2fSSadaf Ebrahimi
1002*83a54b2fSSadaf Ebrahimi    &lt;define name="all"&gt;
1003*83a54b2fSSadaf Ebrahimi      &lt;include name="functest"/&gt;
1004*83a54b2fSSadaf Ebrahimi      &lt;include name="checkintest"/&gt;
1005*83a54b2fSSadaf Ebrahimi    &lt;/define&gt;
1006*83a54b2fSSadaf Ebrahimi
1007*83a54b2fSSadaf Ebrahimi    &lt;run&gt;
1008*83a54b2fSSadaf Ebrahimi      &lt;include name="all"/&gt;
1009*83a54b2fSSadaf Ebrahimi    &lt;/run&gt;
1010*83a54b2fSSadaf Ebrahimi  &lt;/groups&gt;
1011*83a54b2fSSadaf Ebrahimi
1012*83a54b2fSSadaf Ebrahimi  &lt;classes&gt;
1013*83a54b2fSSadaf Ebrahimi    &lt;class name="test.sample.Test1"/&gt;
1014*83a54b2fSSadaf Ebrahimi  &lt;/classes&gt;
1015*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
1016*83a54b2fSSadaf Ebrahimi</pre>
1017*83a54b2fSSadaf Ebrahimi
1018*83a54b2fSSadaf Ebrahimi</p><!-------------------------------------
1019*83a54b2fSSadaf Ebrahimi  EXCLUSION
1020*83a54b2fSSadaf Ebrahimi  ------------------------------------>
1021*83a54b2fSSadaf Ebrahimi
1022*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="exclusions">Exclusion groups</a></h4>
1023*83a54b2fSSadaf Ebrahimi
1024*83a54b2fSSadaf Ebrahimi<p>TestNG allows you to include groups as well as exclude them.</p>
1025*83a54b2fSSadaf Ebrahimi
1026*83a54b2fSSadaf Ebrahimi
1027*83a54b2fSSadaf EbrahimiFor example, it is quite usual to have tests that temporarily break because
1028*83a54b2fSSadaf Ebrahimiof a recent change, and you don't have time to fix the breakage yet.&nbsp; 4
1029*83a54b2fSSadaf EbrahimiHowever, you do want to have clean runs of your functional tests, so you need to
1030*83a54b2fSSadaf Ebrahimideactivate these tests but keep in mind they will need to be reactivated.</p><p>A simple way to solve this problem is to create a group called &quot;broken&quot; and
1031*83a54b2fSSadaf Ebrahimimake these test methods belong to it.&nbsp; For example, in the above example, I
1032*83a54b2fSSadaf Ebrahimiknow that testMethod2() is now broken so I want to disable it:
1033*83a54b2fSSadaf Ebrahimi
1034*83a54b2fSSadaf Ebrahimi
1035*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Java</h3>
1036*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1037*83a54b2fSSadaf Ebrahimi@Test(groups = {"checkintest", "broken"} )
1038*83a54b2fSSadaf Ebrahimipublic void testMethod2() {
1039*83a54b2fSSadaf Ebrahimi}
1040*83a54b2fSSadaf Ebrahimi</pre>
1041*83a54b2fSSadaf Ebrahimi
1042*83a54b2fSSadaf EbrahimiAll I need to do now is to exclude this group from the run:
1043*83a54b2fSSadaf Ebrahimi
1044*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
1045*83a54b2fSSadaf Ebrahimi<pre class="brush: xml; highlight: 5">
1046*83a54b2fSSadaf Ebrahimi&lt;test name="Simple example"&gt;
1047*83a54b2fSSadaf Ebrahimi  &lt;groups&gt;
1048*83a54b2fSSadaf Ebrahimi    &lt;run&gt;
1049*83a54b2fSSadaf Ebrahimi      &lt;include name="checkintest"/&gt;
1050*83a54b2fSSadaf Ebrahimi      &lt;exclude name="broken"/&gt;
1051*83a54b2fSSadaf Ebrahimi    &lt;/run&gt;
1052*83a54b2fSSadaf Ebrahimi  &lt;/groups&gt;
1053*83a54b2fSSadaf Ebrahimi
1054*83a54b2fSSadaf Ebrahimi  &lt;classes&gt;
1055*83a54b2fSSadaf Ebrahimi    &lt;class name="example1.Test1"/&gt;
1056*83a54b2fSSadaf Ebrahimi  &lt;/classes&gt;
1057*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
1058*83a54b2fSSadaf Ebrahimi</pre>
1059*83a54b2fSSadaf Ebrahimi
1060*83a54b2fSSadaf Ebrahimi<p>This way, I will get a clean test run while keeping track of what tests are
1061*83a54b2fSSadaf Ebrahimibroken and need to be fixed later.</p>
1062*83a54b2fSSadaf Ebrahimi
1063*83a54b2fSSadaf Ebrahimi<blockquote>
1064*83a54b2fSSadaf Ebrahimi	<p><i>Note:&nbsp; you can also disable tests on an individual basis by using the
1065*83a54b2fSSadaf Ebrahimi&quot;enabled&quot; property available on both @Test and @Before/After
1066*83a54b2fSSadaf Ebrahimi	annotations.</i></p>
1067*83a54b2fSSadaf Ebrahimi</blockquote>
1068*83a54b2fSSadaf Ebrahimi
1069*83a54b2fSSadaf Ebrahimi
1070*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1071*83a54b2fSSadaf Ebrahimi  PARTIAL GROUPS
1072*83a54b2fSSadaf Ebrahimi  ------------------------------------>
1073*83a54b2fSSadaf Ebrahimi
1074*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="partial-groups">Partial groups</a></h4>
1075*83a54b2fSSadaf Ebrahimi
1076*83a54b2fSSadaf EbrahimiYou can define  groups at the class level and then add groups at the method level:
1077*83a54b2fSSadaf Ebrahimi
1078*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">All.java</h3>
1079*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1080*83a54b2fSSadaf Ebrahimi@Test(groups = { "checkin-test" })
1081*83a54b2fSSadaf Ebrahimipublic class All {
1082*83a54b2fSSadaf Ebrahimi
1083*83a54b2fSSadaf Ebrahimi  @Test(groups = { "func-test" )
1084*83a54b2fSSadaf Ebrahimi  public void method1() { ... }
1085*83a54b2fSSadaf Ebrahimi
1086*83a54b2fSSadaf Ebrahimi  public void method2() { ... }
1087*83a54b2fSSadaf Ebrahimi}
1088*83a54b2fSSadaf Ebrahimi</pre>
1089*83a54b2fSSadaf Ebrahimi
1090*83a54b2fSSadaf EbrahimiIn this class, method2() is part of the group &quot;checkin-test&quot;, which is defined
1091*83a54b2fSSadaf Ebrahimiat the class level, while method1() belongs to both &quot;checkin-test&quot; and
1092*83a54b2fSSadaf Ebrahimi&quot;func-test&quot;.
1093*83a54b2fSSadaf Ebrahimi
1094*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1095*83a54b2fSSadaf Ebrahimi  PARAMETERS
1096*83a54b2fSSadaf Ebrahimi  ------------------------------------>
1097*83a54b2fSSadaf Ebrahimi
1098*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="parameters">Parameters</a></h4>
1099*83a54b2fSSadaf Ebrahimi
1100*83a54b2fSSadaf Ebrahimi<p>
1101*83a54b2fSSadaf Ebrahimi
1102*83a54b2fSSadaf Ebrahimi
1103*83a54b2fSSadaf EbrahimiTest methods don't have to be parameterless.&nbsp; You can use an arbitrary
1104*83a54b2fSSadaf Ebrahiminumber of parameters on each of your test method, and you instruct TestNG to
1105*83a54b2fSSadaf Ebrahimipass you the correct parameters with the <tt>@Parameters</tt> annotation.</p><p>
1106*83a54b2fSSadaf Ebrahimi
1107*83a54b2fSSadaf Ebrahimi
1108*83a54b2fSSadaf EbrahimiThere are two ways to set these parameters:&nbsp; with <tt>testng.xml</tt> or
1109*83a54b2fSSadaf Ebrahimiprogrammatically.</p>
1110*83a54b2fSSadaf Ebrahimi
1111*83a54b2fSSadaf Ebrahimi
1112*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="parameters-testng-xml">Parameters from <tt>testng.xml</tt></a></h5>
1113*83a54b2fSSadaf Ebrahimi
1114*83a54b2fSSadaf Ebrahimi
1115*83a54b2fSSadaf EbrahimiIf you are using simple values for your parameters, you can specify them in your
1116*83a54b2fSSadaf Ebrahimi<tt>testng.xml</tt>:
1117*83a54b2fSSadaf Ebrahimi
1118*83a54b2fSSadaf Ebrahimi
1119*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Java</h3>
1120*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1121*83a54b2fSSadaf Ebrahimi@Parameters({ "first-name" })
1122*83a54b2fSSadaf Ebrahimi@Test
1123*83a54b2fSSadaf Ebrahimipublic void testSingleString(String firstName) {
1124*83a54b2fSSadaf Ebrahimi  System.out.println("Invoked testString " + firstName);
1125*83a54b2fSSadaf Ebrahimi  assert "Cedric".equals(firstName);
1126*83a54b2fSSadaf Ebrahimi}
1127*83a54b2fSSadaf Ebrahimi</pre>
1128*83a54b2fSSadaf Ebrahimi
1129*83a54b2fSSadaf EbrahimiIn this code, we specify that the parameter <tt>firstName</tt> of your Java method
1130*83a54b2fSSadaf Ebrahimishould receive the value of the XML parameter called <tt>first-name</tt><i>.</i>&nbsp;
1131*83a54b2fSSadaf EbrahimiThis XML parameter is defined in <tt>testng.xml</tt>:<p>
1132*83a54b2fSSadaf Ebrahimi
1133*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
1134*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1135*83a54b2fSSadaf Ebrahimi&lt;suite name="My suite"&gt;
1136*83a54b2fSSadaf Ebrahimi  &lt;parameter name="first-name"  value="Cedric"/&gt;
1137*83a54b2fSSadaf Ebrahimi  &lt;test name="Simple example"&gt;
1138*83a54b2fSSadaf Ebrahimi  &lt;-- ... --&gt;
1139*83a54b2fSSadaf Ebrahimi</pre>
1140*83a54b2fSSadaf Ebrahimi
1141*83a54b2fSSadaf Ebrahimi<h4><span style="font-weight: 400">The same technique can be used for <tt>@Before/After </tt>and <tt>@Factory</tt> annotations:</span></h4>
1142*83a54b2fSSadaf Ebrahimi
1143*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1144*83a54b2fSSadaf Ebrahimi@Parameters({ "datasource", "jdbcDriver" })
1145*83a54b2fSSadaf Ebrahimi@BeforeMethod
1146*83a54b2fSSadaf Ebrahimipublic void beforeTest(String ds, String driver) {
1147*83a54b2fSSadaf Ebrahimi  m_dataSource = ...;                              // look up the value of datasource
1148*83a54b2fSSadaf Ebrahimi  m_jdbcDriver = driver;
1149*83a54b2fSSadaf Ebrahimi}
1150*83a54b2fSSadaf Ebrahimi</pre>
1151*83a54b2fSSadaf Ebrahimi
1152*83a54b2fSSadaf EbrahimiThis time, the two Java parameter <i>ds</i>
1153*83a54b2fSSadaf Ebrahimiand <i>driver</i> will receive the value given to the properties <tt>datasource</tt>
1154*83a54b2fSSadaf Ebrahimiand <tt>jdbc-driver </tt>respectively.&nbsp;
1155*83a54b2fSSadaf Ebrahimi
1156*83a54b2fSSadaf Ebrahimi<p>
1157*83a54b2fSSadaf Ebrahimi
1158*83a54b2fSSadaf EbrahimiParameters can be declared optional with the <a href="../javadocs/org/testng/annotations/Optional.html"><tt>Optional</tt></a> annotation:
1159*83a54b2fSSadaf Ebrahimi
1160*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1161*83a54b2fSSadaf Ebrahimi@Parameters("db")
1162*83a54b2fSSadaf Ebrahimi@Test
1163*83a54b2fSSadaf Ebrahimipublic void testNonExistentParameter(@Optional("mysql") String db) { ... }
1164*83a54b2fSSadaf Ebrahimi</pre>
1165*83a54b2fSSadaf Ebrahimi
1166*83a54b2fSSadaf EbrahimiIf no parameter named "db" is found in your <tt>testng.xml</tt> file, your test method will receive the default value specified inside the <tt>@Optional</tt> annotation: "mysql".
1167*83a54b2fSSadaf Ebrahimi
1168*83a54b2fSSadaf Ebrahimi<p>The <tt>@Parameters</tt> annotation can be placed at the following locations:</p><ul>
1169*83a54b2fSSadaf Ebrahimi	<li>On any method that already has a <tt>@Test</tt>, <tt>@Before/After</tt>
1170*83a54b2fSSadaf Ebrahimi	or <tt>@Factory</tt> annotation.</li><li>On at most one constructor of your test class.&nbsp; In this case,
1171*83a54b2fSSadaf Ebrahimi	TestNG will invoke this particular constructor with the parameters
1172*83a54b2fSSadaf Ebrahimi	initialized to the values specified in <tt>testng.xml</tt> whenever it needs
1173*83a54b2fSSadaf Ebrahimi	to instantiate your test class.&nbsp; This feature can be used to initialize fields
1174*83a54b2fSSadaf Ebrahimi	inside your classes to values that will then be used by your
1175*83a54b2fSSadaf Ebrahimi	test methods.</li></ul>
1176*83a54b2fSSadaf Ebrahimi	<blockquote>
1177*83a54b2fSSadaf Ebrahimi	<p><i>Notes:
1178*83a54b2fSSadaf Ebrahimi
1179*83a54b2fSSadaf Ebrahimi</i>
1180*83a54b2fSSadaf Ebrahimi	<ul>
1181*83a54b2fSSadaf Ebrahimi		<li><i>The XML parameters are mapped to the Java parameters in the same order as
1182*83a54b2fSSadaf Ebrahimithey are found in the annotation, and TestNG will issue an error if the numbers
1183*83a54b2fSSadaf Ebrahimidon't match. </i>
1184*83a54b2fSSadaf Ebrahimi		<li><i>Parameters are scoped. In <tt>testng.xml</tt>, you can declare them either under a
1185*83a54b2fSSadaf Ebrahimi		<tt>&lt;suite&gt;</tt> tag or under <tt>&lt;test&gt;</tt>. If two parameters have the same name, it's the one
1186*83a54b2fSSadaf Ebrahimidefined in <tt>&lt;test&gt;</tt> that has precedence. This is convenient if you need to specify
1187*83a54b2fSSadaf Ebrahimia parameter applicable to all your tests and override its value only for certain
1188*83a54b2fSSadaf Ebrahimitests. </i>
1189*83a54b2fSSadaf Ebrahimi		</ul>
1190*83a54b2fSSadaf Ebrahimi	<p></p>
1191*83a54b2fSSadaf Ebrahimi</blockquote>
1192*83a54b2fSSadaf Ebrahimi
1193*83a54b2fSSadaf Ebrahimi
1194*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="parameters-dataproviders">Parameters with DataProviders</a></h5>
1195*83a54b2fSSadaf Ebrahimi
1196*83a54b2fSSadaf Ebrahimi
1197*83a54b2fSSadaf Ebrahimi<p>Specifying parameters in <tt>testng.xml</tt> might not be sufficient if you need to pass complex parameters, or parameters that need to be created  from Java (complex objects, objects read from a property file or a database, etc...). In this case, you can use a Data Provider to supply the values you need to test.&nbsp; A Data Provider is a method on your class that returns an array of array of objects.&nbsp; This method is annotated with <tt>@DataProvider</tt>:
1198*83a54b2fSSadaf Ebrahimi
1199*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Java</h3>
1200*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1201*83a54b2fSSadaf Ebrahimi//This method will provide data to any test method that declares that its Data Provider
1202*83a54b2fSSadaf Ebrahimi//is named "test1"
1203*83a54b2fSSadaf Ebrahimi@DataProvider(name = "test1")
1204*83a54b2fSSadaf Ebrahimipublic Object[][] createData1() {
1205*83a54b2fSSadaf Ebrahimi return new Object[][] {
1206*83a54b2fSSadaf Ebrahimi   { "Cedric", new Integer(36) },
1207*83a54b2fSSadaf Ebrahimi   { "Anne", new Integer(37)},
1208*83a54b2fSSadaf Ebrahimi };
1209*83a54b2fSSadaf Ebrahimi}
1210*83a54b2fSSadaf Ebrahimi
1211*83a54b2fSSadaf Ebrahimi//This test method declares that its data should be supplied by the Data Provider
1212*83a54b2fSSadaf Ebrahimi//named "test1"
1213*83a54b2fSSadaf Ebrahimi@Test(dataProvider = "test1")
1214*83a54b2fSSadaf Ebrahimipublic void verifyData1(String n1, Integer n2) {
1215*83a54b2fSSadaf Ebrahimi System.out.println(n1 + " " + n2);
1216*83a54b2fSSadaf Ebrahimi}
1217*83a54b2fSSadaf Ebrahimi</pre>
1218*83a54b2fSSadaf Ebrahimiwill print
1219*83a54b2fSSadaf Ebrahimi
1220*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
1221*83a54b2fSSadaf EbrahimiCedric 36
1222*83a54b2fSSadaf EbrahimiAnne 37
1223*83a54b2fSSadaf Ebrahimi</pre>
1224*83a54b2fSSadaf Ebrahimi
1225*83a54b2fSSadaf EbrahimiA <tt>@Test</tt> method specifies its Data Provider with the <tt>dataProvider</tt> attribute.&nbsp;
1226*83a54b2fSSadaf EbrahimiThis name must correspond to a method on the same class annotated with <tt>@DataProvider(name=&quot;...&quot;)</tt>
1227*83a54b2fSSadaf Ebrahimiwith a matching name.
1228*83a54b2fSSadaf Ebrahimi
1229*83a54b2fSSadaf Ebrahimi<p>
1230*83a54b2fSSadaf EbrahimiBy default, the data provider will be looked for in the current test class or one of its base classes.  If you want to put your data provider in a different class, it needs to be a static method or a class with a non-arg constructor, and you specify the class where it can be found in the <tt>dataProviderClass</tt> attribute:
1231*83a54b2fSSadaf Ebrahimi
1232*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">StaticProvider.java</h3>
1233*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1234*83a54b2fSSadaf Ebrahimipublic class StaticProvider {
1235*83a54b2fSSadaf Ebrahimi  @DataProvider(name = "create")
1236*83a54b2fSSadaf Ebrahimi  public static Object[][] createData() {
1237*83a54b2fSSadaf Ebrahimi    return new Object[][] {
1238*83a54b2fSSadaf Ebrahimi      new Object[] { new Integer(42) }
1239*83a54b2fSSadaf Ebrahimi    };
1240*83a54b2fSSadaf Ebrahimi  }
1241*83a54b2fSSadaf Ebrahimi}
1242*83a54b2fSSadaf Ebrahimi
1243*83a54b2fSSadaf Ebrahimipublic class MyTest {
1244*83a54b2fSSadaf Ebrahimi  @Test(dataProvider = "create", dataProviderClass = StaticProvider.class)
1245*83a54b2fSSadaf Ebrahimi  public void test(Integer n) {
1246*83a54b2fSSadaf Ebrahimi    // ...
1247*83a54b2fSSadaf Ebrahimi  }
1248*83a54b2fSSadaf Ebrahimi}
1249*83a54b2fSSadaf Ebrahimi</pre>
1250*83a54b2fSSadaf Ebrahimi
1251*83a54b2fSSadaf EbrahimiThe data provider supports injection too. TestNG will use the test context for the injection.
1252*83a54b2fSSadaf Ebrahimi
1253*83a54b2fSSadaf EbrahimiThe Data Provider method can return one of the following two types:
1254*83a54b2fSSadaf Ebrahimi
1255*83a54b2fSSadaf Ebrahimi<ul>
1256*83a54b2fSSadaf Ebrahimi<li>An array of array of objects (<tt>Object[][]</tt>) where the first dimension's size is the number of times the test method will be invoked and the second dimension size contains an array of objects that must be compatible with the parameter types of the test method. This is the cast illustrated by the example above.</li><li>An <tt>Iterator&lt;Object[]&gt;</tt>.  The only difference with <tt>Object[][]</tt> is that an <tt>Iterator</tt> lets you create your test data lazily.  TestNG will invoke the iterator and then the test method with the parameters returned by this iterator one by one.  This is particularly useful if you have a lot of parameter sets to pass to the method and you don't want to create all of them upfront.
1257*83a54b2fSSadaf Ebrahimi</ul>
1258*83a54b2fSSadaf EbrahimiHere is an example of this feature:
1259*83a54b2fSSadaf Ebrahimi
1260*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1261*83a54b2fSSadaf Ebrahimi@DataProvider(name = "test1")
1262*83a54b2fSSadaf Ebrahimipublic Iterator&lt;Object[]> createData() {
1263*83a54b2fSSadaf Ebrahimi  return new MyIterator(DATA);
1264*83a54b2fSSadaf Ebrahimi}
1265*83a54b2fSSadaf Ebrahimi</pre>
1266*83a54b2fSSadaf Ebrahimi
1267*83a54b2fSSadaf EbrahimiIf you declare your <tt>@DataProvider</tt> as taking a <tt>java.lang.reflect.Method</tt>
1268*83a54b2fSSadaf Ebrahimias first parameter, TestNG will pass the current test method for this
1269*83a54b2fSSadaf Ebrahimifirst parameter.  This is particularly useful when several test methods
1270*83a54b2fSSadaf Ebrahimiuse the same <tt>@DataProvider</tt> and you want it to return different
1271*83a54b2fSSadaf Ebrahimivalues depending on which test method it is supplying data for.
1272*83a54b2fSSadaf Ebrahimi<p>
1273*83a54b2fSSadaf EbrahimiFor example, the following code prints the name of the test method inside its <tt>@DataProvider</tt>:
1274*83a54b2fSSadaf Ebrahimi
1275*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1276*83a54b2fSSadaf Ebrahimi@DataProvider(name = "dp")
1277*83a54b2fSSadaf Ebrahimipublic Object[][] createData(Method m) {
1278*83a54b2fSSadaf Ebrahimi  System.out.println(m.getName());  // print test method name
1279*83a54b2fSSadaf Ebrahimi  return new Object[][] { new Object[] { "Cedric" }};
1280*83a54b2fSSadaf Ebrahimi}
1281*83a54b2fSSadaf Ebrahimi
1282*83a54b2fSSadaf Ebrahimi@Test(dataProvider = "dp")
1283*83a54b2fSSadaf Ebrahimipublic void test1(String s) {
1284*83a54b2fSSadaf Ebrahimi}
1285*83a54b2fSSadaf Ebrahimi
1286*83a54b2fSSadaf Ebrahimi@Test(dataProvider = "dp")
1287*83a54b2fSSadaf Ebrahimipublic void test2(String s) {
1288*83a54b2fSSadaf Ebrahimi}
1289*83a54b2fSSadaf Ebrahimi</pre>
1290*83a54b2fSSadaf Ebrahimi
1291*83a54b2fSSadaf Ebrahimiand will therefore display:
1292*83a54b2fSSadaf Ebrahimi
1293*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
1294*83a54b2fSSadaf Ebrahimitest1
1295*83a54b2fSSadaf Ebrahimitest2
1296*83a54b2fSSadaf Ebrahimi</pre>
1297*83a54b2fSSadaf Ebrahimi
1298*83a54b2fSSadaf EbrahimiData providers can run in parallel with the attribute <tt>parallel</tt>:
1299*83a54b2fSSadaf Ebrahimi
1300*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1301*83a54b2fSSadaf Ebrahimi@DataProvider(parallel = true)
1302*83a54b2fSSadaf Ebrahimi// ...
1303*83a54b2fSSadaf Ebrahimi</pre>
1304*83a54b2fSSadaf Ebrahimi
1305*83a54b2fSSadaf EbrahimiParallel data providers running from an XML file share the same pool of threads, which has a size of 10 by default.  You can modify this value in the <tt>&lt;suite&gt;</tt> tag of your XML file:
1306*83a54b2fSSadaf Ebrahimi
1307*83a54b2fSSadaf Ebrahimi
1308*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1309*83a54b2fSSadaf Ebrahimi&lt;suite name="Suite1" data-provider-thread-count="20" &gt;
1310*83a54b2fSSadaf Ebrahimi...
1311*83a54b2fSSadaf Ebrahimi</pre>
1312*83a54b2fSSadaf Ebrahimi
1313*83a54b2fSSadaf EbrahimiIf you want to run a few specific data providers in a different thread pool, you need to run them from a different XML file.
1314*83a54b2fSSadaf Ebrahimi
1315*83a54b2fSSadaf Ebrahimi<p>
1316*83a54b2fSSadaf Ebrahimi
1317*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="parameters-reports">Parameters in reports</a></h5>
1318*83a54b2fSSadaf Ebrahimi
1319*83a54b2fSSadaf Ebrahimi<p>
1320*83a54b2fSSadaf Ebrahimi
1321*83a54b2fSSadaf EbrahimiParameters used to invoke your test methods are shown in the HTML reports generated by TestNG.  Here is an example:
1322*83a54b2fSSadaf Ebrahimi
1323*83a54b2fSSadaf Ebrahimi<p align="center">
1324*83a54b2fSSadaf Ebrahimi<img src="pics/parameters.png" />
1325*83a54b2fSSadaf Ebrahimi</p>
1326*83a54b2fSSadaf Ebrahimi
1327*83a54b2fSSadaf Ebrahimi
1328*83a54b2fSSadaf Ebrahimi</p>
1329*83a54b2fSSadaf Ebrahimi
1330*83a54b2fSSadaf Ebrahimi
1331*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1332*83a54b2fSSadaf Ebrahimi  DEPENDENCIES
1333*83a54b2fSSadaf Ebrahimi  ------------------------------------>
1334*83a54b2fSSadaf Ebrahimi
1335*83a54b2fSSadaf Ebrahimi
1336*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="dependent-methods">Dependencies</a></h4>
1337*83a54b2fSSadaf Ebrahimi
1338*83a54b2fSSadaf Ebrahimi<p>Sometimes, you need
1339*83a54b2fSSadaf Ebrahimiyour test methods to be invoked in a certain order.&nbsp; Here are a
1340*83a54b2fSSadaf Ebrahimifew examples:
1341*83a54b2fSSadaf Ebrahimi
1342*83a54b2fSSadaf Ebrahimi<ul>
1343*83a54b2fSSadaf Ebrahimi<li>To make sure a certain number of test methods have completed and succeeded
1344*83a54b2fSSadaf Ebrahimibefore running more test methods.
1345*83a54b2fSSadaf Ebrahimi<li>To initialize your tests while wanting this initialization methods to be
1346*83a54b2fSSadaf Ebrahimitest methods as well (methods tagged with <tt>@Before/After</tt> will not be part of the
1347*83a54b2fSSadaf Ebrahimifinal report).
1348*83a54b2fSSadaf Ebrahimi</ul>
1349*83a54b2fSSadaf Ebrahimi
1350*83a54b2fSSadaf EbrahimiTestNG allows you to specify dependencies either with annotations or
1351*83a54b2fSSadaf Ebrahimiin XML.
1352*83a54b2fSSadaf Ebrahimi
1353*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="dependencies-with-annotations">Dependencies with annotations</a></h5>
1354*83a54b2fSSadaf Ebrahimi
1355*83a54b2fSSadaf Ebrahimi<p>You can use the attributes <tt>dependsOnMethods</tt> or <tt>dependsOnGroups</tt>, found on the <tt>@Test</tt> annotation.</p>There are two kinds of dependencies:
1356*83a54b2fSSadaf Ebrahimi
1357*83a54b2fSSadaf Ebrahimi<ul>
1358*83a54b2fSSadaf Ebrahimi<li><b>Hard dependencies</b>.  All the methods you depend on must have run and succeeded for you to run.  If at least one failure occurred in your dependencies, you will not be invoked and marked as a SKIP in the report.
1359*83a54b2fSSadaf Ebrahimi</li>
1360*83a54b2fSSadaf Ebrahimi<li><b>Soft dependencies</b>.  You will always be run after the methods you depend on, even if some of them have failed.  This is useful when you just want to make sure that your test methods are run in a certain order but their success doesn't really depend on the success of others.  A soft dependency is obtained by adding <tt>"alwaysRun=true"</tt> in your <tt>@Test</tt> annotation.
1361*83a54b2fSSadaf Ebrahimi</ul>
1362*83a54b2fSSadaf Ebrahimi
1363*83a54b2fSSadaf EbrahimiHere is an example of a hard dependency:
1364*83a54b2fSSadaf Ebrahimi
1365*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1366*83a54b2fSSadaf Ebrahimi@Test
1367*83a54b2fSSadaf Ebrahimipublic void serverStartedOk() {}
1368*83a54b2fSSadaf Ebrahimi
1369*83a54b2fSSadaf Ebrahimi@Test(dependsOnMethods = { "serverStartedOk" })
1370*83a54b2fSSadaf Ebrahimipublic void method1() {}
1371*83a54b2fSSadaf Ebrahimi</pre>
1372*83a54b2fSSadaf Ebrahimi
1373*83a54b2fSSadaf Ebrahimi<p>In this example, <tt>method1()</tt> is declared as depending on method
1374*83a54b2fSSadaf EbrahimiserverStartedOk(), which guarantees that serverStartedOk()
1375*83a54b2fSSadaf Ebrahimiwill always be invoked first.</p><p>You can also have methods that depend on entire groups:</p>
1376*83a54b2fSSadaf Ebrahimi
1377*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1378*83a54b2fSSadaf Ebrahimi@Test(groups = { "init" })
1379*83a54b2fSSadaf Ebrahimipublic void serverStartedOk() {}
1380*83a54b2fSSadaf Ebrahimi
1381*83a54b2fSSadaf Ebrahimi@Test(groups = { "init" })
1382*83a54b2fSSadaf Ebrahimipublic void initEnvironment() {}
1383*83a54b2fSSadaf Ebrahimi
1384*83a54b2fSSadaf Ebrahimi@Test(dependsOnGroups = { "init.*" })
1385*83a54b2fSSadaf Ebrahimipublic void method1() {}
1386*83a54b2fSSadaf Ebrahimi</pre>
1387*83a54b2fSSadaf Ebrahimi
1388*83a54b2fSSadaf Ebrahimi<p>In this example, method1() is declared as depending on any group matching the
1389*83a54b2fSSadaf Ebrahimiregular expression &quot;init.*&quot;, which guarantees that the methods <tt>serverStartedOk()</tt>
1390*83a54b2fSSadaf Ebrahimiand <tt>initEnvironment()</tt> will always be invoked before <tt>method1()</tt>.&nbsp; </p>
1391*83a54b2fSSadaf Ebrahimi<blockquote>
1392*83a54b2fSSadaf Ebrahimi	<p><i>Note:&nbsp; as stated before, the order of invocation for methods that
1393*83a54b2fSSadaf Ebrahimi	belong in the same group is not guaranteed to be the same across test runs.</i></p></blockquote><p>If a method depended upon fails and you have a hard dependency on it (<tt>alwaysRun=false</tt>, which is the default), the methods that depend on it are <b>not</b>
1394*83a54b2fSSadaf Ebrahimimarked as <tt>FAIL</tt> but as <tt>SKIP</tt>.&nbsp; Skipped methods will be reported as such in
1395*83a54b2fSSadaf Ebrahimithe final report (in a color that is neither red nor green in HTML),
1396*83a54b2fSSadaf Ebrahimiwhich is important since skipped methods are not necessarily failures.</p><p>Both <tt>dependsOnGroups</tt> and <tt>dependsOnMethods</tt> accept regular
1397*83a54b2fSSadaf Ebrahimiexpressions as parameters.&nbsp; For <tt>dependsOnMethods</tt>, if you are
1398*83a54b2fSSadaf Ebrahimidepending on a method which happens to have several overloaded versions, all the
1399*83a54b2fSSadaf Ebrahimioverloaded methods will be invoked.&nbsp; If you only want to invoke one of the
1400*83a54b2fSSadaf Ebrahimioverloaded methods, you should use <tt>dependsOnGroups</tt>.</p><p>For a more advanced example of dependent methods, please refer to
1401*83a54b2fSSadaf Ebrahimi<a href="http://beust.com/weblog/archives/000171.html">this article</a>, which
1402*83a54b2fSSadaf Ebrahimiuses inheritance to provide an elegant solution to the problem of multiple
1403*83a54b2fSSadaf Ebrahimidependencies.</p>
1404*83a54b2fSSadaf Ebrahimi
1405*83a54b2fSSadaf EbrahimiBy default, dependent methods are grouped by class. For example, if method <tt>b()</tt> depends on method <tt>a()</tt> and you have several instances of the class that contains these methods (because of a factory of a data provider), then the invocation order will be as follows:
1406*83a54b2fSSadaf Ebrahimi
1407*83a54b2fSSadaf Ebrahimi<pre class="brush: plain">
1408*83a54b2fSSadaf Ebrahimia(1)
1409*83a54b2fSSadaf Ebrahimia(2)
1410*83a54b2fSSadaf Ebrahimib(2)
1411*83a54b2fSSadaf Ebrahimib(2)
1412*83a54b2fSSadaf Ebrahimi</pre>
1413*83a54b2fSSadaf Ebrahimi
1414*83a54b2fSSadaf EbrahimiTestNG will not run <tt>b()</tt> until all the instances have invoked their <tt>a()</tt> method.
1415*83a54b2fSSadaf Ebrahimi
1416*83a54b2fSSadaf Ebrahimi<p>
1417*83a54b2fSSadaf Ebrahimi
1418*83a54b2fSSadaf EbrahimiThis behavior might not be desirable in certain scenarios, such as for example testing a sign in and sign out of a web browser for various countries. In such a case, you would like the following ordering:
1419*83a54b2fSSadaf Ebrahimi
1420*83a54b2fSSadaf Ebrahimi<pre class="brush: plain">
1421*83a54b2fSSadaf EbrahimisignIn("us")
1422*83a54b2fSSadaf EbrahimisignOut("us")
1423*83a54b2fSSadaf EbrahimisignIn("uk")
1424*83a54b2fSSadaf EbrahimisignOut("uk")
1425*83a54b2fSSadaf Ebrahimi</pre>
1426*83a54b2fSSadaf Ebrahimi
1427*83a54b2fSSadaf EbrahimiFor this ordering, you can use the XML attribute <tt>group-by-instances</tt>. This attribute is valid either on &lt;suite&gt; or &lt;test&gt;:
1428*83a54b2fSSadaf Ebrahimi
1429*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1430*83a54b2fSSadaf Ebrahimi  &lt;suite name="Factory" group-by-instances="true"&gt;
1431*83a54b2fSSadaf Ebrahimior
1432*83a54b2fSSadaf Ebrahimi  &lt;test name="Factory" group-by-instances="true"&gt;
1433*83a54b2fSSadaf Ebrahimi</pre>
1434*83a54b2fSSadaf Ebrahimi
1435*83a54b2fSSadaf Ebrahimi
1436*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="dependencies-in-xml">Dependencies in XML</a></h5>
1437*83a54b2fSSadaf Ebrahimi
1438*83a54b2fSSadaf EbrahimiAlternatively, you can specify your group dependencies in the <tt>testng.xml</tt> file. You use the <tt>&lt;dependencies&gt;</tt> tag to achieve this:
1439*83a54b2fSSadaf Ebrahimi
1440*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1441*83a54b2fSSadaf Ebrahimi  &lt;test name="My suite"&gt;
1442*83a54b2fSSadaf Ebrahimi    &lt;groups&gt;
1443*83a54b2fSSadaf Ebrahimi      &lt;dependencies&gt;
1444*83a54b2fSSadaf Ebrahimi        &lt;group name="c" depends-on="a  b" /&gt;
1445*83a54b2fSSadaf Ebrahimi        &lt;group name="z" depends-on="c" /&gt;
1446*83a54b2fSSadaf Ebrahimi      &lt;/dependencies&gt;
1447*83a54b2fSSadaf Ebrahimi    &lt;/groups&gt;
1448*83a54b2fSSadaf Ebrahimi  &lt;/test&gt;
1449*83a54b2fSSadaf Ebrahimi</pre>
1450*83a54b2fSSadaf Ebrahimi
1451*83a54b2fSSadaf EbrahimiThe <tt>&lt;depends-on&gt;</tt> attribute contains a space-separated list of groups.
1452*83a54b2fSSadaf Ebrahimi
1453*83a54b2fSSadaf Ebrahimi
1454*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1455*83a54b2fSSadaf Ebrahimi  FACTORIES
1456*83a54b2fSSadaf Ebrahimi  ------------------------------------>
1457*83a54b2fSSadaf Ebrahimi
1458*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="factories">Factories</a></h4>
1459*83a54b2fSSadaf Ebrahimi
1460*83a54b2fSSadaf EbrahimiFactories allow you to create tests dynamically. For example, imagine you
1461*83a54b2fSSadaf Ebrahimiwant to create a test method that will access a page on a Web site several
1462*83a54b2fSSadaf Ebrahimitimes, and you want to invoke it with different values:
1463*83a54b2fSSadaf Ebrahimi
1464*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">TestWebServer.java</h3>
1465*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1466*83a54b2fSSadaf Ebrahimipublic class TestWebServer {
1467*83a54b2fSSadaf Ebrahimi  @Test(parameters = { "number-of-times" })
1468*83a54b2fSSadaf Ebrahimi  public void accessPage(int numberOfTimes) {
1469*83a54b2fSSadaf Ebrahimi    while (numberOfTimes-- > 0) {
1470*83a54b2fSSadaf Ebrahimi     // access the web page
1471*83a54b2fSSadaf Ebrahimi    }
1472*83a54b2fSSadaf Ebrahimi  }
1473*83a54b2fSSadaf Ebrahimi}
1474*83a54b2fSSadaf Ebrahimi</pre>
1475*83a54b2fSSadaf Ebrahimi
1476*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
1477*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1478*83a54b2fSSadaf Ebrahimi&lt;test name="T1"&gt;
1479*83a54b2fSSadaf Ebrahimi&nbsp;&nbsp;&lt;parameter name="number-of-times" value="10"/&gt;
1480*83a54b2fSSadaf Ebrahimi&nbsp;&nbsp;&lt;class name= "TestWebServer" /&gt;
1481*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
1482*83a54b2fSSadaf Ebrahimi
1483*83a54b2fSSadaf Ebrahimi&lt;test name="T2"&gt;
1484*83a54b2fSSadaf Ebrahimi&nbsp;&nbsp;&lt;parameter name="number-of-times" value="20"/&gt;
1485*83a54b2fSSadaf Ebrahimi&nbsp;&nbsp;&lt;class name= "TestWebServer"/&gt;
1486*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
1487*83a54b2fSSadaf Ebrahimi
1488*83a54b2fSSadaf Ebrahimi&lt;test name="T3"&gt;
1489*83a54b2fSSadaf Ebrahimi&nbsp;&nbsp;&lt;parameter name="number-of-times" value="30"/&gt;
1490*83a54b2fSSadaf Ebrahimi&nbsp;&nbsp;&lt;class name= "TestWebServer"/&gt;
1491*83a54b2fSSadaf Ebrahimi&lt;/test&gt;
1492*83a54b2fSSadaf Ebrahimi</pre>
1493*83a54b2fSSadaf Ebrahimi
1494*83a54b2fSSadaf EbrahimiThis can become quickly impossible to manage, so instead, you should use a factory:
1495*83a54b2fSSadaf Ebrahimi
1496*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">WebTestFactory.java</h3>
1497*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1498*83a54b2fSSadaf Ebrahimipublic class WebTestFactory {
1499*83a54b2fSSadaf Ebrahimi  @Factory
1500*83a54b2fSSadaf Ebrahimi  public Object[] createInstances() {
1501*83a54b2fSSadaf Ebrahimi   Object[] result = new Object[10];
1502*83a54b2fSSadaf Ebrahimi   for (int i = 0; i < 10; i++) {
1503*83a54b2fSSadaf Ebrahimi      result[i] = new WebTest(i * 10);
1504*83a54b2fSSadaf Ebrahimi    }
1505*83a54b2fSSadaf Ebrahimi    return result;
1506*83a54b2fSSadaf Ebrahimi  }
1507*83a54b2fSSadaf Ebrahimi}
1508*83a54b2fSSadaf Ebrahimi</pre>
1509*83a54b2fSSadaf Ebrahimi
1510*83a54b2fSSadaf Ebrahimiand the new test class is now:
1511*83a54b2fSSadaf Ebrahimi
1512*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">WebTest.java</h3>
1513*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1514*83a54b2fSSadaf Ebrahimipublic class WebTest {
1515*83a54b2fSSadaf Ebrahimi  private int m_numberOfTimes;
1516*83a54b2fSSadaf Ebrahimi  public WebTest(int numberOfTimes) {
1517*83a54b2fSSadaf Ebrahimi    m_numberOfTimes = numberOfTimes;
1518*83a54b2fSSadaf Ebrahimi  }
1519*83a54b2fSSadaf Ebrahimi
1520*83a54b2fSSadaf Ebrahimi  @Test
1521*83a54b2fSSadaf Ebrahimi  public void testServer() {
1522*83a54b2fSSadaf Ebrahimi   for (int i = 0; i < m_numberOfTimes; i++) {
1523*83a54b2fSSadaf Ebrahimi     // access the web page
1524*83a54b2fSSadaf Ebrahimi    }
1525*83a54b2fSSadaf Ebrahimi  }
1526*83a54b2fSSadaf Ebrahimi}
1527*83a54b2fSSadaf Ebrahimi</pre>
1528*83a54b2fSSadaf Ebrahimi
1529*83a54b2fSSadaf Ebrahimi<p>Your <tt>testng.xml</tt> only needs to reference the class that
1530*83a54b2fSSadaf Ebrahimicontains the factory method, since the test instances themselves will be created
1531*83a54b2fSSadaf Ebrahimiat runtime:</p>
1532*83a54b2fSSadaf Ebrahimi
1533*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1534*83a54b2fSSadaf Ebrahimi&lt;class name="WebTestFactory" /&gt;
1535*83a54b2fSSadaf Ebrahimi</pre>
1536*83a54b2fSSadaf Ebrahimi
1537*83a54b2fSSadaf Ebrahimi<p>The factory method can receive parameters just like <tt>@Test</tt> and <tt>@Before/After</tt> and it must return <tt>Object[]</tt>.&nbsp;
1538*83a54b2fSSadaf EbrahimiThe objects returned can be of any class (not necessarily the same class as the
1539*83a54b2fSSadaf Ebrahimifactory class) and they don't even need to contain TestNG annotations (in which
1540*83a54b2fSSadaf Ebrahimicase they will be ignored by TestNG).</p>
1541*83a54b2fSSadaf Ebrahimi
1542*83a54b2fSSadaf Ebrahimi<p>
1543*83a54b2fSSadaf Ebrahimi
1544*83a54b2fSSadaf EbrahimiFactories can also be used with data providers, and you can leverage this functionality by putting the <tt>@Factory</tt> annotation either on a regular method or on a constructor. Here is an example of a constructor factory:
1545*83a54b2fSSadaf Ebrahimi
1546*83a54b2fSSadaf Ebrahimi<pre class="brush:java">
1547*83a54b2fSSadaf Ebrahimi  @Factory(dataProvider = "dp")
1548*83a54b2fSSadaf Ebrahimi  public FactoryDataProviderSampleTest(int n) {
1549*83a54b2fSSadaf Ebrahimi    super(n);
1550*83a54b2fSSadaf Ebrahimi  }
1551*83a54b2fSSadaf Ebrahimi
1552*83a54b2fSSadaf Ebrahimi  @DataProvider
1553*83a54b2fSSadaf Ebrahimi  static public Object[][] dp() {
1554*83a54b2fSSadaf Ebrahimi    return new Object[][] {
1555*83a54b2fSSadaf Ebrahimi      new Object[] { 41 },
1556*83a54b2fSSadaf Ebrahimi      new Object[] { 42 },
1557*83a54b2fSSadaf Ebrahimi    };
1558*83a54b2fSSadaf Ebrahimi  }
1559*83a54b2fSSadaf Ebrahimi</pre>
1560*83a54b2fSSadaf Ebrahimi
1561*83a54b2fSSadaf EbrahimiThe example will make TestNG create two test classes, on with the constructor invoked with the value 41 and the other with 42.
1562*83a54b2fSSadaf Ebrahimi
1563*83a54b2fSSadaf Ebrahimi
1564*83a54b2fSSadaf Ebrahimi
1565*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1566*83a54b2fSSadaf Ebrahimi  CLASS LEVEL ANNOTATIONS
1567*83a54b2fSSadaf Ebrahimi  ------------------------------------>
1568*83a54b2fSSadaf Ebrahimi
1569*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="class-level">Class level annotations</a></h4>
1570*83a54b2fSSadaf Ebrahimi
1571*83a54b2fSSadaf EbrahimiThe <tt>@Test</tt> annotation can be put on a class instead of a test method:
1572*83a54b2fSSadaf Ebrahimi
1573*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Test1.java</h3>
1574*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1575*83a54b2fSSadaf Ebrahimi@Test
1576*83a54b2fSSadaf Ebrahimipublic class Test1 {
1577*83a54b2fSSadaf Ebrahimi  public void test1() {
1578*83a54b2fSSadaf Ebrahimi  }
1579*83a54b2fSSadaf Ebrahimi
1580*83a54b2fSSadaf Ebrahimi  public void test2() {
1581*83a54b2fSSadaf Ebrahimi  }
1582*83a54b2fSSadaf Ebrahimi}
1583*83a54b2fSSadaf Ebrahimi</pre>
1584*83a54b2fSSadaf EbrahimiThe effect of a class level <tt>@Test</tt> annotation is to make all the public methods of this class to become test methods even if they are not annotated.  You can still repeat the <tt>@Test</tt> annotation on a method if you want to add certain attributes.
1585*83a54b2fSSadaf Ebrahimi<p>
1586*83a54b2fSSadaf Ebrahimi
1587*83a54b2fSSadaf EbrahimiFor example:
1588*83a54b2fSSadaf Ebrahimi
1589*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Test1.java</h3>
1590*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1591*83a54b2fSSadaf Ebrahimi@Test
1592*83a54b2fSSadaf Ebrahimipublic class Test1 {
1593*83a54b2fSSadaf Ebrahimi  public void test1() {
1594*83a54b2fSSadaf Ebrahimi  }
1595*83a54b2fSSadaf Ebrahimi
1596*83a54b2fSSadaf Ebrahimi  @Test(groups = "g1")
1597*83a54b2fSSadaf Ebrahimi  public void test2() {
1598*83a54b2fSSadaf Ebrahimi  }
1599*83a54b2fSSadaf Ebrahimi}
1600*83a54b2fSSadaf Ebrahimi</pre>
1601*83a54b2fSSadaf Ebrahimiwill make both <tt>test1()</tt> and <tt>test2()</tt> test methods but on top of that, <tt>test2()</tt> now belongs to the group "g1".
1602*83a54b2fSSadaf Ebrahimi<p>
1603*83a54b2fSSadaf Ebrahimi
1604*83a54b2fSSadaf Ebrahimi
1605*83a54b2fSSadaf Ebrahimi
1606*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1607*83a54b2fSSadaf Ebrahimi  PARALLEL RUNNING
1608*83a54b2fSSadaf Ebrahimi  ------------------------------------>
1609*83a54b2fSSadaf Ebrahimi
1610*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="parallel-running">Parallelism and time-outs</a></h4>
1611*83a54b2fSSadaf Ebrahimi
1612*83a54b2fSSadaf EbrahimiYou can  instruct TestNG to run your tests in separate threads in various ways.
1613*83a54b2fSSadaf Ebrahimi
1614*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="parallel-suites">Parallel suites</a></h5>
1615*83a54b2fSSadaf Ebrahimi
1616*83a54b2fSSadaf EbrahimiThis is useful if you are running several suite files (e.g. "<tt>java org.testng.TestNG testng1.xml testng2.xml"</tt>) and you want each of these suites to be run in a separate thread. You can use the following command line flag to specify the size of a thread pool:
1617*83a54b2fSSadaf Ebrahimi
1618*83a54b2fSSadaf Ebrahimi<pre class="brush: plain">
1619*83a54b2fSSadaf Ebrahimijava org.testng.TestNG -suitethreadpoolsize 3 testng1.xml testng2.xml testng3.xml
1620*83a54b2fSSadaf Ebrahimi</pre>
1621*83a54b2fSSadaf Ebrahimi
1622*83a54b2fSSadaf EbrahimiThe corresponding ant task name is <tt>suitethreadpoolsize</tt>.
1623*83a54b2fSSadaf Ebrahimi
1624*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="parallel-tests">Parallel tests, classes and methods</a></h5>
1625*83a54b2fSSadaf EbrahimiThe <i>parallel</i> attribute on the &lt;suite&gt; tag can take one of following values:
1626*83a54b2fSSadaf Ebrahimi
1627*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1628*83a54b2fSSadaf Ebrahimi&lt;suite name="My suite" parallel="methods" thread-count="5"&gt;
1629*83a54b2fSSadaf Ebrahimi</pre>
1630*83a54b2fSSadaf Ebrahimi
1631*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1632*83a54b2fSSadaf Ebrahimi&lt;suite name="My suite" parallel="tests" thread-count="5"&gt;
1633*83a54b2fSSadaf Ebrahimi</pre>
1634*83a54b2fSSadaf Ebrahimi
1635*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1636*83a54b2fSSadaf Ebrahimi&lt;suite name="My suite" parallel="classes" thread-count="5"&gt;
1637*83a54b2fSSadaf Ebrahimi</pre>
1638*83a54b2fSSadaf Ebrahimi
1639*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1640*83a54b2fSSadaf Ebrahimi&lt;suite name="My suite" parallel="instances" thread-count="5"&gt;
1641*83a54b2fSSadaf Ebrahimi</pre>
1642*83a54b2fSSadaf Ebrahimi
1643*83a54b2fSSadaf Ebrahimi<ul>
1644*83a54b2fSSadaf Ebrahimi<li>
1645*83a54b2fSSadaf Ebrahimi<b><tt>parallel="methods"</tt></b>:  TestNG will run all your test methods in separate threads. Dependent methods will also run in separate threads but they will respect the order that you specified.
1646*83a54b2fSSadaf Ebrahimi</li>
1647*83a54b2fSSadaf Ebrahimi
1648*83a54b2fSSadaf Ebrahimi<br>
1649*83a54b2fSSadaf Ebrahimi
1650*83a54b2fSSadaf Ebrahimi<li>
1651*83a54b2fSSadaf Ebrahimi<b><tt>parallel="tests"</tt></b>:  TestNG will run all the methods in the same &lt;test&gt; tag in the same thread, but each &lt;test&gt; tag will be in a separate thread.  This allows you to group all your classes that are not thread safe in the same &lt;test&gt; and guarantee they will all run in the same thread while taking advantage of TestNG using as many threads as possible to run your tests.
1652*83a54b2fSSadaf Ebrahimi</li>
1653*83a54b2fSSadaf Ebrahimi
1654*83a54b2fSSadaf Ebrahimi<br>
1655*83a54b2fSSadaf Ebrahimi
1656*83a54b2fSSadaf Ebrahimi<li>
1657*83a54b2fSSadaf Ebrahimi<b><tt>parallel="classes"</tt></b>:  TestNG will run all the methods in the same class in the same thread, but each class will be run in a separate thread.
1658*83a54b2fSSadaf Ebrahimi</li>
1659*83a54b2fSSadaf Ebrahimi
1660*83a54b2fSSadaf Ebrahimi<br/>
1661*83a54b2fSSadaf Ebrahimi
1662*83a54b2fSSadaf Ebrahimi<li>
1663*83a54b2fSSadaf Ebrahimi<b><tt>parallel="instances"</tt></b>:  TestNG will run all the methods in the same instance in the same thread, but two methods on two different instances will be running in different threads.
1664*83a54b2fSSadaf Ebrahimi</li>
1665*83a54b2fSSadaf Ebrahimi
1666*83a54b2fSSadaf Ebrahimi</ul>
1667*83a54b2fSSadaf Ebrahimi
1668*83a54b2fSSadaf Ebrahimi<p>
1669*83a54b2fSSadaf Ebrahimi
1670*83a54b2fSSadaf Ebrahimi
1671*83a54b2fSSadaf EbrahimiAdditionally, the attribute <i>
1672*83a54b2fSSadaf Ebrahimithread-count</i> allows you to specify how many threads should be allocated for
1673*83a54b2fSSadaf Ebrahimithis execution.<blockquote>
1674*83a54b2fSSadaf Ebrahimi	<p><i>Note: the <tt>@Test</tt> attribute <tt>timeOut</tt> works in both
1675*83a54b2fSSadaf Ebrahimi	parallel and non-parallel mode.</i></p></blockquote>You can also specify that a <tt>@Test</tt> method should be invoked from different threads.  You can use the attribute <tt>threadPoolSize</tt> to achieve this result:
1676*83a54b2fSSadaf Ebrahimi
1677*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1678*83a54b2fSSadaf Ebrahimi@Test(threadPoolSize = 3, invocationCount = 10,  timeOut = 10000)
1679*83a54b2fSSadaf Ebrahimipublic void testServer() {
1680*83a54b2fSSadaf Ebrahimi</pre>
1681*83a54b2fSSadaf EbrahimiIn this example, the function <tt>testServer</tt> will be invoked ten times from three different threads.  Additionally, a time-out of ten seconds guarantees that none of the threads will block on this thread forever.
1682*83a54b2fSSadaf Ebrahimi
1683*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1684*83a54b2fSSadaf Ebrahimi  RERUNNING
1685*83a54b2fSSadaf Ebrahimi  ------------------------------------>
1686*83a54b2fSSadaf Ebrahimi
1687*83a54b2fSSadaf Ebrahimi
1688*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="rerunning">Rerunning failed tests</a></h4>
1689*83a54b2fSSadaf Ebrahimi
1690*83a54b2fSSadaf EbrahimiEvery time tests fail in a suite, TestNG creates a file called <tt>testng-failed.xml</tt> in the output directory.
1691*83a54b2fSSadaf EbrahimiThis XML file contains the necessary information to rerun only these methods
1692*83a54b2fSSadaf Ebrahimithat failed, allowing you to quickly reproduce the failures without having to
1693*83a54b2fSSadaf Ebrahimirun the entirety of your tests.&nbsp; Therefore, a typical session would look
1694*83a54b2fSSadaf Ebrahimilike this:
1695*83a54b2fSSadaf Ebrahimi
1696*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
1697*83a54b2fSSadaf Ebrahimijava -classpath testng.jar;%CLASSPATH% org.testng.TestNG -d test-outputs testng.xml
1698*83a54b2fSSadaf Ebrahimijava -classpath testng.jar;%CLASSPATH% org.testng.TestNG -d test-outputs test-outputs\testng-failed.xml
1699*83a54b2fSSadaf Ebrahimi</pre>
1700*83a54b2fSSadaf Ebrahimi
1701*83a54b2fSSadaf Ebrahimi<p>Note that <tt>testng-failed.xml</tt> will contain all the necessary dependent
1702*83a54b2fSSadaf Ebrahimimethods so that you are guaranteed to run the methods that failed without any
1703*83a54b2fSSadaf EbrahimiSKIP failures.</p>
1704*83a54b2fSSadaf Ebrahimi
1705*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="junit">JUnit tests</a></h4>
1706*83a54b2fSSadaf Ebrahimi
1707*83a54b2fSSadaf EbrahimiTestNG can run JUnit 3 and JUnit 4 tests.&nbsp; All you need to do is
1708*83a54b2fSSadaf Ebrahimiput the JUnit jar file on the classpath, specify your JUnit test classes in the <tt>testng.classNames</tt>
1709*83a54b2fSSadaf Ebrahimiproperty and set the <tt>testng.junit</tt> property to true:
1710*83a54b2fSSadaf Ebrahimi
1711*83a54b2fSSadaf Ebrahimi<p></p>
1712*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
1713*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1714*83a54b2fSSadaf Ebrahimi&lt;test name="Test1" junit="true"&gt;
1715*83a54b2fSSadaf Ebrahimi  &lt;classes&gt;
1716*83a54b2fSSadaf Ebrahimi    &lt;!-- ... --&gt;
1717*83a54b2fSSadaf Ebrahimi</pre>
1718*83a54b2fSSadaf Ebrahimi
1719*83a54b2fSSadaf Ebrahimi<p>The behavior of TestNG in this case is similar to JUnit depending on the JUnit version found on the class path:<br>
1720*83a54b2fSSadaf Ebrahimi</p>
1721*83a54b2fSSadaf Ebrahimi<ul>
1722*83a54b2fSSadaf Ebrahimi    <li>JUnit 3:
1723*83a54b2fSSadaf Ebrahimi<ul>
1724*83a54b2fSSadaf Ebrahimi  <li>All methods starting with test* in your classes will be run</li><li>If there is a method setUp() on your test class, it will be invoked before
1725*83a54b2fSSadaf Ebrahimi	every test method</li><li>If there is a method tearDown() on your test class, it will be invoked
1726*83a54b2fSSadaf Ebrahimi	before after every test method</li><li>If your test class contains a method suite(), all the tests returned by
1727*83a54b2fSSadaf Ebrahimi	this method will be invoked</li></ul>
1728*83a54b2fSSadaf Ebrahimi    </li>
1729*83a54b2fSSadaf Ebrahimi    <li>JUnit 4:
1730*83a54b2fSSadaf Ebrahimi        <ul>
1731*83a54b2fSSadaf Ebrahimi            <li>TestNG will use the <tt>org.junit.runner.JUnitCore</tt> runner to run your tests</li>
1732*83a54b2fSSadaf Ebrahimi        </ul>
1733*83a54b2fSSadaf Ebrahimi    </li>
1734*83a54b2fSSadaf Ebrahimi</ul>
1735*83a54b2fSSadaf Ebrahimi
1736*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1737*83a54b2fSSadaf Ebrahimi  JUNIT
1738*83a54b2fSSadaf Ebrahimi--------------------------------------->
1739*83a54b2fSSadaf Ebrahimi
1740*83a54b2fSSadaf Ebrahimi
1741*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1742*83a54b2fSSadaf Ebrahimi  RUNNING TESTNG
1743*83a54b2fSSadaf Ebrahimi ------------------------------------>
1744*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="running-testng-programmatically">Running TestNG programmatically</a></h4>
1745*83a54b2fSSadaf Ebrahimi
1746*83a54b2fSSadaf EbrahimiYou can invoke TestNG from your own programs very easily:
1747*83a54b2fSSadaf Ebrahimi
1748*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Java</h3>
1749*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1750*83a54b2fSSadaf EbrahimiTestListenerAdapter tla = new TestListenerAdapter();
1751*83a54b2fSSadaf EbrahimiTestNG testng = new TestNG();
1752*83a54b2fSSadaf Ebrahimitestng.setTestClasses(new Class[] { Run2.class });
1753*83a54b2fSSadaf Ebrahimitestng.addListener(tla);
1754*83a54b2fSSadaf Ebrahimitestng.run();
1755*83a54b2fSSadaf Ebrahimi</pre>
1756*83a54b2fSSadaf Ebrahimi
1757*83a54b2fSSadaf EbrahimiThis example creates a <tt><a href="http://testng.org/javadocs/org/testng/TestNG.html">TestNG</a></tt> object and runs the test class <tt>Run2</tt>.  It also adds a <tt>TestListener</tt>.  You can either use the adapter class <tt><a href="http://testng.org/javadocs/org/testng/TestListenerAdapter.html">org.testng.TestListenerAdapter</a></tt> or implement <tt><a href="http://testng.org/javadocs/org/testng/ITestListener.html">org.testng.ITestListener</a></tt> yourself.  This interface contains various callback methods that let you keep track of when a test starts, succeeds, fails, etc...
1758*83a54b2fSSadaf Ebrahimi<p>
1759*83a54b2fSSadaf EbrahimiSimilary, you can invoke TestNG on a <tt>testng.xml</tt> file or you can create a virtual <tt>testng.xml</tt> file yourself.  In order to do this, you can use the classes found the package <tt><a href="http://testng.org/javadocs/org/testng/xml/package-frame.html">org.testng.xml</a></tt>:  <tt><a href="http://testng.org/javadocs/org/testng/xml/XmlClass.html">XmlClass</a></tt>, <tt><a href="http://testng.org/javadocs/org/testng/xml/XmlTest.html">XmlTest</a></tt>, etc...  Each of these classes correspond to their XML tag counterpart.
1760*83a54b2fSSadaf Ebrahimi<p>
1761*83a54b2fSSadaf EbrahimiFor example, suppose you want to create the following virtual file:
1762*83a54b2fSSadaf Ebrahimi
1763*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1764*83a54b2fSSadaf Ebrahimi&lt;suite name="TmpSuite" &gt;
1765*83a54b2fSSadaf Ebrahimi  &lt;test name="TmpTest" &gt;
1766*83a54b2fSSadaf Ebrahimi    &lt;classes&gt;
1767*83a54b2fSSadaf Ebrahimi      &lt;class name="test.failures.Child"  /&gt;
1768*83a54b2fSSadaf Ebrahimi    &lt;classes&gt;
1769*83a54b2fSSadaf Ebrahimi    &lt;/test&gt;
1770*83a54b2fSSadaf Ebrahimi&lt;/suite&gt;
1771*83a54b2fSSadaf Ebrahimi</pre>
1772*83a54b2fSSadaf Ebrahimi
1773*83a54b2fSSadaf EbrahimiYou would use the following code:
1774*83a54b2fSSadaf Ebrahimi
1775*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1776*83a54b2fSSadaf EbrahimiXmlSuite suite = new XmlSuite();
1777*83a54b2fSSadaf Ebrahimisuite.setName("TmpSuite");
1778*83a54b2fSSadaf Ebrahimi
1779*83a54b2fSSadaf EbrahimiXmlTest test = new XmlTest(suite);
1780*83a54b2fSSadaf Ebrahimitest.setName("TmpTest");
1781*83a54b2fSSadaf EbrahimiList&lt;XmlClass&gt; classes = new ArrayList&lt;XmlClass&gt;();
1782*83a54b2fSSadaf Ebrahimiclasses.add(new XmlClass("test.failures.Child"));
1783*83a54b2fSSadaf Ebrahimitest.setXmlClasses(classes) ;
1784*83a54b2fSSadaf Ebrahimi</pre>
1785*83a54b2fSSadaf EbrahimiAnd then you can pass this <tt>XmlSuite</tt> to TestNG:
1786*83a54b2fSSadaf Ebrahimi
1787*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1788*83a54b2fSSadaf EbrahimiList&lt;XmlSuite&gt; suites = new ArrayList&lt;XmlSuite&gt;();
1789*83a54b2fSSadaf Ebrahimisuites.add(suite);
1790*83a54b2fSSadaf EbrahimiTestNG tng = new TestNG();
1791*83a54b2fSSadaf Ebrahimitng.setXmlSuites(suites);
1792*83a54b2fSSadaf Ebrahimitng.run();
1793*83a54b2fSSadaf Ebrahimi</pre>
1794*83a54b2fSSadaf Ebrahimi
1795*83a54b2fSSadaf Ebrahimi<p>Please see the <a href="../doc/javadocs/org/testng/package-summary.html" target="mainFrame">JavaDocs</a> for the entire API.</p><p>
1796*83a54b2fSSadaf Ebrahimi
1797*83a54b2fSSadaf Ebrahimi
1798*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1799*83a54b2fSSadaf Ebrahimi  BEANSHELL
1800*83a54b2fSSadaf Ebrahimi ------------------------------------>
1801*83a54b2fSSadaf Ebrahimi
1802*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="beanshell">BeanShell and advanced group selection</a></h4>
1803*83a54b2fSSadaf Ebrahimi
1804*83a54b2fSSadaf Ebrahimi
1805*83a54b2fSSadaf Ebrahimi	<p>If the <tt>&lt;include&gt;</tt> and <tt>&lt;exclude&gt;</tt> tags in <tt>testng.xml</tt> are not enough for your needs, you can use a <a href="http://beanshell.org">BeanShell</a> expression to decide whether a certain test method should be included in a test run or not. You specify this expression just under the <tt>&lt;test&gt;</tt> tag:</p>
1806*83a54b2fSSadaf Ebrahimi
1807*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">testng.xml</h3>
1808*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
1809*83a54b2fSSadaf Ebrahimi&lt;test name="BeanShell test"&gt;
1810*83a54b2fSSadaf Ebrahimi   &lt;method-selectors&gt;
1811*83a54b2fSSadaf Ebrahimi     &lt;method-selector&gt;
1812*83a54b2fSSadaf Ebrahimi       &lt;script language="beanshell"&gt;&lt;![CDATA[
1813*83a54b2fSSadaf Ebrahimi         groups.containsKey("test1")
1814*83a54b2fSSadaf Ebrahimi       ]]&gt;&lt;/script&gt;
1815*83a54b2fSSadaf Ebrahimi     &lt;/method-selector&gt;
1816*83a54b2fSSadaf Ebrahimi   &lt;/method-selectors&gt;
1817*83a54b2fSSadaf Ebrahimi  &lt;!-- ... --&gt;
1818*83a54b2fSSadaf Ebrahimi</pre>
1819*83a54b2fSSadaf Ebrahimi
1820*83a54b2fSSadaf EbrahimiWhen a <tt>&lt;script&gt;</tt> tag is found in <tt>testng.xml</tt>, TestNG will ignore subsequent <tt>&lt;include&gt;</tt> and <tt>&lt;exclude&gt;</tt> of groups and methods in the current <tt>&lt;test&gt;</tt> tag:&nbsp; your BeanShell expression will be the only way to decide whether a test method is included or not.</p><p>Here are additional information on the BeanShell script:</p><ul>
1821*83a54b2fSSadaf Ebrahimi<li>
1822*83a54b2fSSadaf EbrahimiIt must return a boolean value.&nbsp; Except for this constraint, any valid BeanShell code is allowed (for example, you might want to return <tt>true </tt>during week days and false during weekends, which would allow you to run tests differently depending on the date).<br>&nbsp;
1823*83a54b2fSSadaf Ebrahimi</li>
1824*83a54b2fSSadaf Ebrahimi<li>
1825*83a54b2fSSadaf EbrahimiTestNG defines the following variables for your convenience:<br>&nbsp; <b><tt>java.lang.reflect.Method method</tt></b>:&nbsp; the current test method.<br>&nbsp; <b>org.testng.ITestNGMethod testngMethod</b>:&nbsp; the description of the current test method.<br>&nbsp; <b><tt>java.util.Map&lt;String, String&gt; groups</tt></b>:&nbsp; a map of the groups the current test method belongs to.<br>&nbsp;
1826*83a54b2fSSadaf Ebrahimi</li>
1827*83a54b2fSSadaf Ebrahimi<li>
1828*83a54b2fSSadaf EbrahimiYou might want to surround your expression with a <tt>CDATA</tt> declaration (as shown above) to avoid tedious quoting of reserved XML characters).<br>&nbsp;
1829*83a54b2fSSadaf Ebrahimi</li>
1830*83a54b2fSSadaf Ebrahimi</ul>
1831*83a54b2fSSadaf Ebrahimi
1832*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1833*83a54b2fSSadaf Ebrahimi  ANNOTATION TRANSFORMERS
1834*83a54b2fSSadaf Ebrahimi ------------------------------------>
1835*83a54b2fSSadaf Ebrahimi
1836*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="annotationtransformers">Annotation Transformers</a></h4>
1837*83a54b2fSSadaf Ebrahimi
1838*83a54b2fSSadaf EbrahimiTestNG allows you to modify the content of all the annotations at runtime.  This is especially useful if the annotations in the source code are right most of the time, but there are a few situations where you'd like to override their value.
1839*83a54b2fSSadaf Ebrahimi<p>
1840*83a54b2fSSadaf Ebrahimi
1841*83a54b2fSSadaf EbrahimiIn order to achieve this, you need to use an Annotation Transformer.
1842*83a54b2fSSadaf Ebrahimi
1843*83a54b2fSSadaf Ebrahimi<p>
1844*83a54b2fSSadaf Ebrahimi
1845*83a54b2fSSadaf EbrahimiAn Annotation Transformer is a class that implements the following interface:
1846*83a54b2fSSadaf Ebrahimi
1847*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1848*83a54b2fSSadaf Ebrahimipublic interface IAnnotationTransformer {
1849*83a54b2fSSadaf Ebrahimi
1850*83a54b2fSSadaf Ebrahimi  /**
1851*83a54b2fSSadaf Ebrahimi   * This method will be invoked by TestNG to give you a chance
1852*83a54b2fSSadaf Ebrahimi   * to modify a TestNG annotation read from your test classes.
1853*83a54b2fSSadaf Ebrahimi   * You can change the values you need by calling any of the
1854*83a54b2fSSadaf Ebrahimi   * setters on the ITest interface.
1855*83a54b2fSSadaf Ebrahimi   *
1856*83a54b2fSSadaf Ebrahimi   * Note that only one of the three parameters testClass,
1857*83a54b2fSSadaf Ebrahimi   * testConstructor and testMethod will be non-null.
1858*83a54b2fSSadaf Ebrahimi   *
1859*83a54b2fSSadaf Ebrahimi   * @param annotation The annotation that was read from your
1860*83a54b2fSSadaf Ebrahimi   * test class.
1861*83a54b2fSSadaf Ebrahimi   * @param testClass If the annotation was found on a class, this
1862*83a54b2fSSadaf Ebrahimi   * parameter represents this class (null otherwise).
1863*83a54b2fSSadaf Ebrahimi   * @param testConstructor If the annotation was found on a constructor,
1864*83a54b2fSSadaf Ebrahimi   * this parameter represents this constructor (null otherwise).
1865*83a54b2fSSadaf Ebrahimi   * @param testMethod If the annotation was found on a method,
1866*83a54b2fSSadaf Ebrahimi   * this parameter represents this method (null otherwise).
1867*83a54b2fSSadaf Ebrahimi   */
1868*83a54b2fSSadaf Ebrahimi  public void transform(ITest annotation, Class testClass,
1869*83a54b2fSSadaf Ebrahimi      Constructor testConstructor, Method testMethod);
1870*83a54b2fSSadaf Ebrahimi}
1871*83a54b2fSSadaf Ebrahimi</pre>
1872*83a54b2fSSadaf Ebrahimi
1873*83a54b2fSSadaf EbrahimiLike all the other TestNG listeners, you can specify this class either on the command line or with ant:
1874*83a54b2fSSadaf Ebrahimi
1875*83a54b2fSSadaf Ebrahimi<p>
1876*83a54b2fSSadaf Ebrahimi
1877*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1878*83a54b2fSSadaf Ebrahimi  java org.testng.TestNG -listener MyTransformer testng.xml
1879*83a54b2fSSadaf Ebrahimi</pre>
1880*83a54b2fSSadaf Ebrahimi
1881*83a54b2fSSadaf Ebrahimior programmatically:
1882*83a54b2fSSadaf Ebrahimi
1883*83a54b2fSSadaf Ebrahimi<p>
1884*83a54b2fSSadaf Ebrahimi
1885*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1886*83a54b2fSSadaf Ebrahimi  TestNG tng = new TestNG();
1887*83a54b2fSSadaf Ebrahimi  tng.setAnnotationTransformer(new MyTransformer());
1888*83a54b2fSSadaf Ebrahimi  // ...
1889*83a54b2fSSadaf Ebrahimi</pre>
1890*83a54b2fSSadaf Ebrahimi
1891*83a54b2fSSadaf EbrahimiWhen the method <tt>transform()</tt> is invoked, you can call any of the setters on the <tt>ITest test</tt> parameter to alter its value before TestNG proceeds further.
1892*83a54b2fSSadaf Ebrahimi<p>
1893*83a54b2fSSadaf EbrahimiFor example, here is how you would override the attribute <tt>invocationCount</tt> but only on the test method <tt>invoke()</tt> of one of your test classes:
1894*83a54b2fSSadaf Ebrahimi
1895*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1896*83a54b2fSSadaf Ebrahimi  public class MyTransformer implements IAnnotationTransformer {
1897*83a54b2fSSadaf Ebrahimi    public void transform(ITest annotation, Class testClass,
1898*83a54b2fSSadaf Ebrahimi        Constructor testConstructor, Method testMethod)
1899*83a54b2fSSadaf Ebrahimi    {
1900*83a54b2fSSadaf Ebrahimi      if ("invoke".equals(testMethod.getName())) {
1901*83a54b2fSSadaf Ebrahimi        annotation.setInvocationCount(5);
1902*83a54b2fSSadaf Ebrahimi      }
1903*83a54b2fSSadaf Ebrahimi    }
1904*83a54b2fSSadaf Ebrahimi  }
1905*83a54b2fSSadaf Ebrahimi</pre>
1906*83a54b2fSSadaf Ebrahimi
1907*83a54b2fSSadaf Ebrahimi<tt>IAnnotationTransformer</tt> only lets you modify a <tt>@Test</tt> annotation.  If you need to modify another TestNG annotation (a configuration annotation, <tt>@Factory</tt> or <tt>@DataProvider</tt>), use an <tt>IAnnotationTransformer2</tt>.
1908*83a54b2fSSadaf Ebrahimi
1909*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1910*83a54b2fSSadaf Ebrahimi  METHOD INTERCEPTORS
1911*83a54b2fSSadaf Ebrahimi ------------------------------------>
1912*83a54b2fSSadaf Ebrahimi
1913*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="methodinterceptors">Method Interceptors</a></h4>
1914*83a54b2fSSadaf Ebrahimi
1915*83a54b2fSSadaf EbrahimiOnce TestNG has calculated in what order the test methods will be invoked, these methods are split in two groups:
1916*83a54b2fSSadaf Ebrahimi
1917*83a54b2fSSadaf Ebrahimi<ul>
1918*83a54b2fSSadaf Ebrahimi  <li><em>Methods run sequentially</em>.  These are all the test methods that have dependencies or dependents.  These methods will be run in a specific order.
1919*83a54b2fSSadaf Ebrahimi  <li><em>Methods run in no particular order</em>.  These are all the methods that don't belong in the first category.  The order in which these test methods are run is random and can vary from one run to the next (although by default, TestNG will try to group test methods by class).
1920*83a54b2fSSadaf Ebrahimi</ul>
1921*83a54b2fSSadaf Ebrahimi
1922*83a54b2fSSadaf EbrahimiIn order to give you more control on the methods that belong to the second category, TestNG defines the following interface:
1923*83a54b2fSSadaf Ebrahimi
1924*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1925*83a54b2fSSadaf Ebrahimipublic interface IMethodInterceptor {
1926*83a54b2fSSadaf Ebrahimi
1927*83a54b2fSSadaf Ebrahimi  List&lt;IMethodInstance&gt; intercept(List&lt;IMethodInstance&gt; methods, ITestContext context);
1928*83a54b2fSSadaf Ebrahimi
1929*83a54b2fSSadaf Ebrahimi}
1930*83a54b2fSSadaf Ebrahimi
1931*83a54b2fSSadaf Ebrahimi</pre>
1932*83a54b2fSSadaf Ebrahimi
1933*83a54b2fSSadaf EbrahimiThe list of methods passed in parameters are all the methods that can be run in any order.  Your <tt>intercept</tt> method is expected to return a similar list of <tt>IMethodInstance</tt>, which can be either of the following:
1934*83a54b2fSSadaf Ebrahimi
1935*83a54b2fSSadaf Ebrahimi<ul>
1936*83a54b2fSSadaf Ebrahimi  <li>The same list you received in parameter but in a different order.
1937*83a54b2fSSadaf Ebrahimi  <li>A smaller list of <tt>IMethodInstance</tt> objects.
1938*83a54b2fSSadaf Ebrahimi  <li>A bigger list of <tt>IMethodInstance</tt> objects.
1939*83a54b2fSSadaf Ebrahimi</ul>
1940*83a54b2fSSadaf Ebrahimi
1941*83a54b2fSSadaf EbrahimiOnce you have defined your interceptor, you pass it to TestNG as a listener.  For example:
1942*83a54b2fSSadaf Ebrahimi
1943*83a54b2fSSadaf Ebrahimi<p>
1944*83a54b2fSSadaf Ebrahimi
1945*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Shell</h3>
1946*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
1947*83a54b2fSSadaf Ebrahimijava -classpath "testng-jdk15.jar:test/build" org.testng.TestNG -listener test.methodinterceptors.NullMethodInterceptor
1948*83a54b2fSSadaf Ebrahimi   -testclass test.methodinterceptors.FooTest
1949*83a54b2fSSadaf Ebrahimi</pre>
1950*83a54b2fSSadaf Ebrahimi
1951*83a54b2fSSadaf EbrahimiFor the equivalent <tt>ant</tt> syntax, see the <tt>listeners</tt> attribute in the <a href="ant.html">ant documentation</a>.
1952*83a54b2fSSadaf Ebrahimi<p>
1953*83a54b2fSSadaf EbrahimiFor example, here is a Method Interceptor that will reorder the methods so that test methods that belong to the group "fast" are always run first:
1954*83a54b2fSSadaf Ebrahimi
1955*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
1956*83a54b2fSSadaf Ebrahimipublic List&lt;IMethodInstance&gt; intercept(List&lt;IMethodInstance&gt; methods, ITestContext context) {
1957*83a54b2fSSadaf Ebrahimi  List&lt;IMethodInstance&gt; result = new ArrayList&lt;IMethodInstance&gt;();
1958*83a54b2fSSadaf Ebrahimi  for (IMethodInstance m : methods) {
1959*83a54b2fSSadaf Ebrahimi    Test test = m.getMethod().getConstructorOrMethod().getAnnotation(Test.class);
1960*83a54b2fSSadaf Ebrahimi    Set&lt;String&gt; groups = new HashSet&lt;String&gt;();
1961*83a54b2fSSadaf Ebrahimi    for (String group : test.groups()) {
1962*83a54b2fSSadaf Ebrahimi      groups.add(group);
1963*83a54b2fSSadaf Ebrahimi    }
1964*83a54b2fSSadaf Ebrahimi    if (groups.contains("fast")) {
1965*83a54b2fSSadaf Ebrahimi      result.add(0, m);
1966*83a54b2fSSadaf Ebrahimi    }
1967*83a54b2fSSadaf Ebrahimi    else {
1968*83a54b2fSSadaf Ebrahimi      result.add(m);
1969*83a54b2fSSadaf Ebrahimi    }
1970*83a54b2fSSadaf Ebrahimi  }
1971*83a54b2fSSadaf Ebrahimi  return result;
1972*83a54b2fSSadaf Ebrahimi}
1973*83a54b2fSSadaf Ebrahimi</pre>
1974*83a54b2fSSadaf Ebrahimi
1975*83a54b2fSSadaf Ebrahimi
1976*83a54b2fSSadaf Ebrahimi<!-------------------------------------
1977*83a54b2fSSadaf Ebrahimi  TESTNG LISTENERS
1978*83a54b2fSSadaf Ebrahimi ------------------------------------>
1979*83a54b2fSSadaf Ebrahimi
1980*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="testng-listeners">TestNG Listeners</a></h4>
1981*83a54b2fSSadaf Ebrahimi
1982*83a54b2fSSadaf EbrahimiThere are several interfaces that allow you to modify TestNG's behavior.  These interfaces are broadly called "TestNG Listeners".  Here are a few listeners:
1983*83a54b2fSSadaf Ebrahimi
1984*83a54b2fSSadaf Ebrahimi<ul>
1985*83a54b2fSSadaf Ebrahimi  <li><tt>IAnnotationTransformer</tt> (<a href="#annotationtransformers">doc</a>, <a href="../javadocs/org/testng/IAnnotationTransformer.html">javadoc</a>)
1986*83a54b2fSSadaf Ebrahimi  <li><tt>IAnnotationTransformer2</tt> (<a href="#annotationtransformers">doc</a>, <a href="../javadocs/org/testng/IAnnotationTransformer2.html">javadoc</a>)
1987*83a54b2fSSadaf Ebrahimi  <li><tt>IHookable</tt> (<a href="#ihookable">doc</a>, <a href="../javadocs/org/testng/IHookable.html">javadoc</a>)
1988*83a54b2fSSadaf Ebrahimi  <li><tt>IInvokedMethodListener</tt> (doc, <a href="../javadocs/org/testng/IInvokedMethodListener.html">javadoc</a>)
1989*83a54b2fSSadaf Ebrahimi  <li><tt>IMethodInterceptor</tt> (<a href="#methodinterceptors">doc</a>, <a href="../javadocs/org/testng/IMethodInterceptor.html">javadoc</a>)
1990*83a54b2fSSadaf Ebrahimi  <li><tt>IReporter</tt> (<a href="#logging-reporters">doc</a>, <a href="../javadocs/org/testng/IReporter.html">javadoc</a>)
1991*83a54b2fSSadaf Ebrahimi  <li><tt>ISuiteListener</tt> (doc, <a href="../javadocs/org/testng/ISuiteListener.html">javadoc</a>)
1992*83a54b2fSSadaf Ebrahimi  <li><tt>ITestListener</tt> (<a href="#logging-listeners">doc</a>, <a href="../javadocs/org/testng/ITestListener.html">javadoc</a>)
1993*83a54b2fSSadaf Ebrahimi</ul>
1994*83a54b2fSSadaf Ebrahimi
1995*83a54b2fSSadaf EbrahimiWhen you implement one of these interfaces, you can let TestNG know about it with either of the following ways:
1996*83a54b2fSSadaf Ebrahimi
1997*83a54b2fSSadaf Ebrahimi<ul>
1998*83a54b2fSSadaf Ebrahimi  <li><a href="#running-testng">Using -listener on the command line.</a>
1999*83a54b2fSSadaf Ebrahimi  <li><a href="ant.html">Using &lt;listeners&gt; with ant.</a>
2000*83a54b2fSSadaf Ebrahimi  <li>Using &lt;listeners&gt; in your <tt>testng.xml</tt> file.
2001*83a54b2fSSadaf Ebrahimi  <li>Using the <tt>@Listeners</tt> annotation on any of your test classes.
2002*83a54b2fSSadaf Ebrahimi  <li>Using <tt>ServiceLoader</tt>.
2003*83a54b2fSSadaf Ebrahimi</ul>
2004*83a54b2fSSadaf Ebrahimi
2005*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="listeners-testng-xml">Specifying listeners with <tt>testng.xml</tt> or in Java</a></h5>
2006*83a54b2fSSadaf Ebrahimi
2007*83a54b2fSSadaf EbrahimiHere is how you can define listeners in your <tt>testng.xml</tt> file:
2008*83a54b2fSSadaf Ebrahimi
2009*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
2010*83a54b2fSSadaf Ebrahimi&lt;suite&gt;
2011*83a54b2fSSadaf Ebrahimi
2012*83a54b2fSSadaf Ebrahimi  &lt;listeners&gt;
2013*83a54b2fSSadaf Ebrahimi    &lt;listener class-name="com.example.MyListener" /&gt;
2014*83a54b2fSSadaf Ebrahimi    &lt;listener class-name="com.example.MyMethodInterceptor" /&gt;
2015*83a54b2fSSadaf Ebrahimi  &lt;/listeners&gt;
2016*83a54b2fSSadaf Ebrahimi
2017*83a54b2fSSadaf Ebrahimi...
2018*83a54b2fSSadaf Ebrahimi
2019*83a54b2fSSadaf Ebrahimi</pre>
2020*83a54b2fSSadaf Ebrahimi
2021*83a54b2fSSadaf EbrahimiOr if you prefer to define these listeners in Java:
2022*83a54b2fSSadaf Ebrahimi
2023*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2024*83a54b2fSSadaf Ebrahimi@Listeners({ com.example.MyListener.class, com.example.MyMethodInterceptor.class })
2025*83a54b2fSSadaf Ebrahimipublic class MyTest {
2026*83a54b2fSSadaf Ebrahimi  // ...
2027*83a54b2fSSadaf Ebrahimi}
2028*83a54b2fSSadaf Ebrahimi</pre>
2029*83a54b2fSSadaf Ebrahimi
2030*83a54b2fSSadaf EbrahimiThe <tt>@Listeners</tt> annotation can contain any class that extends <tt>org.testng.ITestNGListener</tt> <b>except</b> <tt>IAnnotationTransformer</tt> and <tt>IAnnotationTransformer2</tt>.  The reason is that these listeners need to be known very early in the process so that TestNG can use them to rewrite your annotations, therefore you need to specify these listeners in your <tt>testng.xml</tt> file.
2031*83a54b2fSSadaf Ebrahimi
2032*83a54b2fSSadaf Ebrahimi<p>
2033*83a54b2fSSadaf Ebrahimi
2034*83a54b2fSSadaf EbrahimiNote that the <tt>@Listeners</tt> annotation will apply to your entire suite file, just as if you had specified it in a <tt>testng.xml</tt> file. If you want to restrict its scope (for example, only running on the current class), the code in your listener could first check the test method that's about to run and decide what to do then.
2035*83a54b2fSSadaf Ebrahimi
2036*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="listeners-service-loader">Specifying listeners with <tt>ServiceLoader</tt></a></h5>
2037*83a54b2fSSadaf Ebrahimi
2038*83a54b2fSSadaf EbrahimiFinally, the JDK offers a very elegant mechanism to specify implementations of interfaces on the class path via the <tt><a href="http://download.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html">ServiceLoader</a></tt> class.
2039*83a54b2fSSadaf Ebrahimi
2040*83a54b2fSSadaf Ebrahimi<p>
2041*83a54b2fSSadaf EbrahimiWith ServiceLoader, all you need to do is create a jar file that contains your listener(s) and a few configuration files, put that jar file on the classpath when you run TestNG and TestNG will automatically find them.
2042*83a54b2fSSadaf Ebrahimi<p>
2043*83a54b2fSSadaf Ebrahimi
2044*83a54b2fSSadaf EbrahimiHere is a concrete example of how it works.
2045*83a54b2fSSadaf Ebrahimi
2046*83a54b2fSSadaf Ebrahimi<p>
2047*83a54b2fSSadaf Ebrahimi
2048*83a54b2fSSadaf EbrahimiLet's start by creating a listener (any TestNG listener should work):
2049*83a54b2fSSadaf Ebrahimi
2050*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2051*83a54b2fSSadaf Ebrahimipackage test.tmp;
2052*83a54b2fSSadaf Ebrahimi
2053*83a54b2fSSadaf Ebrahimipublic class TmpSuiteListener implements ISuiteListener {
2054*83a54b2fSSadaf Ebrahimi  @Override
2055*83a54b2fSSadaf Ebrahimi  public void onFinish(ISuite suite) {
2056*83a54b2fSSadaf Ebrahimi    System.out.println("Finishing");
2057*83a54b2fSSadaf Ebrahimi  }
2058*83a54b2fSSadaf Ebrahimi
2059*83a54b2fSSadaf Ebrahimi  @Override
2060*83a54b2fSSadaf Ebrahimi  public void onStart(ISuite suite) {
2061*83a54b2fSSadaf Ebrahimi    System.out.println("Starting");
2062*83a54b2fSSadaf Ebrahimi  }
2063*83a54b2fSSadaf Ebrahimi}
2064*83a54b2fSSadaf Ebrahimi</pre>
2065*83a54b2fSSadaf Ebrahimi
2066*83a54b2fSSadaf EbrahimiCompile this file, then create a file at the location <tt>META-INF/services/org.testng.ITestNGListener</tt>, which will name the implementation(s) you want for this interface.
2067*83a54b2fSSadaf Ebrahimi
2068*83a54b2fSSadaf Ebrahimi<p>
2069*83a54b2fSSadaf Ebrahimi
2070*83a54b2fSSadaf EbrahimiYou should end up with the following directory structure, with only two files:
2071*83a54b2fSSadaf Ebrahimi
2072*83a54b2fSSadaf Ebrahimi<pre class="brush: plain; highlight: [4, 7]">
2073*83a54b2fSSadaf Ebrahimi$ tree
2074*83a54b2fSSadaf Ebrahimi|____META-INF
2075*83a54b2fSSadaf Ebrahimi| |____services
2076*83a54b2fSSadaf Ebrahimi| | |____org.testng.ITestNGListener
2077*83a54b2fSSadaf Ebrahimi|____test
2078*83a54b2fSSadaf Ebrahimi| |____tmp
2079*83a54b2fSSadaf Ebrahimi| | |____TmpSuiteListener.class
2080*83a54b2fSSadaf Ebrahimi
2081*83a54b2fSSadaf Ebrahimi$ cat META-INF/services/org.testng.ITestNGListener
2082*83a54b2fSSadaf Ebrahimitest.tmp.TmpSuiteListener
2083*83a54b2fSSadaf Ebrahimi</pre>
2084*83a54b2fSSadaf Ebrahimi
2085*83a54b2fSSadaf EbrahimiCreate a jar of this directory:
2086*83a54b2fSSadaf Ebrahimi
2087*83a54b2fSSadaf Ebrahimi<pre class="brush: plain">
2088*83a54b2fSSadaf Ebrahimi$ jar cvf ../sl.jar .
2089*83a54b2fSSadaf Ebrahimiadded manifest
2090*83a54b2fSSadaf Ebrahimiignoring entry META-INF/
2091*83a54b2fSSadaf Ebrahimiadding: META-INF/services/(in = 0) (out= 0)(stored 0%)
2092*83a54b2fSSadaf Ebrahimiadding: META-INF/services/org.testng.ITestNGListener(in = 26) (out= 28)(deflated -7%)
2093*83a54b2fSSadaf Ebrahimiadding: test/(in = 0) (out= 0)(stored 0%)
2094*83a54b2fSSadaf Ebrahimiadding: test/tmp/(in = 0) (out= 0)(stored 0%)
2095*83a54b2fSSadaf Ebrahimiadding: test/tmp/TmpSuiteListener.class(in = 849) (out= 470)(deflated 44%)
2096*83a54b2fSSadaf Ebrahimi</pre>
2097*83a54b2fSSadaf Ebrahimi
2098*83a54b2fSSadaf EbrahimiNext, put this jar file on your classpath when you invoke TestNG:
2099*83a54b2fSSadaf Ebrahimi
2100*83a54b2fSSadaf Ebrahimi<pre class="brush: plain">
2101*83a54b2fSSadaf Ebrahimi$ java -classpath sl.jar:testng.jar org.testng.TestNG testng-single.yaml
2102*83a54b2fSSadaf EbrahimiStarting
2103*83a54b2fSSadaf Ebrahimif2 11 2
2104*83a54b2fSSadaf EbrahimiPASSED: f2("2")
2105*83a54b2fSSadaf EbrahimiFinishing
2106*83a54b2fSSadaf Ebrahimi</pre>
2107*83a54b2fSSadaf Ebrahimi
2108*83a54b2fSSadaf EbrahimiThis mechanism allows you to apply the same set of listeners to an entire organization just by adding a jar file to the classpath, instead of asking every single developer to remember to specify these listeners in their testng.xml file.
2109*83a54b2fSSadaf Ebrahimi
2110*83a54b2fSSadaf Ebrahimi<!-------------------------------------
2111*83a54b2fSSadaf Ebrahimi  DEPENDENCY INJECTION
2112*83a54b2fSSadaf Ebrahimi ------------------------------------>
2113*83a54b2fSSadaf Ebrahimi
2114*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="dependency-injection">Dependency injection</a></h4>
2115*83a54b2fSSadaf Ebrahimi
2116*83a54b2fSSadaf EbrahimiTestNG supports two different kinds of dependency injection: native (performed by TestNG itself) and external (performed by a dependency injection framework such as Guice).
2117*83a54b2fSSadaf Ebrahimi
2118*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="native-dependency-injection">Native dependency injection</a></h5>
2119*83a54b2fSSadaf Ebrahimi
2120*83a54b2fSSadaf EbrahimiTestNG lets you declare additional parameters in your methods.  When this happens, TestNG will automatically fill these parameters with the right value.  Dependency injection can be used in the following places:
2121*83a54b2fSSadaf Ebrahimi
2122*83a54b2fSSadaf Ebrahimi<ul>
2123*83a54b2fSSadaf Ebrahimi
2124*83a54b2fSSadaf Ebrahimi<li>
2125*83a54b2fSSadaf Ebrahimi  Any @Before method or @Test method can declare a parameter of type <tt>ITestContext</tt>.
2126*83a54b2fSSadaf Ebrahimi<li>
2127*83a54b2fSSadaf Ebrahimi  Any @AfterMethod method can declare a parameter of type <tt>ITestResult</tt>, which will reflect the result of the test method that was just run.
2128*83a54b2fSSadaf Ebrahimi<li>
2129*83a54b2fSSadaf Ebrahimi  Any @Before and @After methods can declare a parameter of type <tt>XmlTest</tt>, which contain the current <tt>&lt;test&gt;</tt> tag.
2130*83a54b2fSSadaf Ebrahimi<li>
2131*83a54b2fSSadaf Ebrahimi  Any @BeforeMethod (and @AfterMethod) can declare a parameter of type
2132*83a54b2fSSadaf Ebrahimi  <tt>java.lang.reflect.Method</tt>.  This parameter will receive the
2133*83a54b2fSSadaf Ebrahimi  test method that will be called once this @BeforeMethod finishes (or
2134*83a54b2fSSadaf Ebrahimi  after the method as run for @AfterMethod).
2135*83a54b2fSSadaf Ebrahimi<li>
2136*83a54b2fSSadaf Ebrahimi  Any @BeforeMethod can declare a parameter of type <tt>Object[]</tt>.  This parameter will receive the list of parameters that are about to be fed to the upcoming test method, which could be either injected by TestNG, such as <tt>java.lang.reflect.Method</tt> or come from a <tt>@DataProvider</tt>.
2137*83a54b2fSSadaf Ebrahimi<li>
2138*83a54b2fSSadaf Ebrahimi  Any @DataProvider can declare a parameter of type
2139*83a54b2fSSadaf Ebrahimi  <tt>ITestContext</tt> or <tt>java.lang.reflect.Method</tt>.  The
2140*83a54b2fSSadaf Ebrahimi  latter parameter will receive the test method that is about to be invoked.
2141*83a54b2fSSadaf Ebrahimi</ul>
2142*83a54b2fSSadaf Ebrahimi
2143*83a54b2fSSadaf EbrahimiYou can turn off injection with the <tt>@NoInjection</tt> annotation:
2144*83a54b2fSSadaf Ebrahimi
2145*83a54b2fSSadaf Ebrahimi<pre class="brush: java; highlight: [9]">
2146*83a54b2fSSadaf Ebrahimipublic class NoInjectionTest {
2147*83a54b2fSSadaf Ebrahimi
2148*83a54b2fSSadaf Ebrahimi  @DataProvider(name = "provider")
2149*83a54b2fSSadaf Ebrahimi  public Object[][] provide() throws Exception {
2150*83a54b2fSSadaf Ebrahimi      return new Object[][] { { CC.class.getMethod("f") } };
2151*83a54b2fSSadaf Ebrahimi  }
2152*83a54b2fSSadaf Ebrahimi
2153*83a54b2fSSadaf Ebrahimi  @Test(dataProvider = "provider")
2154*83a54b2fSSadaf Ebrahimi  public void withoutInjection(@NoInjection Method m) {
2155*83a54b2fSSadaf Ebrahimi      Assert.assertEquals(m.getName(), "f");
2156*83a54b2fSSadaf Ebrahimi  }
2157*83a54b2fSSadaf Ebrahimi
2158*83a54b2fSSadaf Ebrahimi  @Test(dataProvider = "provider")
2159*83a54b2fSSadaf Ebrahimi  public void withInjection(Method m) {
2160*83a54b2fSSadaf Ebrahimi      Assert.assertEquals(m.getName(), "withInjection");
2161*83a54b2fSSadaf Ebrahimi  }
2162*83a54b2fSSadaf Ebrahimi}
2163*83a54b2fSSadaf Ebrahimi</pre>
2164*83a54b2fSSadaf Ebrahimi
2165*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="guice-dependency-injection">Guice dependency injection</a></h5>
2166*83a54b2fSSadaf Ebrahimi
2167*83a54b2fSSadaf EbrahimiIf you use Guice, TestNG gives you an easy way to inject your test objects with a Guice module:
2168*83a54b2fSSadaf Ebrahimi
2169*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2170*83a54b2fSSadaf Ebrahimi@Guice(modules = GuiceExampleModule.class)
2171*83a54b2fSSadaf Ebrahimipublic class GuiceTest extends SimpleBaseTest {
2172*83a54b2fSSadaf Ebrahimi
2173*83a54b2fSSadaf Ebrahimi  @Inject
2174*83a54b2fSSadaf Ebrahimi  ISingleton m_singleton;
2175*83a54b2fSSadaf Ebrahimi
2176*83a54b2fSSadaf Ebrahimi  @Test
2177*83a54b2fSSadaf Ebrahimi  public void singletonShouldWork() {
2178*83a54b2fSSadaf Ebrahimi    m_singleton.doSomething();
2179*83a54b2fSSadaf Ebrahimi  }
2180*83a54b2fSSadaf Ebrahimi
2181*83a54b2fSSadaf Ebrahimi}
2182*83a54b2fSSadaf Ebrahimi</pre>
2183*83a54b2fSSadaf Ebrahimi
2184*83a54b2fSSadaf EbrahimiIn this example, <tt>GuiceExampleModule</tt> is expected to bind the interface <tt>ISingleton</tt> to some concrete class:
2185*83a54b2fSSadaf Ebrahimi
2186*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2187*83a54b2fSSadaf Ebrahimipublic class GuiceExampleModule implements Module {
2188*83a54b2fSSadaf Ebrahimi
2189*83a54b2fSSadaf Ebrahimi  @Override
2190*83a54b2fSSadaf Ebrahimi  public void configure(Binder binder) {
2191*83a54b2fSSadaf Ebrahimi    binder.bind(ISingleton.class).to(ExampleSingleton.class).in(Singleton.class);
2192*83a54b2fSSadaf Ebrahimi  }
2193*83a54b2fSSadaf Ebrahimi
2194*83a54b2fSSadaf Ebrahimi}
2195*83a54b2fSSadaf Ebrahimi</pre>
2196*83a54b2fSSadaf Ebrahimi
2197*83a54b2fSSadaf EbrahimiIf you need more flexibility in specifying which modules should be used to instantiate your test classes, you can specify a module factory:
2198*83a54b2fSSadaf Ebrahimi
2199*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2200*83a54b2fSSadaf Ebrahimi@Guice(moduleFactory = ModuleFactory.class)
2201*83a54b2fSSadaf Ebrahimipublic class GuiceModuleFactoryTest {
2202*83a54b2fSSadaf Ebrahimi
2203*83a54b2fSSadaf Ebrahimi  @Inject
2204*83a54b2fSSadaf Ebrahimi  ISingleton m_singleton;
2205*83a54b2fSSadaf Ebrahimi
2206*83a54b2fSSadaf Ebrahimi  @Test
2207*83a54b2fSSadaf Ebrahimi  public void singletonShouldWork() {
2208*83a54b2fSSadaf Ebrahimi    m_singleton.doSomething();
2209*83a54b2fSSadaf Ebrahimi  }
2210*83a54b2fSSadaf Ebrahimi}
2211*83a54b2fSSadaf Ebrahimi</pre>
2212*83a54b2fSSadaf Ebrahimi
2213*83a54b2fSSadaf EbrahimiThe module factory needs to implement the interface <a href="../javadocs/org/testng/IModuleFactory.html">IModuleFactory</a>:
2214*83a54b2fSSadaf Ebrahimi
2215*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2216*83a54b2fSSadaf Ebrahimipublic interface IModuleFactory {
2217*83a54b2fSSadaf Ebrahimi /**
2218*83a54b2fSSadaf Ebrahimi   * @param context The current test context
2219*83a54b2fSSadaf Ebrahimi   * @param testClass The test class
2220*83a54b2fSSadaf Ebrahimi   *
2221*83a54b2fSSadaf Ebrahimi   * @return The Guice module that should be used to get an instance of this
2222*83a54b2fSSadaf Ebrahimi   * test class.
2223*83a54b2fSSadaf Ebrahimi   */
2224*83a54b2fSSadaf Ebrahimi  Module createModule(ITestContext context, Class&lt;?&gt; testClass);
2225*83a54b2fSSadaf Ebrahimi}
2226*83a54b2fSSadaf Ebrahimi</pre>
2227*83a54b2fSSadaf Ebrahimi
2228*83a54b2fSSadaf EbrahimiYour factory will be passed an instance of the test context and the test class that TestNG needs to instantiate. Your <tt>createModule</tt> method should return a Guice Module that will know how to instantiate this test class. You can use the test context to find out more information about your environment, such as parameters specified in <tt>testng.xml</tt>, etc...
2229*83a54b2fSSadaf Ebrahimi
2230*83a54b2fSSadaf EbrahimiYou will get even more flexibility and Guice power with <tt>parent-module</tt> and <tt>guice-stage</tt> suite parameters.
2231*83a54b2fSSadaf Ebrahimi<tt>guice-stage</tt> allow you to chose the <a href="https://github.com/google/guice/wiki/Bootstrap"><tt>Stage</tt></a> used to create the parent injector.
2232*83a54b2fSSadaf EbrahimiThe default one is <tt>DEVELOPMENT</tt>. Other allowed values are <tt>PRODUCTION</tt> and <tt>TOOL</tt>.
2233*83a54b2fSSadaf EbrahimiHere is how you can define parent-module in your test.xml file:
2234*83a54b2fSSadaf Ebrahimi
2235*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
2236*83a54b2fSSadaf Ebrahimi<suite parent-module="com.example.SuiteParenModule" guice-stage="PRODUCTION">
2237*83a54b2fSSadaf Ebrahimi</suite>
2238*83a54b2fSSadaf Ebrahimi</pre>
2239*83a54b2fSSadaf Ebrahimi
2240*83a54b2fSSadaf EbrahimiTestNG will create this module only once for given suite. Will also use this module for obtaining instances of test specific Guice modules and module factories, then will create child injector for each test class.
2241*83a54b2fSSadaf Ebrahimi
2242*83a54b2fSSadaf EbrahimiWith such approach you can declare all common bindings in parent-module also you can inject binding declared in parent-module in module and module factory. Here is an example of this functionality:
2243*83a54b2fSSadaf Ebrahimi
2244*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2245*83a54b2fSSadaf Ebrahimipackage com.example;
2246*83a54b2fSSadaf Ebrahimi
2247*83a54b2fSSadaf Ebrahimipublic class ParentModule extends AbstractModule {
2248*83a54b2fSSadaf Ebrahimi  @Override
2249*83a54b2fSSadaf Ebrahimi  protected void conigure() {
2250*83a54b2fSSadaf Ebrahimi    bind(MyService.class).toProvider(MyServiceProvider.class);
2251*83a54b2fSSadaf Ebrahimi    bind(MyContext.class).to(MyContextImpl.class).in(Singleton.class);
2252*83a54b2fSSadaf Ebrahimi  }
2253*83a54b2fSSadaf Ebrahimi}
2254*83a54b2fSSadaf Ebrahimi</pre>
2255*83a54b2fSSadaf Ebrahimi
2256*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2257*83a54b2fSSadaf Ebrahimipackage com.example;
2258*83a54b2fSSadaf Ebrahimi
2259*83a54b2fSSadaf Ebrahimipublic class TestModule extends AbstractModule {
2260*83a54b2fSSadaf Ebrahimi  private final MyContext myContext;
2261*83a54b2fSSadaf Ebrahimi
2262*83a54b2fSSadaf Ebrahimi  @Inject
2263*83a54b2fSSadaf Ebrahimi  TestModule(MyContext myContext) {
2264*83a54b2fSSadaf Ebrahimi    this.myContext = myContext
2265*83a54b2fSSadaf Ebrahimi  }
2266*83a54b2fSSadaf Ebrahimi
2267*83a54b2fSSadaf Ebrahimi  @Override
2268*83a54b2fSSadaf Ebrahimi  protected void configure() {
2269*83a54b2fSSadaf Ebrahimi    bind(MySession.class).toInstance(myContext.getSession());
2270*83a54b2fSSadaf Ebrahimi  }
2271*83a54b2fSSadaf Ebrahimi}
2272*83a54b2fSSadaf Ebrahimi</pre>
2273*83a54b2fSSadaf Ebrahimi
2274*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
2275*83a54b2fSSadaf Ebrahimi<suite parent-module="com.example.ParentModule">
2276*83a54b2fSSadaf Ebrahimi</suite>
2277*83a54b2fSSadaf Ebrahimi</pre>
2278*83a54b2fSSadaf Ebrahimi
2279*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2280*83a54b2fSSadaf Ebrahimipackage com.example;
2281*83a54b2fSSadaf Ebrahimi
2282*83a54b2fSSadaf Ebrahimi@Test
2283*83a54b2fSSadaf Ebrahimi@Guice(modules = TestModule.class)
2284*83a54b2fSSadaf Ebrahimipublic class TestClass {
2285*83a54b2fSSadaf Ebrahimi  @Inject
2286*83a54b2fSSadaf Ebrahimi  MyService myService;
2287*83a54b2fSSadaf Ebrahimi  @Inject
2288*83a54b2fSSadaf Ebrahimi  MySession mySession;
2289*83a54b2fSSadaf Ebrahimi
2290*83a54b2fSSadaf Ebrahimi  public void testServiceWithSession() {
2291*83a54b2fSSadaf Ebrahimi    myService.serve(mySession);
2292*83a54b2fSSadaf Ebrahimi  }
2293*83a54b2fSSadaf Ebrahimi}
2294*83a54b2fSSadaf Ebrahimi</pre>
2295*83a54b2fSSadaf Ebrahimi
2296*83a54b2fSSadaf EbrahimiAs you see ParentModule declares binding for MyService and MyContext classes. Then MyContext is injected using constructor injection into TestModule class, which also declare binding for MySession. Then parent-module in test XML file is set to ParentModule class, this enables injection in TestModule. Later in TestClass you see two injections:
2297*83a54b2fSSadaf Ebrahimi * MyService - binding taken from ParentModule
2298*83a54b2fSSadaf Ebrahimi * MySession - binding taken from TestModule
2299*83a54b2fSSadaf EbrahimiThis configuration ensures you that all tests in this suite will be run with same session instance, the MyContextImpl object is only created once per suite, this give you possibility to configure common environment state for all tests in suite.
2300*83a54b2fSSadaf Ebrahimi
2301*83a54b2fSSadaf Ebrahimi<!-------------------------------------
2302*83a54b2fSSadaf Ebrahimi  INVOKED METHOD LISTENERS
2303*83a54b2fSSadaf Ebrahimi ------------------------------------>
2304*83a54b2fSSadaf Ebrahimi
2305*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="invokedmethodlistener">Listening to method invocations</a></h4>
2306*83a54b2fSSadaf Ebrahimi
2307*83a54b2fSSadaf EbrahimiThe listener <tt><a href="../javadocs/org/testng/IInvokedMethodListener.html">IInvokedMethodListener</a></tt> allows you to be notified whenever TestNG is about to invoke a test (annotated with <tt>@Test</tt>) or configuration (annotated with any of the <tt>@Before</tt> or <tt>@After</tt> annotation) method.  You need to implement the following interface:
2308*83a54b2fSSadaf Ebrahimi
2309*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2310*83a54b2fSSadaf Ebrahimipublic interface IInvokedMethodListener extends ITestNGListener {
2311*83a54b2fSSadaf Ebrahimi  void beforeInvocation(IInvokedMethod method, ITestResult testResult);
2312*83a54b2fSSadaf Ebrahimi  void afterInvocation(IInvokedMethod method, ITestResult testResult);
2313*83a54b2fSSadaf Ebrahimi}
2314*83a54b2fSSadaf Ebrahimi</pre>
2315*83a54b2fSSadaf Ebrahimi
2316*83a54b2fSSadaf Ebrahimiand declare it as a listener, as explained in <a href="#testng-listeners">the section about TestNG listeners</a>.
2317*83a54b2fSSadaf Ebrahimi
2318*83a54b2fSSadaf Ebrahimi<p>
2319*83a54b2fSSadaf Ebrahimi
2320*83a54b2fSSadaf Ebrahimi
2321*83a54b2fSSadaf Ebrahimi<!-------------------------------------
2322*83a54b2fSSadaf Ebrahimi  IHOOKABLE AND ICONFIGURABLE
2323*83a54b2fSSadaf Ebrahimi  ------------------------------------>
2324*83a54b2fSSadaf Ebrahimi
2325*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="ihookable">Overriding test methods</a></h4>
2326*83a54b2fSSadaf Ebrahimi
2327*83a54b2fSSadaf EbrahimiTestNG allows you to override and possibly skip the invocation of test methods. One example of where this is useful is if you need to your test methods with a specific security manager. You achieve this by providing a listener that implements <a href="../javadocs/org/testng/IHookable.html"><tt>IHookable</tt></a>.
2328*83a54b2fSSadaf Ebrahimi<p>
2329*83a54b2fSSadaf EbrahimiHere is an example with JAAS:
2330*83a54b2fSSadaf Ebrahimi
2331*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2332*83a54b2fSSadaf Ebrahimipublic class MyHook implements IHookable {
2333*83a54b2fSSadaf Ebrahimi  public void run(final IHookCallBack icb, ITestResult testResult) {
2334*83a54b2fSSadaf Ebrahimi    // Preferably initialized in a @Configuration method
2335*83a54b2fSSadaf Ebrahimi    mySubject = authenticateWithJAAs();
2336*83a54b2fSSadaf Ebrahimi
2337*83a54b2fSSadaf Ebrahimi    Subject.doAs(mySubject, new PrivilegedExceptionAction() {
2338*83a54b2fSSadaf Ebrahimi      public Object run() {
2339*83a54b2fSSadaf Ebrahimi        icb.callback(testResult);
2340*83a54b2fSSadaf Ebrahimi      }
2341*83a54b2fSSadaf Ebrahimi    };
2342*83a54b2fSSadaf Ebrahimi  }
2343*83a54b2fSSadaf Ebrahimi}
2344*83a54b2fSSadaf Ebrahimi</pre>
2345*83a54b2fSSadaf Ebrahimi
2346*83a54b2fSSadaf Ebrahimi<p>
2347*83a54b2fSSadaf Ebrahimi<!-------------------------------------
2348*83a54b2fSSadaf Ebrahimi  IALTERSUITELISTENER
2349*83a54b2fSSadaf Ebrahimi  ------------------------------------>
2350*83a54b2fSSadaf Ebrahimi
2351*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="ialtersuite">Altering suites (or) tests</a></h4>
2352*83a54b2fSSadaf EbrahimiSometimes you may need to just want to alter a suite (or) a test tag in a suite xml in runtime without having to
2353*83a54b2fSSadaf Ebrahimichange the contents of a suite file.
2354*83a54b2fSSadaf Ebrahimi
2355*83a54b2fSSadaf Ebrahimi<p>
2356*83a54b2fSSadaf EbrahimiA classic example for this would be to try and leverage your existing suite file and try using it for simulating a load test
2357*83a54b2fSSadaf Ebrahimion your "Application under test".
2358*83a54b2fSSadaf EbrahimiAt the minimum you would end up duplicating the contents of your &lt;test&gt; tag multiple
2359*83a54b2fSSadaf Ebrahimitimes and create a new suite xml file and work with. But this doesn't seem to scale a lot.
2360*83a54b2fSSadaf Ebrahimi
2361*83a54b2fSSadaf Ebrahimi<p>
2362*83a54b2fSSadaf EbrahimiTestNG allows you to alter a suite (or) a test tag in your suite xml file at runtime via listeners.
2363*83a54b2fSSadaf EbrahimiYou achieve this by providing a listener that implements <a href="../javadocs/org/testng/IAlterSuiteListener.html"><tt>IAlterSuiteListener</tt></a>.
2364*83a54b2fSSadaf EbrahimiPlease refer to <a href="#testng-listeners">Listeners section</a> to learn about listeners.
2365*83a54b2fSSadaf Ebrahimi<p>
2366*83a54b2fSSadaf EbrahimiHere is an example that shows how the suite name is getting altered in runtime:
2367*83a54b2fSSadaf Ebrahimi
2368*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2369*83a54b2fSSadaf Ebrahimipublic class AlterSuiteNameListener implements IAlterSuiteListener {
2370*83a54b2fSSadaf Ebrahimi
2371*83a54b2fSSadaf Ebrahimi    @Override
2372*83a54b2fSSadaf Ebrahimi    public void alter(List&lt;XmlSuite&gt; suites) {
2373*83a54b2fSSadaf Ebrahimi        XmlSuite suite = suites.get(0);
2374*83a54b2fSSadaf Ebrahimi        suite.setName(getClass().getSimpleName());
2375*83a54b2fSSadaf Ebrahimi    }
2376*83a54b2fSSadaf Ebrahimi}
2377*83a54b2fSSadaf Ebrahimi</pre>
2378*83a54b2fSSadaf Ebrahimi
2379*83a54b2fSSadaf EbrahimiThis listener can only be added with either of the following ways:
2380*83a54b2fSSadaf Ebrahimi<ul>
2381*83a54b2fSSadaf Ebrahimi  <li>Through the <tt>&lt;listeners&gt;</tt> tag in the suite xml file.</li>
2382*83a54b2fSSadaf Ebrahimi  <li>Through a <a href="#listeners-service-loader">Service Loader</a></li>
2383*83a54b2fSSadaf Ebrahimi</ul>
2384*83a54b2fSSadaf Ebrahimi
2385*83a54b2fSSadaf EbrahimiThis listener cannot be added to execution using the <tt>@Listeners</tt> annotation.
2386*83a54b2fSSadaf Ebrahimi
2387*83a54b2fSSadaf Ebrahimi<!------------------------------------
2388*83a54b2fSSadaf Ebrahimi  TEST SUCCESS
2389*83a54b2fSSadaf Ebrahimi  ------------------------------------>
2390*83a54b2fSSadaf Ebrahimi
2391*83a54b2fSSadaf Ebrahimi<h3><a class="section" indent="." name="test-results">Test results</a></h3>
2392*83a54b2fSSadaf Ebrahimi
2393*83a54b2fSSadaf Ebrahimi
2394*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="success-failure">Success, failure and assert</a></h4>
2395*83a54b2fSSadaf Ebrahimi
2396*83a54b2fSSadaf Ebrahimi
2397*83a54b2fSSadaf Ebrahimi<p>A test is considered successful if it completed without throwing any
2398*83a54b2fSSadaf Ebrahimiexception or if&nbsp; it threw an exception that was expected (see the
2399*83a54b2fSSadaf Ebrahimidocumentation for the <tt>expectedExceptions</tt> attribute found on the <tt>@Test</tt> annotation).
2400*83a54b2fSSadaf Ebrahimi</p>
2401*83a54b2fSSadaf Ebrahimi
2402*83a54b2fSSadaf Ebrahimi<p>Your test methods will typically be made of calls that can throw an
2403*83a54b2fSSadaf Ebrahimiexception, or of various assertions (using the Java &quot;assert&quot; keyword).&nbsp; An
2404*83a54b2fSSadaf Ebrahimi&quot;assert&quot; failing will trigger an AssertionErrorException, which in turn will
2405*83a54b2fSSadaf Ebrahimimark the method as failed (remember to use -ea on the JVM if you are not seeing
2406*83a54b2fSSadaf Ebrahimithe assertion errors).</p><p>Here is an example test method:</p>
2407*83a54b2fSSadaf Ebrahimi
2408*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2409*83a54b2fSSadaf Ebrahimi@Test
2410*83a54b2fSSadaf Ebrahimipublic void verifyLastName() {
2411*83a54b2fSSadaf Ebrahimi  assert "Beust".equals(m_lastName) : "Expected name Beust, for" + m_lastName;
2412*83a54b2fSSadaf Ebrahimi}
2413*83a54b2fSSadaf Ebrahimi</pre>
2414*83a54b2fSSadaf Ebrahimi
2415*83a54b2fSSadaf EbrahimiTestNG also include JUnit's Assert class, which lets you perform
2416*83a54b2fSSadaf Ebrahimiassertions on complex objects:
2417*83a54b2fSSadaf Ebrahimi
2418*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2419*83a54b2fSSadaf Ebrahimiimport static org.testng.AssertJUnit.*;
2420*83a54b2fSSadaf Ebrahimi//...
2421*83a54b2fSSadaf Ebrahimi@Test
2422*83a54b2fSSadaf Ebrahimipublic void verify() {
2423*83a54b2fSSadaf Ebrahimi  assertEquals("Beust", m_lastName);
2424*83a54b2fSSadaf Ebrahimi}
2425*83a54b2fSSadaf Ebrahimi</pre>
2426*83a54b2fSSadaf Ebrahimi<p>Note that the above code use a static import in order to be able to use the
2427*83a54b2fSSadaf Ebrahimi<tt>assertEquals</tt> method without having to prefix it by its class.
2428*83a54b2fSSadaf Ebrahimi
2429*83a54b2fSSadaf Ebrahimi<!-------------------------------------
2430*83a54b2fSSadaf Ebrahimi  LOGGING
2431*83a54b2fSSadaf Ebrahimi  ------------------------------------>
2432*83a54b2fSSadaf Ebrahimi</p>
2433*83a54b2fSSadaf Ebrahimi
2434*83a54b2fSSadaf Ebrahimi<h4><a class="section" indent=".." name="logging">Logging and results</a></h4>
2435*83a54b2fSSadaf Ebrahimi
2436*83a54b2fSSadaf EbrahimiThe results of the test run are created in a file called <tt>index.html</tt> in the
2437*83a54b2fSSadaf Ebrahimidirectory specified when launching SuiteRunner.&nbsp; This file points to
2438*83a54b2fSSadaf Ebrahimivarious other HTML and text files that contain the result of the entire test
2439*83a54b2fSSadaf Ebrahimirun.&nbsp; You can see a typical example
2440*83a54b2fSSadaf Ebrahimi<a href="http://testng.org/test-output/index.html">here</a>.
2441*83a54b2fSSadaf Ebrahimi
2442*83a54b2fSSadaf Ebrahimi<p>
2443*83a54b2fSSadaf EbrahimiIt's very easy to generate your own reports with TestNG with Listeners and Reporters:
2444*83a54b2fSSadaf Ebrahimi
2445*83a54b2fSSadaf Ebrahimi<ul>
2446*83a54b2fSSadaf Ebrahimi<li><b>Listeners</b> implement the interface <a href="../javadocs/org/testng/ITestListener.html"><tt>org.testng.ITestListener</tt></a> and are notified in real time of when a test starts, passes, fails, etc...</li><li><b>Reporters</b> implement the interface <a href="../javadocs/org/testng/IReporter.html"><tt>org.testng.IReporter</tt></a> and are notified when all the suites have been run by TestNG.  The IReporter instance receives a list of objects that describe the entire test run.</li></ul>For example, if you want to generate a PDF report of your test run, you don't need to be notified in real time of the test run so you should probably use an <tt>IReporter</tt>.  If you'd like to write a real-time reporting of your tests, such as a GUI with a progress bar or a text reporter displaying dots (".") as each test is invoked (as is explained below), <tt>ITestListener</tt> is your best choice.
2447*83a54b2fSSadaf Ebrahimi
2448*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="logging-listeners">Logging Listeners</a></h5>
2449*83a54b2fSSadaf Ebrahimi
2450*83a54b2fSSadaf EbrahimiHere is a listener that displays a "." for each passed test, a "F" for each failure and a "S" for each skip:
2451*83a54b2fSSadaf Ebrahimi
2452*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2453*83a54b2fSSadaf Ebrahimipublic class DotTestListener extends TestListenerAdapter {
2454*83a54b2fSSadaf Ebrahimi  private int m_count = 0;
2455*83a54b2fSSadaf Ebrahimi
2456*83a54b2fSSadaf Ebrahimi  @Override
2457*83a54b2fSSadaf Ebrahimi  public void onTestFailure(ITestResult tr) {
2458*83a54b2fSSadaf Ebrahimi    log("F");
2459*83a54b2fSSadaf Ebrahimi  }
2460*83a54b2fSSadaf Ebrahimi
2461*83a54b2fSSadaf Ebrahimi  @Override
2462*83a54b2fSSadaf Ebrahimi  public void onTestSkipped(ITestResult tr) {
2463*83a54b2fSSadaf Ebrahimi    log("S");
2464*83a54b2fSSadaf Ebrahimi  }
2465*83a54b2fSSadaf Ebrahimi
2466*83a54b2fSSadaf Ebrahimi  @Override
2467*83a54b2fSSadaf Ebrahimi  public void onTestSuccess(ITestResult tr) {
2468*83a54b2fSSadaf Ebrahimi    log(".");
2469*83a54b2fSSadaf Ebrahimi  }
2470*83a54b2fSSadaf Ebrahimi
2471*83a54b2fSSadaf Ebrahimi  private void log(String string) {
2472*83a54b2fSSadaf Ebrahimi    System.out.print(string);
2473*83a54b2fSSadaf Ebrahimi    if (++m_count % 40 == 0) {
2474*83a54b2fSSadaf Ebrahimi      System.out.println("");
2475*83a54b2fSSadaf Ebrahimi    }
2476*83a54b2fSSadaf Ebrahimi  }
2477*83a54b2fSSadaf Ebrahimi}
2478*83a54b2fSSadaf Ebrahimi</pre>
2479*83a54b2fSSadaf Ebrahimi
2480*83a54b2fSSadaf EbrahimiIn this example, I chose to extend <a href="../javadocs/org/testng/TestListenerAdapter.html"><tt>TestListenerAdapter</tt></a>, which implements <a href="../javadocs/org/testng/ITestListener.html"><tt>ITestListener</tt></a> with empty methods, so I don't have to override other methods from the interface that I have no interest in.  You can implement the interface directly if you prefer.
2481*83a54b2fSSadaf Ebrahimi
2482*83a54b2fSSadaf Ebrahimi<p>
2483*83a54b2fSSadaf EbrahimiHere is how I invoke TestNG to use this new listener:
2484*83a54b2fSSadaf Ebrahimi
2485*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Shell</h3>
2486*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
2487*83a54b2fSSadaf Ebrahimijava -classpath testng.jar;%CLASSPATH% org.testng.TestNG -listener org.testng.reporters.DotTestListener test\testng.xml
2488*83a54b2fSSadaf Ebrahimi</pre>
2489*83a54b2fSSadaf Ebrahimi
2490*83a54b2fSSadaf Ebrahimiand the output:
2491*83a54b2fSSadaf Ebrahimi
2492*83a54b2fSSadaf Ebrahimi<p>
2493*83a54b2fSSadaf Ebrahimi
2494*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">Shell</h3>
2495*83a54b2fSSadaf Ebrahimi<pre class="brush: text">
2496*83a54b2fSSadaf Ebrahimi........................................
2497*83a54b2fSSadaf Ebrahimi........................................
2498*83a54b2fSSadaf Ebrahimi........................................
2499*83a54b2fSSadaf Ebrahimi........................................
2500*83a54b2fSSadaf Ebrahimi........................................
2501*83a54b2fSSadaf Ebrahimi.........................
2502*83a54b2fSSadaf Ebrahimi===============================================
2503*83a54b2fSSadaf EbrahimiTestNG JDK 1.5
2504*83a54b2fSSadaf EbrahimiTotal tests run: 226, Failures: 0, Skips: 0
2505*83a54b2fSSadaf Ebrahimi===============================================
2506*83a54b2fSSadaf Ebrahimi</pre>
2507*83a54b2fSSadaf Ebrahimi
2508*83a54b2fSSadaf EbrahimiNote that when you use <tt>-listener</tt>, TestNG will automatically determine the type of listener you want to use.
2509*83a54b2fSSadaf Ebrahimi
2510*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="logging-reporters">Logging Reporters</a></h5>
2511*83a54b2fSSadaf Ebrahimi
2512*83a54b2fSSadaf EbrahimiThe <a href="../javadocs/org/testng/IReporter.html"><tt>org.testng.IReporter</tt></a> interface only has one method:
2513*83a54b2fSSadaf Ebrahimi
2514*83a54b2fSSadaf Ebrahimi<pre class="brush: java">
2515*83a54b2fSSadaf Ebrahimipublic void generateReport(List&lt;ISuite</a>&gt; suites, String outputDirectory)
2516*83a54b2fSSadaf Ebrahimi</pre>
2517*83a54b2fSSadaf Ebrahimi
2518*83a54b2fSSadaf EbrahimiThis method will be invoked by TestNG when all the suites have been run and you can inspect its parameters to access all the information on the run that was just completed.
2519*83a54b2fSSadaf Ebrahimi
2520*83a54b2fSSadaf Ebrahimi<p>
2521*83a54b2fSSadaf Ebrahimi
2522*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="logging-junitreports">JUnitReports</a></h5>
2523*83a54b2fSSadaf Ebrahimi
2524*83a54b2fSSadaf Ebrahimi<p>
2525*83a54b2fSSadaf Ebrahimi
2526*83a54b2fSSadaf Ebrahimi
2527*83a54b2fSSadaf EbrahimiTestNG contains a listener that takes the TestNG results
2528*83a54b2fSSadaf Ebrahimiand outputs an XML file that can then be fed to JUnitReport.  <a href="http://testng.org/test-report/junit-noframes.html">
2529*83a54b2fSSadaf EbrahimiHere</a> is an example, and the ant task to create this report:
2530*83a54b2fSSadaf Ebrahimi
2531*83a54b2fSSadaf Ebrahimi<h3 class="sourcetitle">build.xml</h3>
2532*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
2533*83a54b2fSSadaf Ebrahimi&lt;target name="reports"&gt;
2534*83a54b2fSSadaf Ebrahimi  &lt;junitreport todir="test-report"&gt;
2535*83a54b2fSSadaf Ebrahimi    &lt;fileset dir="test-output"&gt;
2536*83a54b2fSSadaf Ebrahimi      &lt;include name="*/*.xml"/&gt;
2537*83a54b2fSSadaf Ebrahimi    &lt;/fileset&gt;
2538*83a54b2fSSadaf Ebrahimi
2539*83a54b2fSSadaf Ebrahimi    &lt;report format="noframes"  todir="test-report"/&gt;
2540*83a54b2fSSadaf Ebrahimi  &lt;/junitreport&gt;
2541*83a54b2fSSadaf Ebrahimi&lt;/target&gt;
2542*83a54b2fSSadaf Ebrahimi</pre>
2543*83a54b2fSSadaf Ebrahimi<blockquote>
2544*83a54b2fSSadaf Ebrahimi	<em>Note:&nbsp; a current incompatibility between the JDK 1.5 and JUnitReports
2545*83a54b2fSSadaf Ebrahimiprevents the frame version from working, so you need to specify &quot;noframes&quot; to
2546*83a54b2fSSadaf Ebrahimiget this to work for now.</em>
2547*83a54b2fSSadaf Ebrahimi	</blockquote>
2548*83a54b2fSSadaf Ebrahimi
2549*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="logging-reporter-api">Reporter API</a></h5>
2550*83a54b2fSSadaf Ebrahimi
2551*83a54b2fSSadaf Ebrahimi<p>
2552*83a54b2fSSadaf EbrahimiIf you need to log messages that should appear in the generated HTML reports, you can use the class <tt><a href="../javadocs/org/testng/Reporter.html">org.testng.Reporter</a></tt>:
2553*83a54b2fSSadaf Ebrahimi
2554*83a54b2fSSadaf Ebrahimi<blockquote class="brush: text">
2555*83a54b2fSSadaf Ebrahimi<font color="#ffffff">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#000000">Reporter.log</font><font color="#000000">(</font><font color="#2a00ff">&#34;M3 WAS CALLED&#34;</font><font color="#000000">)</font><font color="#000000">;</font>
2556*83a54b2fSSadaf Ebrahimi
2557*83a54b2fSSadaf Ebrahimi</blockquote>
2558*83a54b2fSSadaf Ebrahimi
2559*83a54b2fSSadaf Ebrahimi<p align="center">
2560*83a54b2fSSadaf Ebrahimi
2561*83a54b2fSSadaf Ebrahimi<img src="pics/show-output1.png" />
2562*83a54b2fSSadaf Ebrahimi<img src="pics/show-output2.png" />
2563*83a54b2fSSadaf Ebrahimi
2564*83a54b2fSSadaf Ebrahimi</p>
2565*83a54b2fSSadaf Ebrahimi
2566*83a54b2fSSadaf Ebrahimi<h5><a class="section" indent="..." name="logging-xml-reports">XML Reports</a></h5>
2567*83a54b2fSSadaf Ebrahimi
2568*83a54b2fSSadaf Ebrahimi<p>
2569*83a54b2fSSadaf EbrahimiTestNG offers an XML reporter capturing TestNG specific information that is not available in JUnit reports. This is particulary useful when the user's test environment needs to consume XML results with TestNG-specific data that the JUnit format can't provide.  Below is a sample of the output of such a reporter:
2570*83a54b2fSSadaf Ebrahimi</p>
2571*83a54b2fSSadaf Ebrahimi
2572*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
2573*83a54b2fSSadaf Ebrahimi&lt;testng-results&gt;
2574*83a54b2fSSadaf Ebrahimi  &lt;suite name=&quot;Suite1&quot;&gt;
2575*83a54b2fSSadaf Ebrahimi    &lt;groups&gt;
2576*83a54b2fSSadaf Ebrahimi      &lt;group name=&quot;group1&quot;&gt;
2577*83a54b2fSSadaf Ebrahimi        &lt;method signature=&quot;com.test.TestOne.test2()&quot; name=&quot;test2&quot; class=&quot;com.test.TestOne&quot;/&gt;
2578*83a54b2fSSadaf Ebrahimi        &lt;method signature=&quot;com.test.TestOne.test1()&quot; name=&quot;test1&quot; class=&quot;com.test.TestOne&quot;/&gt;
2579*83a54b2fSSadaf Ebrahimi      &lt;/group&gt;
2580*83a54b2fSSadaf Ebrahimi      &lt;group name=&quot;group2&quot;&gt;
2581*83a54b2fSSadaf Ebrahimi        &lt;method signature=&quot;com.test.TestOne.test2()&quot; name=&quot;test2&quot; class=&quot;com.test.TestOne&quot;/&gt;
2582*83a54b2fSSadaf Ebrahimi      &lt;/group&gt;
2583*83a54b2fSSadaf Ebrahimi    &lt;/groups&gt;
2584*83a54b2fSSadaf Ebrahimi    &lt;test name=&quot;test1&quot;&gt;
2585*83a54b2fSSadaf Ebrahimi      &lt;class name=&quot;com.test.TestOne&quot;&gt;
2586*83a54b2fSSadaf Ebrahimi        &lt;test-method status=&quot;FAIL&quot; signature=&quot;test1()&quot; name=&quot;test1&quot; duration-ms=&quot;0&quot;
2587*83a54b2fSSadaf Ebrahimi              started-at=&quot;2007-05-28T12:14:37Z&quot; description=&quot;someDescription2&quot;
2588*83a54b2fSSadaf Ebrahimi              finished-at=&quot;2007-05-28T12:14:37Z&quot;&gt;
2589*83a54b2fSSadaf Ebrahimi          &lt;exception class=&quot;java.lang.AssertionError&quot;&gt;
2590*83a54b2fSSadaf Ebrahimi            &lt;short-stacktrace&gt;
2591*83a54b2fSSadaf Ebrahimi              &lt;![CDATA[
2592*83a54b2fSSadaf Ebrahimi                java.lang.AssertionError
2593*83a54b2fSSadaf Ebrahimi                ... Removed 22 stack frames
2594*83a54b2fSSadaf Ebrahimi              ]]&gt;
2595*83a54b2fSSadaf Ebrahimi            &lt;/short-stacktrace&gt;
2596*83a54b2fSSadaf Ebrahimi          &lt;/exception&gt;
2597*83a54b2fSSadaf Ebrahimi        &lt;/test-method&gt;
2598*83a54b2fSSadaf Ebrahimi        &lt;test-method status=&quot;PASS&quot; signature=&quot;test2()&quot; name=&quot;test2&quot; duration-ms=&quot;0&quot;
2599*83a54b2fSSadaf Ebrahimi              started-at=&quot;2007-05-28T12:14:37Z&quot; description=&quot;someDescription1&quot;
2600*83a54b2fSSadaf Ebrahimi              finished-at=&quot;2007-05-28T12:14:37Z&quot;&gt;
2601*83a54b2fSSadaf Ebrahimi        &lt;/test-method&gt;
2602*83a54b2fSSadaf Ebrahimi        &lt;test-method status=&quot;PASS&quot; signature=&quot;setUp()&quot; name=&quot;setUp&quot; is-config=&quot;true&quot; duration-ms=&quot;15&quot;
2603*83a54b2fSSadaf Ebrahimi              started-at=&quot;2007-05-28T12:14:37Z&quot; finished-at=&quot;2007-05-28T12:14:37Z&quot;&gt;
2604*83a54b2fSSadaf Ebrahimi        &lt;/test-method&gt;
2605*83a54b2fSSadaf Ebrahimi      &lt;/class&gt;
2606*83a54b2fSSadaf Ebrahimi    &lt;/test&gt;
2607*83a54b2fSSadaf Ebrahimi  &lt;/suite&gt;
2608*83a54b2fSSadaf Ebrahimi&lt;/testng-results&gt;
2609*83a54b2fSSadaf Ebrahimi</pre>
2610*83a54b2fSSadaf Ebrahimi<p>This reporter is injected along with the other default listeners so you can get this type of output by default. The listener provides some properties that can tweak the reporter to fit your needs. The following table contains a list of these properties with a short explanation:
2611*83a54b2fSSadaf Ebrahimi</p>
2612*83a54b2fSSadaf Ebrahimi<table border="1" width="100%" id="table6">
2613*83a54b2fSSadaf Ebrahimi  <tr>
2614*83a54b2fSSadaf Ebrahimi    <th>Property</th>
2615*83a54b2fSSadaf Ebrahimi    <th>Comment</th>
2616*83a54b2fSSadaf Ebrahimi    <th>Default value</th>
2617*83a54b2fSSadaf Ebrahimi  </tr>
2618*83a54b2fSSadaf Ebrahimi  <tr>
2619*83a54b2fSSadaf Ebrahimi    <td>outputDirectory</td>
2620*83a54b2fSSadaf Ebrahimi    <td>A <tt>String</tt> indicating the directory where should the XML files be outputed.</td>
2621*83a54b2fSSadaf Ebrahimi    <td>The TestNG output directory</td>
2622*83a54b2fSSadaf Ebrahimi  </tr>
2623*83a54b2fSSadaf Ebrahimi  <tr>
2624*83a54b2fSSadaf Ebrahimi    <td>timestampFormat</td>
2625*83a54b2fSSadaf Ebrahimi    <td>Specifies the format of date fields that are generated by this reporter</td>
2626*83a54b2fSSadaf Ebrahimi    <td>yyyy-MM-dd'T'HH:mm:ss'Z'</td>
2627*83a54b2fSSadaf Ebrahimi  </tr>
2628*83a54b2fSSadaf Ebrahimi  <tr>
2629*83a54b2fSSadaf Ebrahimi    <td>fileFragmentationLevel</td>
2630*83a54b2fSSadaf Ebrahimi    <td>An integer having the values 1, 2 or 3, indicating the way that the XML files are generated:
2631*83a54b2fSSadaf Ebrahimi      <br>
2632*83a54b2fSSadaf Ebrahimi<pre>
2633*83a54b2fSSadaf Ebrahimi   1 - will generate all the results in one file.
2634*83a54b2fSSadaf Ebrahimi   2 - each suite is generated in a separate XML file that is linked to the main file.
2635*83a54b2fSSadaf Ebrahimi   3 - same as 2 plus separate files for test-cases that are referenced from the suite files.
2636*83a54b2fSSadaf Ebrahimi</pre>
2637*83a54b2fSSadaf Ebrahimi    </td>
2638*83a54b2fSSadaf Ebrahimi    <td>1</td>
2639*83a54b2fSSadaf Ebrahimi  </tr>
2640*83a54b2fSSadaf Ebrahimi  <tr>
2641*83a54b2fSSadaf Ebrahimi    <td>splitClassAndPackageNames</td>
2642*83a54b2fSSadaf Ebrahimi    <td>This boolean specifies the way that class names are generated for the <tt>&lt;class&gt;</tt> element.
2643*83a54b2fSSadaf Ebrahimi      For example, you will get <tt>&lt;class class="com.test.MyTest"&gt;</tt> for false and <tt>&lt;class class="MyTest" package="com.test"&gt;</tt> for true.
2644*83a54b2fSSadaf Ebrahimi    </td>
2645*83a54b2fSSadaf Ebrahimi    <td>false</td>
2646*83a54b2fSSadaf Ebrahimi  </tr>
2647*83a54b2fSSadaf Ebrahimi  <tr>
2648*83a54b2fSSadaf Ebrahimi    <td>generateGroupsAttribute</td>
2649*83a54b2fSSadaf Ebrahimi    <td>A boolean indicating if a <tt>groups</tt> attribute should be generated for the <tt>&lt;test-method&gt;</tt> element. This feature aims at providing a
2650*83a54b2fSSadaf Ebrahimi      straight-forward method of retrieving the groups that include a test method without having to surf through the <tt>&lt;group&gt;</tt> elements.
2651*83a54b2fSSadaf Ebrahimi    </td>
2652*83a54b2fSSadaf Ebrahimi    <td>false</td>
2653*83a54b2fSSadaf Ebrahimi  </tr>
2654*83a54b2fSSadaf Ebrahimi  <tr>
2655*83a54b2fSSadaf Ebrahimi    <td>generateTestResultAttributes</td>
2656*83a54b2fSSadaf Ebrahimi    <td>
2657*83a54b2fSSadaf Ebrahimi      A boolean indicating if an <tt>&lt;attributes&gt;</tt> tag should be generated for each <tt>&lt;test-method&gt;</tt> element, containing the test result
2658*83a54b2fSSadaf Ebrahimi      attributes (See <tt>ITestResult.setAttribute()</tt> about setting test result attributes). Each attribute <tt>toString()</tt> representation will be
2659*83a54b2fSSadaf Ebrahimi      written in a <tt>&lt;attribute name="[attribute name]"&gt;</tt> tag.
2660*83a54b2fSSadaf Ebrahimi    </td>
2661*83a54b2fSSadaf Ebrahimi    <td>false</td>
2662*83a54b2fSSadaf Ebrahimi  </tr>
2663*83a54b2fSSadaf Ebrahimi  <tr>
2664*83a54b2fSSadaf Ebrahimi    <td>stackTraceOutputMethod</td>
2665*83a54b2fSSadaf Ebrahimi    <td>Specifies the type of stack trace that is to be generated for exceptions and has the following values:
2666*83a54b2fSSadaf Ebrahimi         <br>
2667*83a54b2fSSadaf Ebrahimi<pre>
2668*83a54b2fSSadaf Ebrahimi   0 - no stacktrace (just Exception class and message).
2669*83a54b2fSSadaf Ebrahimi   1 - a short version of the stack trace keeping just a few lines from the top
2670*83a54b2fSSadaf Ebrahimi   2 - the complete stacktrace with all the inner exceptions
2671*83a54b2fSSadaf Ebrahimi   3 - both short and long stacktrace
2672*83a54b2fSSadaf Ebrahimi</pre>
2673*83a54b2fSSadaf Ebrahimi    </td>
2674*83a54b2fSSadaf Ebrahimi    <td>2</td>
2675*83a54b2fSSadaf Ebrahimi  </tr>
2676*83a54b2fSSadaf Ebrahimi  <tr>
2677*83a54b2fSSadaf Ebrahimi    <td>generateDependsOnMethods</td>
2678*83a54b2fSSadaf Ebrahimi    <td>Use this attribute to enable/disable the generation of a <tt>depends-on-methods</tt> attribute for the <tt>&lt;test-method&gt;</tt> element.
2679*83a54b2fSSadaf Ebrahimi    </td>
2680*83a54b2fSSadaf Ebrahimi    <td>true</td>
2681*83a54b2fSSadaf Ebrahimi  </tr>
2682*83a54b2fSSadaf Ebrahimi  <tr>
2683*83a54b2fSSadaf Ebrahimi    <td>generateDependsOnGroups</td>
2684*83a54b2fSSadaf Ebrahimi    <td>Enable/disable the generation of a <tt>depends-on-groups</tt> attribute for the <tt>&lt;test-method&gt;</tt> element.
2685*83a54b2fSSadaf Ebrahimi    </td>
2686*83a54b2fSSadaf Ebrahimi    <td>true</td>
2687*83a54b2fSSadaf Ebrahimi  </tr>
2688*83a54b2fSSadaf Ebrahimi</table>
2689*83a54b2fSSadaf Ebrahimi<p>
2690*83a54b2fSSadaf Ebrahimi  In order to configure this reporter you can use the <tt>-reporter</tt> option in the command line or the <a href="http://testng.org/doc/ant.html">Ant</a>
2691*83a54b2fSSadaf Ebrahimi  task with the nested <tt>&lt;reporter&gt;</tt> element. For each of these you must specify the class <tt>org.testng.reporters.XMLReporter</tt>.
2692*83a54b2fSSadaf Ebrahimi  Please note that you cannot configure the built-in reporter because this one will only use default settings. If you need just the XML report with custom settings
2693*83a54b2fSSadaf Ebrahimi  you will have to add it manually with one of the two methods and disable the default listeners.
2694*83a54b2fSSadaf Ebrahimi</p>
2695*83a54b2fSSadaf Ebrahimi
2696*83a54b2fSSadaf Ebrahimi<!------------------------------------
2697*83a54b2fSSadaf Ebrahimi  YAML
2698*83a54b2fSSadaf Ebrahimi  ------------------------------------>
2699*83a54b2fSSadaf Ebrahimi
2700*83a54b2fSSadaf Ebrahimi<h3><a class="section" name="yaml">YAML</a></h3>
2701*83a54b2fSSadaf Ebrahimi
2702*83a54b2fSSadaf EbrahimiTestNG supports <a href="http://www.yaml.org/">YAML</a> as an alternate way of specifying your suite file. For example, the following XML file:
2703*83a54b2fSSadaf Ebrahimi
2704*83a54b2fSSadaf Ebrahimi<pre class="brush: xml">
2705*83a54b2fSSadaf Ebrahimi<!DOCTYPE suite SYSTEM "http://beust.com/testng/testng-1.0.dtd" >
2706*83a54b2fSSadaf Ebrahimi
2707*83a54b2fSSadaf Ebrahimi<suite name="SingleSuite" verbose="2" thread-count="4" >
2708*83a54b2fSSadaf Ebrahimi
2709*83a54b2fSSadaf Ebrahimi  &lt;parameter name="n" value="42" /&gt;
2710*83a54b2fSSadaf Ebrahimi
2711*83a54b2fSSadaf Ebrahimi  <test name="Regression2">
2712*83a54b2fSSadaf Ebrahimi    <groups>
2713*83a54b2fSSadaf Ebrahimi      <run>
2714*83a54b2fSSadaf Ebrahimi        &lt;exclude name="broken" /&gt;
2715*83a54b2fSSadaf Ebrahimi      </run>
2716*83a54b2fSSadaf Ebrahimi    </groups>
2717*83a54b2fSSadaf Ebrahimi
2718*83a54b2fSSadaf Ebrahimi    <classes>
2719*83a54b2fSSadaf Ebrahimi      &lt;class name="test.listeners.ResultEndMillisTest" /&gt;
2720*83a54b2fSSadaf Ebrahimi    </classes>
2721*83a54b2fSSadaf Ebrahimi  </test>
2722*83a54b2fSSadaf Ebrahimi</suite>
2723*83a54b2fSSadaf Ebrahimi</pre>
2724*83a54b2fSSadaf Ebrahimi<p>and here is its YAML version:</p>
2725*83a54b2fSSadaf Ebrahimi<pre class="brush: plain">
2726*83a54b2fSSadaf Ebrahiminame: SingleSuite
2727*83a54b2fSSadaf EbrahimithreadCount: 4
2728*83a54b2fSSadaf Ebrahimiparameters: { n: 42 }
2729*83a54b2fSSadaf Ebrahimi
2730*83a54b2fSSadaf Ebrahimitests:
2731*83a54b2fSSadaf Ebrahimi  - name: Regression2
2732*83a54b2fSSadaf Ebrahimi    parameters: { count: 10 }
2733*83a54b2fSSadaf Ebrahimi    excludedGroups: [ broken ]
2734*83a54b2fSSadaf Ebrahimi    classes:
2735*83a54b2fSSadaf Ebrahimi      - test.listeners.ResultEndMillisTest
2736*83a54b2fSSadaf Ebrahimi</pre>
2737*83a54b2fSSadaf Ebrahimi
2738*83a54b2fSSadaf EbrahimiHere is <a href="https://github.com/cbeust/testng/blob/master/src/test/resources/testng.xml">TestNG's own suite file</a>, and its <a href="https://github.com/cbeust/testng/blob/master/src/test/resources/testng.yaml">YAML counterpart</a>.
2739*83a54b2fSSadaf Ebrahimi
2740*83a54b2fSSadaf Ebrahimi<p>
2741*83a54b2fSSadaf Ebrahimi
2742*83a54b2fSSadaf EbrahimiYou might find the YAML file format easier to read and to maintain. YAML files are also recognized by the TestNG Eclipse plug-in. You can find more information about YAML and TestNG in this <a href="http://beust.com/weblog/2010/08/15/yaml-the-forgotten-victim-of-the-format-wars/">blog post</a>.
2743*83a54b2fSSadaf Ebrahimi
2744*83a54b2fSSadaf Ebrahimi
2745*83a54b2fSSadaf Ebrahimi<!---------------------------------------------------------------------->
2746*83a54b2fSSadaf Ebrahimi
2747*83a54b2fSSadaf Ebrahimi<a name="testng-dtd">
2748*83a54b2fSSadaf Ebrahimi&nbsp;<hr width="100%">
2749*83a54b2fSSadaf Ebrahimi<p>Back to my <a href="http://beust.com/weblog">home page</a>.</p><p>Or check out some of my other projects:</p><ul>
2750*83a54b2fSSadaf Ebrahimi	<li><a href="http://beust.com/ejbgen">EJBGen</a>:&nbsp; an EJB tag
2751*83a54b2fSSadaf Ebrahimi	generator.</li><li><a href="http://testng.org">TestNG</a>:&nbsp; A testing framework using annotations, test groups and method parameters. </li><li><a href="http://beust.com/doclipse">Doclipse</a>:&nbsp; a JavaDoc tag
2752*83a54b2fSSadaf Ebrahimi	Eclipse plug-in.</li><li><a href="http://beust.com/j15">J15</a>:&nbsp; an Eclipse plug-in to help
2753*83a54b2fSSadaf Ebrahimi	you migrate your code to the new JDK 1.5 constructs.</li><li><a href="http://beust.com/sgen">SGen</a>:&nbsp; a replacement for
2754*83a54b2fSSadaf Ebrahimi	XDoclet with an easy plug-in architecture.</li><li><a href="http://beust.com/canvas">Canvas</a>:&nbsp; a template generator
2755*83a54b2fSSadaf Ebrahimi	based on the Groovy language.</li></ul><p>
2756*83a54b2fSSadaf Ebrahimi</p>
2757*83a54b2fSSadaf Ebrahimi
2758*83a54b2fSSadaf Ebrahimi<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
2759*83a54b2fSSadaf Ebrahimi</script>
2760*83a54b2fSSadaf Ebrahimi<script type="text/javascript">
2761*83a54b2fSSadaf Ebrahimi_uacct = "UA-238215-2";
2762*83a54b2fSSadaf EbrahimiurchinTracker();
2763*83a54b2fSSadaf Ebrahimi</script>
2764*83a54b2fSSadaf Ebrahimi
2765