最全的TestNG官方文档中文翻译

1 - Introduction

TestNG是一个旨在简化广泛的测试需求测试框架，从单元测试（单独测试一个类）到集成测试（测试由几个类、几个包甚至几个外部框架（如应用服务器）组成的整个系统）。

编写测试通常由三个步骤组成：

• 编写测试的业务逻辑并在代码中插入TestNG注释。
• 在 testng.xml  或 build.xml 文件中添加有关测试的信息（例如类名，希望运行的组，等）。
• - Run TestNG。

你可以在欢迎页面上找到一个快速示例。

本文档中使用的概念如下：

• 一个 XML 文件表示一个套件。它可以包含一个或多个测试，并由<suite>标签定义。
• 一个<test>标签表示一个测试，它可以包含一个或多个TestNG类。
• TestNG类是至少包含一个TestNG注释的Java类。它由<class>标签表示，可以包含一个或多个测试方法。
• 测试方法是在源代码中由@Test注解的Java方法。

TestNG测试可以通过@beforexxx和@afterxxx注释进行配置，这些注释允许在某个点（点可以是上面列出的任何一项）之前和之后执行一些Java逻辑。

本手册的其余部分将解释如下：

• 所有注释的列表和简要解释。这将使您对TestNG提供的各种功能有一个了解，但您可能希望参考专门讨论这些注释的一节来了解详细信息。
• testng.xml文件的描述、语法以及可以在其中指定的内容。
• 各种特性的详细列表以及如何结合注释和 testng.xml 使用它们。

2 - Annotations

下面是 TestNG 中可用的注释及其属性的快速概述。

@BeforeSuite @AfterSuite @BeforeTest @AfterTest @BeforeGroups @AfterGroups @BeforeClass @AfterClass @BeforeMethod @AfterMethod		TestNG类的配置信息 : @BeforeSuite: 该注解标记的方法将在<suite>标签中所有的测试方法执行之前执行。 @AfterSuite: 该注解标记的方法将在<suilte>标签中所有的测试方法执行之后执行。 @BeforeTest: 该注解标记的方法将在<test>标签中所有的测试方法执行之前执行。 @AfterTest: 该注解标记的方法将在<test>标签中所有的测试方法执行之后执行。 @BeforeGroups: 该注解标记的方法将在组列表运行之前运行。这个方法保证在调用属于任何这些组的第一个测试方法之前运行。 @AfterGroups: 该注解标记的方法将在组列表运行之后运行。该方法保证在调用属于任何这些组的最后一个测试方法zhi'hou运行。 @BeforeClass: 该注解标记的方法将在调用该类的第一个测试方法之前执行。 @AfterClass: 该注解标记的方法将在该类所有的测试方法运行之后执行。 @BeforeMethod: 该注解标记的方法将在每一个测试方法执行之前运行。 @AfterMethod: 该注解标记的方法将在每一个测试方法执行之后执行。 在TestNG类的超类中注释的行为 当这些注解在 TestNG 超类上使用时，也一并会被子类继承下来。因此，在一个公共超类中集中多个测试方法的设置是很有用的。 在这种情况下，TestNG保证“@Before”方法按继承顺序执行(首先执行最高的超类，然后沿着继承链向下执行)，“@After”方法按相反的顺序执行(沿着继承链向上执行)。
	alwaysRun	对于before方法(beforeSuite, beforeTest, beforeTestClass和beforeTestMethod，但不包括beforeGroups):如果设置为true，这个配置方法将运行，无论它属于哪个组。 对于after方法(afterSuite, afterClass，…):如果设置为true，即使之前调用的一个或多个方法失败或被跳过，这个配置方法也会运行。
	dependsOnGroups	此方法所依赖的组列表。
	dependsOnMethods	此方法所依赖的方法列表
	enabled	是否启用该类/方法上的方法
	groups	该类/方法所属的组列表
	inheritGroups	如果为true，此方法将属于@Test注释中在类级别指定的组。
	onlyForGroups	只适用于@BeforeMethod和@AfterMethod。如果指定，则只有当对应的测试方法属于列出的组之一时，才会调用此setup/teardown方法。
@DataProvider		将方法标记成为测试方法提供数据的方法。带有该注解的方法，必须返回一个 Object[][]，其中每个 Object[] 都可以成为对接测试方法的参数列表。要使用该 DataProvider 返回的参数列表的测试方法，其@Test注解中 dataProvider 参数值要传入该方法的方法名或@DataProvider注解的name参数值。（带有该注解的方法，必须是静态方法）
	name	当前DataProvier方法的名称。如果不传入时，默认使用该方法的methodName。
	parallel	如果设置为true，则使用该方法提供数据的测试方法，将并行（多线程）执行。默认值为false。
@Factory		将方法标记为给 TestNG 提供Test类的工厂。该方法必须返回一个Object[]。（返回的Object 会直接被当作测试类，去执行对应的测试方法。创建测试类时，可以批量传参，给测试方法使用。 ）
@Listeners		在测试类上，定义监听器。（指定当前类使用的监听器）
	value	一个继承了 org.testng.ITestNGListener 的类的数组。
@Test		将类或方法标记为测试的一部分。
	alwaysRun	如果设置为true，在依赖的测试方法执行失败后，此测试方法也会执行。
	dataProvider	指定为改方法提供数据的dataProvider的name。
	dataProviderClass	dataProvider 方法所在类的类路径（test执行时会在此类中查找 dataProvider 指定的方法）。如果没有指定，将在当前测试方法所在类或其基类之一上查找dataProvider指定的方法。如果指定了类路径，则dataProvider指定的方法需要是 static 的。
	dependsOnGroups	此测试方法依赖的组列表。
	dependsOnMethods	此测试方法依赖的方法列表。
	description	测试方法的描述。
	enabled	是否启用该类/方法上的方法。 （ enabled=false时，会将方法禁用，即直接跳过）
	expectedExceptions	该测试方法预期抛出的异常列表。如果 没有抛出异常 或 抛出的异常与列表中的异常不同，则此测试将被标记为失败。
	groups	当前测试类/方法所属的组列表。
	invocationCount	当前测试方法执行的次数。
	invocationTimeOut	此测试方法在所有每次调用的累计时间中所花费的最大毫秒数。如果未指定invocationCount，则将忽略此属性。（每次调用时的，最大调用时长。）
	priority	此测试方法的优先级。序号小的优先执行。
	successPercentage	此测试方法预期执行成功的百分比。
	singleThreaded	如果设置为true，这个测试类上的所有方法都保证在同一个线程中运行，即使测试当前正在使用parallel="methods"运行。这个属性只能在类级别使用，如果在方法级别使用，它将被忽略。注意:此属性过去被称为sequential(现在已弃用)。
	timeOut	此测试应该执行的最大毫秒数。（超时后会报失败）
	threadPoolSize	此测试方法的线程池的大小。该测试方法将由invocationCount指定的多个线程调用。 注意:如果未指定invocationCount，此属性将被忽略

3 - testng.xml

你可以用几种不同的方式调用TestNG:

• 使用 testng.xml 调用
• 使用 ant
• 通过 command 命令行调用

本节描述 testng.xml 的格式(您将在下面找到关于ant和命令行的文档)。

可以在主网站： testng-1.0.dtd 上找到 testng.xml 的当前DTD。(为了方便起见，您可能更喜欢浏览HTML版本)。

下面是一个示例 testng.xml 文件：

<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd" >

<suite name="Suite1" verbose="1" >
   <test name="Nopackage" >
       <classes>
            <class name="NoPackageTest" />
        </classes>
   </test>
   
   <test name="Regression1">
       <classes>
           <class name="test.sample.ParameterSample"/>
           <class name="test.sample.ParameterTest"/>
       </classes>
   </test>
</suite>

你可以指定包名，而不是类名：

<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd" >

<suite name="Suite1" verbose="1" >
   <test name="Regression1"   >
       <packages>
           <package name="test.sample" />
       </packages>
   </test>
</suite>

在这个例子中，TestNG 将查看 test.sample 包中所有的类，并只保留具有TestNG注解的类。

你也可以指定要包含和排除的 组 与 方法：

<test name="Regression1">
  <groups>
   <run>
     <exclude name="brokenTests"  />
     <include name="checkinTests"  />
   </run>
 </groups>

 <classes>
   <class name="test.IndividualMethodsTest">
     <methods>
       <include name="testMethod" />
     </methods>
   </class>
 </classes>
</test>

您还可以在testng.xml中定义新的组，并在属性中指定额外的细节，例如是否并行运行测试，使用多少线程，是否运行JUnit测试，等等。

默认情况下，TestNG将按照在XML文件中找到测试的顺序运行测试。如果希望此文件中列出的类和方法以不可预测的顺序运行，请将 preserve-order 属性设置为false

<test name="Regression1" preserve-order="false">
  <classes>
    <class name="test.Test1">
     <methods>
       <include name="m1" />
       <include name="m2" />
     </methods>
   </class>
    <class name="test.Test2" />
 </classes>
</test>

请参阅DTD以获得特性的完整列表，或者继续阅读。

4 - Running TestNG

可以通过不同的方式调用TestNG：

• Command line
• ant
• Eclipse
• IntelliJ's IDEA

本节仅说明如何从命令行调用TestNG。如果您对其他方式感兴趣，请按上述其中一个链接。

假设在类路径中有TestNG，调用TestNG的最简单方法如下：

java org.testng.TestNG testng1.xml [testng2.xml testng3.xml ...]

您需要指定至少一个XML文件来描述您试图运行的TestNG套件。另外，以下命令行开关是可用的：

Command Line Parameters

Option	Argument	Documentation
-configfailurepolicy	skip | continue	如果@Before*方法失败，TestNG应该继续执行套件中剩余的测试还是跳过它们。默认行为是跳过。
-d	一个目录	生成报告的目录(默认为test-output)。
-dataproviderthreadcount	并行运行测试时用于 data providers 的默认线程数。	这将设置并行运行测试时 data providers 使用的默认最大线程数。它只有在选择了并行模式时才会生效(例如，使用-parallel选项)。这可以在套件定义中重写。
-excludegroups	以逗号分隔的组列表。	要从本次运行中排除的组列表。
-groups	以逗号分隔的组列表。	要运行的组列表(例如："windows,linux,regression").
-listener	可以在类路径中找到以逗号分隔的Java类列表。	你自己指定的监听器。这些类要实现 org.testng.ITestListener
-usedefaultlisteners	true|false	是否使用默认监听器
-methods	以逗号分隔的完全限定类名和方法列表。例如com.example.Foo.f1,com.example.Bar.f2	允许你指定要运行的单个方法。
-methodselectors	用逗号分隔的Java类和定义方法选择器的方法的优先级列表。	允许您在命令行上指定方法选择器。例如：com.example.Selector1:3,com.example.Selector2:2
-parallel	methods|tests|classes	如果指定，将设置用于确定运行测试时如何使用并行线程的默认机制。如果没有设置，默认机制是根本不使用并行线程。这可以在套件定义中重写。
-reporter	自定义报告监听器的扩展配置（继承了 report listener）	类似于-listener，不同之处在于它允许在报告实例上配置 javabeans-style 的属性。 例如: -reporter com.test.MyReporter:methodFilter=*insert*,enableFiltering=true 这个选项可以配置多次，每个需要生成的报告都可以配置一次。
-sourcedir	以逗号分隔的目录列表。	javadoc注释的测试源所在的目录。只有在使用javadoc类型注释时才需要此选项。(例如 "src/test" or "src/test/org/testng/eclipse-plugin;src/test/org/testng/testng").
-suitename	测试套的默认名称	这指定了在命令行上定义的测试套件的套件名称。如果suite.xml文件或源代码指定了不同的套件名称，则忽略此选项。如果您使用双引号“like this”将它括起来，则可以创建包含空格的套件名称。
-testclass	可以在类路径中找到的以逗号分隔的类列表。	用逗号分隔的类文件列表 (e.g. "org.foo.Test1,org.foo.test2").
-testjar	一个 jar	指定包含测试类的jar文件。如果在这个jar文件的根目录下找到一个testng.xml文件，就会使用它，否则，在这个jar文件中找到的所有测试类都将被认为是测试类。
-testname	测试的默认名称	这指定了在命令行上定义的测试的名称。如果suite.xml文件或源代码指定了不同的测试名称，则忽略此选项。如果您使用双引号“like this”将其包围起来，则可以创建一个包含空格的测试名称。
-testnames	用逗号分隔测试名称列表。	只有在<test>标签中定义的匹配这些名称之一的测试将被运行。
-testrunfactory	可以在类路径中找到的Java类。	允许你指定自己的测试运行程序。这个类需要实现 org.testng.ITestRunnerFactory.
-threadcount	并行运行测试时使用的默认线程数。	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.
-xmlpathinjar	jar文件中XML文件的路径。	这个属性应该包含测试jar中一个有效XML文件的路径(例如:“resources/ testng.xml”)。默认是“testng.xml”，这意味需要在jar文件的根目录下有一个名为“testng.xml”的文件。该option 只有在指定了 -testjar 时，才会生效

可以通过不带任何参数调用TestNG来获得该文档。

您还可以将命令行开关放在一个文本文件中，例如输入c:\command.txt，并告诉TestNG使用该文件来检索它的参数（将TestNG的命令行参数放入到txt文件中，然后用testNG检索txt文件）：

C:> more c:\command.txt
-d test-output testng.xml
C:> java org.testng.TestNG @c:\command.txt

另外，可以在Java虚拟机的命令行上传递TestNG属性

java -Dtestng.test.classpath="c:/build;c:/java/classes;" org.testng.TestNG testng.xml

以下是TestNG能够理解的属性：

System properties

Property	Type	Documentation
testng.test.classpath	以分号分隔的包含测试类的一系列目录。	如果设置了这个属性，TestNG将使用它来查找测试类，而不是类路径。如果您在XML文件中使用package标记，并且在类路径中有很多类，其中大多数不是测试类，那么这样做很方便。

例如：

java org.testng.TestNG -groups windows,linux -testclass org.test.MyTest

ant任务和TestNG.xml允许您使用更多参数启动TestNG(要包含的方法、指定参数等)，因此只有当您试图了解TestNG并希望快速启动和运行时，才应该考虑使用命令行。

重要提示：如果您还指定了testng.xml文件，则指定应该运行哪些测试的命令行标志将被忽略，但-includedgroups和-excludedgroups除外，它们将覆盖testng.xml中发现的所有组包含/排除。

5 - Test methods，Test classes and Test groups

5.1 - Test methods

用 @Test 注解的方法。被 @Test 注解的方法的返回值会被忽略，除非你在 testng.xml 文件中将 allow-return-values 设置为 true 。

<suite allow-return-values="true">
or
<test allow-return-values="true">

5.2 - Test Groups

TestNG允许您执行复杂的测试方法分组。你不仅可以声明方法属于组，还可以指定包含其他组的组。然后可以调用TestNG，并要求它包含一组特定的组(或正则表达式)，同时排除另一组。这为您在如何划分测试方面提供了最大的灵活性，并且如果您想要连续运行两组不同的测试，则不需要重新编译任何内容。

测试组在 testng.xml 文件中指定，可以在 <test> 或 <suite> 标签下找到。在<suite> 标签中指定的组，应用于其 <suite>标签下的所有的 <test> 标签。注意，组在这些标签中是累积的：如果在 <suite> 中指定组“a”，在 <test> 中指定组“b”，那么“a”和“b”都将被包含。

例如，有至少两类测试是很常见的

• Check-in 测试。在提交新代码之前，应该运行这些测试。它们通常应该是快速的，并确保没有基本的功能被破坏。
• 功能测试。这些测试应该涵盖软件的所有功能，并且至少每天运行一次，尽管理想情况下您希望连续运行它们。

通常，Check-in 测试是功能测试的一个子集。TestNG允许您以一种非常直观的方式指定测试组。例如，你可以这样构造你的测试：你的整个测试类属于“functest”组，另外一些方法属于“checkintest”组：

public class Test1 {
 @Test(groups = { "functest", "checkintest" })
 public void testMethod1() {
 }

 @Test(groups = {"functest", "checkintest"} )
 public void testMethod2() {
 }

 @Test(groups = { "functest" })
 public void testMethod3() {
 }
}

用以下调用TestNG

<test name="Test1">
 <groups>
   <run>
     <include name="functest"/>
   </run>
 </groups>
 <classes>
   <class name="example1.Test1"/>
 </classes>
</test>

将运行该类中的所有测试方法，而使用 checktest 调用它将只运行testMethod1()和testMethod2()。

下面是另一个例子，这次使用了正则表达式。假设你的一些测试方法不应该在Linux上运行，你的测试应该是这样的：

@Test
public class Test1 {
 @Test(groups = { "windows.checkintest" })
 public void testWindowsOnly() {
 }

 @Test(groups = {"linux.checkintest"} )
 public void testLinuxOnly() {
 }

 @Test(groups = { "windows.functest" )
 public void testWindowsToo() {
 }
}

你可以使用下面的testng.xml只启动Windows方法：

<test name="Test1">
 <groups>
   <run>
     <include name="windows.*"/>
   </run>
 </groups>

 <classes>
   <class name="example1.Test1"/>
 </classes>
</test>

注意:TestNG使用 regular expressions, 而不是 wildmats。 注意区别 (例如, "任何字符" 使用 ".*"匹配，-- 点 星 -- 而不是 "*")。

Method groups

你也可以排除或包含单独的方法:

<test name="Test1">
 <classes>
   <class name="example1.Test1">
     <methods>
       <include name=".*enabledTestMethod.*"/>
       <exclude name=".*brokenTestMethod.*"/>
     </methods>
    </class>
 </classes>
</test>

在不需要重新编译任何东西的情况下，禁用单个方法非常方便，但我不建议过多地使用这种技术，因为如果开始重构Java代码，它可能会破坏测试框架(在标记中使用的正则表达式可能不再与方法匹配)。

5.3 - Groups of groups

组还可以包括其他组。这些组被称为“元组”。例如，您可能想要定义一个组“all”，这个组包括“checkintest”组和“functest”组。“functest”组本身又将包含组“windows”和“linux”，而“checkintest”组又将只包含“windows”。下面是你将如何在你的配置文件中定义它：

<test name="Regression1">
 <groups>
   <define name="functest">
     <include name="windows"/>
     <include name="linux"/>
   </define>

<!-- 官网上应该是漏掉了下面这部分 -->
    <define name="checkintest">
     <include name="windows"/>
   </define>
 
   <define name="all">
     <include name="functest"/>
     <include name="checkintest"/>
   </define>
 
   <run>
     <include name="all"/>
   </run>
 </groups>

 <classes>
   <class name="test.sample.Test1"/>
 </classes>
</test>

5.4 - Exclusion groups

TestNG允许包含或排除组。

例如，测试由于最近的更改而暂时中断，而您还没有时间修复中断，这是非常常见的。4 然而，你确实希望有清晰的功能测试运行，所以你需要停用这些测试（被中断的测试），但记住它们需要重新激活。

解决这个问题的一个简单方法是创建一个名为“broken”的组，并使这些测试方法（被中断的测试）属于它（名为“broken”的组）。例如，在上面的例子中（5.2 的例子），我知道testMethod2()现在被破坏了，所以我想禁用它：

@Test(groups = {"checkintest", "broken"} )
public void testMethod2() {
}

现在需要做的就是将这一组从运行中排除：

<test name="Simple example">
 <groups>
   <run>
     <include name="checkintest"/>
     <exclude name="broken"/>
   </run>
 </groups>

 <classes>
   <class name="example1.Test1"/>
 </classes>
</test>

通过这种方式，我将得到一个干净的测试运行，同时跟踪哪些测试被破坏了，需要稍后修复。

注意:您也可以通过使用@Test和@Before/After注释上可用的“enabled”属性来禁用单个测试。

5.5 - Parial groups

你可以在类级别定义组，然后在方法级别添加组：

@Test(groups = { "checkin-test" })
public class All {
 @Test(groups = { "func-test" )
 public void method1() { ... }
 public void method2() { ... }
}

在这个类中，method2()是在类级别定义的“check -test”组的一部分，而method1()同时属于“check -test”和“func-test”两个组。

5.6 - Parameters

测试方法不必是无参数的。您可以在每个测试方法上使用任意数量的参数，并指示TestNG通过@Parameters注解传递正确的参数。

有两种方式设置这些参数：使用 testng.xml 或 通过编程方式。

5.6.1 - Parameters from testng.xml

如果你使用简单的参数值，你可以在你的testng.xml中指定它们：

@Parameters({ "first-name" })
@Test
public void testSingleString(String firstName) {
 System.out.println("Invoked testString " + firstName);
 assert "Cedric".equals(firstName);
}

在这段代码中，我们指定Java方法的 firstName 参数应该接收名为 first-name 的 XML参数 的值。这个 XML参数 在testng.xml中定义：

<suite name="My suite">
  <parameter name="first-name"  value="Cedric"/>
  <test name="Simple example">
  <-- ... -->

同样的技术也可以用于@Before/After和@Factory注释：

@Parameters({ "datasource", "jdbcDriver" })
@BeforeMethod
public void beforeTest(String ds, String driver) {
  m_dataSource = ...;                              // look up the value of datasource
  m_jdbcDriver = driver;
}

这一次，两个Java参数 ds 和 driver 将分别接收配置文件给出的 datasource 和 jdbc-driver 的值。

参数可以通过@Optional 注解声明为可选：

@Parameters("db")
@Test
public void testNonExistentParameter(@Optional("mysql") String db) { ... }

如果在testng.xml文件中没有找到名为“db”的参数，你的测试方法将收到在 @Optional 注解中指定的默认值:“mysql”。

@Parameters 注解可以放在以下位置：

• 任何已经有@Test，@Before/After或@Factory注释的方法。
• 最多一个构造函数的测试类。在这种情况下，当需要实例化测试类时，TestNG将使用 Testng.xml 中指定的值初始化参数去调用这个特定的构造函数。这个特性可以用来将类中的字段初始化为测试方法要使用的值。

        

    注意：

• XML参数按照在注释中找到它们的顺序映射到Java参数，如果数字不匹配，TestNG将发出错误。
• 参数是有作用范围的。在 testng.xml 中，您可以在<suite>标签下声明它们，也可以在<test>标签下声明它们。如果两个参数具有相同的名称，则 <test> 标签中定义的参数具有优先级。如果您需要指定一个适用于所有测试的参数，这是很方便的。

5.6.2 - Paramters with DataProviders

如果您需要传递复杂的参数，或者需要从Java中创建的参数(复杂对象、从属性文件或数据库中读取的对象等等)，在testng.xml中指定参数可能是不够的。在这种情况下，您可以使用Data Provider来提供需要测试的值。Data Provider是类上的一个方法，它返回对象的数组的数组。这个方法用&