TestNG官方文档中文新版.docx

TestNG官方文档中文版(1)-介绍
最近决定开始使用TestNG来替代junit，作为未来的单元测试基础组件。
    google了一下没有找到好的详细的文档，最后发现官网上的文档其实挺全的，决定翻译一下。
    TestNG的官方文档请见： http://testng.org/doc/documentation-main.html

1. 介绍
    TestNG是一个设计用来简化广泛的测试需求的测试框架，从单元测试（隔离测试一个类）到集成测试（测试由有多个类多个包甚至多个外部框架组成的整个系统，例如运用服务器）。

    编写一个测试的过程有三个典型步骤：

    * 编写测试的 业务逻辑并在代码中插入TestNG annotation
    * 将测试信息添加到testng.xml文件或者build.xml中
    * 运行TestNG

在欢迎页面上可以找到快速入门示例。

下面是这篇文档使用的概念：

    * suite由xml文件描述。它包含一个或多个测试并被定义为<suite>标签
    * test由<test>描述并包含一个或者多个TestNG类
    * TestNG类是包含至少一个TestNG annotation的java类，由<class>标签描述并包含一个或多个测试方法
    * 测试方法是源文件中带有@Testd注释的java方法

    TestNG测试可以被@BeforeXXX 和 @AfterXXX annotations配置，容许在特定点的前后执行一些java逻辑，这些点上面已经列出。

这份手册的剩余部分将讲述以下内容：

    * 所有的annotation列表并带有简短说明，为TestNG的多种功能性提供参考, 你可能需要参考为每个annotation提供的代码片段来学习细节。

     * testng.xml文件描述，它的语法和如果指定它。
    * 多个特性的详细列表和怎样结合annotation和testng.xml来使用它们

*******************************************************************************

注：上面的内容很简短，但是请注意其中的一些细节。

1. TestNG是一个设计用来简化广泛的测试需求的测试框架，从单元测试到集成测试
    这个是TestNG设计的出发点，不仅仅是单元测试，而且可以用于集成测试。设计目标的不同，对比junit的只适合用于单元测试，TestNG无疑走的更远。
    可以用于集成测试，这个特性是我选择TestNG的最重要的原因。

2. 测试的过程的三个典型步骤，注意和junit(4.0)相比，多了一个将测试信息添加到testng.xml文件或者build.xml
    测试信息尤其是测试数据不再写死在测试代码中，好处就是修改测试数据时不需要修改代码/编译了，从而有助于将测试人员引入单元测试/集成测试。

3. 基本概念，相比junit的TestCase/TestSuite，TestNG有suite/test/test method三个级别，即将test/test method明确区分开了。
    junit中的TestCase将test/test method混合，比较容易让人概念不清晰，尤其是新手。
TestNG官方文档中文版(2)-annotation
    TestNG的官方文档的中文翻译版第二章，原文请见 http://testng.org/doc/documentation-main.html

2 - Annotation

这里是TestNG中用到的annotation的快速预览，还有它们的属性。

@BeforeSuite:        被注释的方法将在所有测试运行前运行
@AfterSuite:        被注释的方法将在所有测试运行后运行
@BeforeTest:        被注释的方法将在测试运行前运行
@AfterTest:        被注释的方法将在测试运行后运行
@BeforeGroups:        被配置的方法将在列表中的gourp前运行。这个方法保证在第一个属于这些组的测试方法调用前立即执行。
@AfterGroups:        被配置的方法将在列表中的gourp后运行。这个方法保证在最后一个属于这些组的测试方法调用后立即执行。
@BeforeClass:        被注释的方法将在当前类的第一个测试方法调用前运行。
@AfterClass:        被注释的方法将在当前类的所有测试方法调用后运行。
@BeforeMethod:        被注释的方法将在每一个测试方法调用前运行。
@AfterMethod:        被注释的方法将在每一个测试方法调用后运行。
属性：
    alwaysRun    对于每个bufore方法(beforeSuite, beforeTest, beforeTestClass 和 beforeTestMethod, 但是不包括 beforeGroups):
                如果设置为true，被配置的方法将总是运行而不管它属于哪个组。
                对于after方法(afterSuite, afterClass, ...): 如果设置为true，被配置的方法甚至在一个或多个先调用的方法失败或被忽略时也将运行。
    dependsOnGroups        这个方法依赖的组列表
    dependsOnMethods    这个方法依赖的方法列表
    enabled            这个类的方法是否激活
    groups            这个类或方法所属的分组列表
    inheritGroups        如果设置为true，这个方法被属于在类级别被@Test annotation指定的组

@DataProvider    标记一个方法用于为测试方法提供数据。
                被注释的方法必须返回Object[][], 其中每个Object[]可以指派为这个测试方法的参数列表。
                从这个DataProvider接收数据@Test方法需要使用一个和当前注释相同名称的dataProvider名称
    name         这个DataProvider的名称

@Factory    标记方法作为一个返回对象的工厂，这些对象将被TestNG用于作为测试类。这个方法必须返回Object[]

@Parameters    描述如何传递参数给@Test方法
    value    用于填充这个方法的参数的变量列表

@Test        标记一个类或方法作为测试的一部分
    alwaysRun     如果设置为true，这个测试方法将总是运行，甚至当它依赖的方法失败时。
    dataProvider     这个测试方法的data provider的名称
    dataProviderClass     用于查找data provider的类。
                    如果不指定，将在当前测试方法所在的类或者它的基类上查找data provider。
                    如果这个属性被指定, 则data provider方法需要是指定类的static方法。
    dependsOnGroups     当前方法依赖的组列表
    dependsOnMethods     当前方法依赖的方法列表
    description     当前方法的描述
    enabled     当前类的方法/方法是否被激活
    expectedExceptions     测试方法期望抛出的异常列表。如果没有异常或者抛出的不是列表中的任何一个，当前方法都将标记为失败.
    groups     当前类/方法所属的组列表
    invocationCount     当前方法被调用的次数
    successPercentage     当前方法期望的成功率
    sequential     如果设置为true，当前测试类上的所有方法保证按照顺序运行。甚至测试们在parallel="true"的情况下.
            这个属性只能用于类级别，如果用于方法级别将被忽略。
    timeOut     当前方法容许花费的最大时间，单位毫秒。
    threadPoolSize     当前方法的线程池大小。方法将被多线程调用，次数由invocationCount参数指定
            注意：如果invocationCount没有指定则这个属性将被忽略

注：
    上面是TestNG中用到的annotation列表，从中我们可以看到TestNG提供的一些特性

1. before方法和after方法    带来了足够丰富的测试生命周期控制
2. dependsOnGroups/dependsOnMethods 提供了依赖检查机制，并可以严格控制执行顺序
3. DataProvider 使得对同一个方法的测试覆盖变的非常轻松，非常适合进行边界测试，只要给出多种测试数据就可以针对一个测试方法进行覆盖
4. expectedExceptions 使得异常测试变的非常轻松
5. invocationCount/threadPoolSize 终于可以简单的直接进行多线程测试了，这个绝对是junit的超级弱项，回想junit中那个万恶的System.exist(0)...
6. timeOut 终于不用死等然后手工强行关闭测试，TestNG想的太周到了
TestNG官方文档中文版(3)-testng.xml
    TestNG的官方文档的中文翻译版第3章，原文请见 http://testng.org/doc/documentation-main.html

    3 - testng.xml

    调用TestNG由几种不同方法：

    * 使用testng.xml文件
    * 使用ant
    * 从命令行

    这节描述testng.xml的格式（文档的后面会讲到ant和命令行）。

    当前testng.xml的DTD文件可以从官方找到：http://testng.org/testng-1.0.dtd。（为了方便使用，你可能更喜欢浏览HTML版本）。
    下面是testng.xml文件的一个例子：

<!DOCTYPE suite SYSTEM "http://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 "http://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 annotation的类。

    你同样可以指定包含或不包含的组和方法:
<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测试，等等...
    请查看DTD文件了解完整的特性列表。
TestNG官方文档中文版(4)-运行TestNG
4 - 运行TestNG

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

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

1) 命令行

假设你已经将TestNG加入到class path，调用TestNG最简单的方法事下面的：

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

必须指定最少一个描述你试图测试的TestNG suite的xml文件。另外，下面的命令行参数可以使用：

命令行参数列表

选项        参数                文档说明
-d        一个目录            生成报告的目录（ test-output）
-sourcedir    分号隔开的目录列表        带有javadoc注释的测试源文件目录. 这个选项只在使用javadoc类型的annotation时才有效.
                        (例如 "src/test" or "src/test/org/testng/eclipse-plugin;src/test/org/testng/testng").
-testclass    可以在classpath路径中找到的逗号分隔的类列表。逗号分隔的类文件列表(例如 "org.foo.Test1,org.foo.test2").
-groups        逗号分隔的组列表        要运行的组列表(例如 "windows,linux,regression").
-excludegroups    逗号分隔的组列表        不想包含在这次运行中的组列表
-testrunfactory    可以在classpath中找到的java类    指定测试的runner.这个类需要实现接口org.testng.ITestRunnerFactory .
-listener    可以在classpath路径中找到的逗号分隔的类列表。    指定测试的listener. 这个类需要实现接口org.testng.ITestListener
-parallel    methods|tests            如果指定, 设置运行测试时如何使用并发线程的默认机制.如果不设置，默认机制是完全不使用并发线程。这个设置可以被suite定义覆盖.
-threadcount    并发测试运行时默认使用的线程数    用于设置并发测试时默认的线程数. 只在并发模式被选择时才生效 (例如, 打开 -parallel 选项). 这个设置可以被suite定义覆盖.
-suitename    测试套件使用的默认名称.        指定在命令行上定义的测试套件的名称。如果suite.xml文件或源代码指定了另外一个不同的套件名称，这个选项将被忽略。可以创建带空格的套件名称，如果在名称前后加双引号如"like this".
-testname    测试使用的默认名称.        指定在命令行上定义的测试的名称。如果suite.xml文件或源代码指定了另外一个不同的测试名称，这个选项将被忽略。可以创建带空格的测试名称，如果在名称前后加双引号如"like this".
-reporter    扩展配置用于自定义报告listenner.    类似 -listener 选项, 除了容许reporter示例上由javabean形式的配置.
    例如: -reporter com.test.MyReporter:methodFilter=*insert*,enableFiltering=true

可以通过不带任何参数直接调用TestNFG来获得这个文档。

可以将命令行开关写到txt文件中，例如c:\command.txt, 然后告诉TestNG使用这个文件类找到参数:

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

另外，可以通过jvm的命令行来传递参数给TestNG，例如

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

TestNG能够理解的参数
属性             类型                     文档
testng.test.classpath     分号分隔的包含测试类的一系列目录     如果这个属性被设置，TestNG将使用它替代从class path来查找测试类. 如果你正在使用在xml文件里面的包标签并且在classpath路径中由很多类而大部分都不是测试类的时候比较方便

举例:

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

注意 ant 任务和testng.xml容许用更多的参数来启动TestNG（包含的方法，指定的参数，等等），因此可以认为命令行适用于学习TestNG并且想快速入门。

2) Ant

可以这样定义TestNG的ant任务：

<taskdef resource="testngtasks"
         classpath="testng.jar"/>

这个任务运行TestNG测试，并且通常是在单独的jvm中。接受下面的属性：

属性名            描述                是否必须
annotations         字符串"JDK"或者"Javadoc". 定义测试适用的注释类型.如果使用"Javadoc", 则需要同时指定"sourcedir".     不是必须. 如果适用jkd5则默认为"JDK"，如果适用jdk1.4则默认为"Javadoc"
classfilesetref     要运行的测试类的FileSet结构的引用.      
classpath         要运行的测试的PATH-like 结构.      
classpathref         要运行的测试的PATH-like 结构的引用.      
dumpCommand         打印TestNG启动命令.     不是必须,默认false
enableAssert         开启JDK 1.4的断言.     不是必须,默认true
failureProperty     失败发生时要设置的属性的名称. 只有haltonfailure没有设置时才有效.     不是必须.
haltonfailure         如果测试运行期间发生失败，停止构造过程.     不是必须,默认false
haltonskipped         如果发生至少一次测试跳过，停止构造过程.        不是必须,默认false
groups             要运行的组列表，空格或逗号分隔   
excludedgroups         排除在外的组列表，空格或逗号分隔
jvm             使用的jvm，将被Runtime.exec()运行     java
listeners         逗号或空格分隔的全路径类列表，需要实现org.testng.ITestListener或org.testng.IReporter     不是必须
outputdir         报告输出目录             不是必须,默认输出到test-output.
skippedProperty     当发生测试被跳过时设置的property的名称.只有当haltonskipped没有设置时才使用     不是必须
sourcedir         用于jdk1.4测试的PATH-like结构(使用JavaDoc形式的annotations)      
sourcedirref         用于jdk1.4测试的PATH-like结构的引用(使用JavaDoc形式的annotations)           
suiteRunnerClass     TestNG启动器的全路径名称    不是必须.  默认使用org.testng.TestNG
parallel         运行测试时使用的并行模式 - methods或者tests     不是必须 - 如果没有指定，并行模式不被选择
threadCount         运行时使用的线程数量。如果并行模式被同时指定否则忽略。     默认1
testJar         包含测试和套件定义的jar包路径
timeOut         所有测试必须运行完成的最大超时时间，单位毫秒
useDefaultListeners     是否使用默认监听器和报告器.     默认true.
workingDir         运行TestNG前ant任务应该转移到的目录。
xmlfilesetref        用于要测试的套件定义的FileSet结构的引用      
suitename         设置测试套件的默认名称如果在suite的xml文件或者源代码中都没有被定义。    不是必须，默认设置为"Ant suite"
testname        设置测试的默认名称如果在suite的xml文件或者源代码中都没有被定义。    不是必须，默认设置为"Ant test"

属性classpath, classpathref或者内嵌的<classpath>必须设置一个，用于提供测试的classpath

属性xmlfilesetref, classfilesetref 或者内嵌的 <xmlfileset>, 分别的<classfileset>必须使用用来提供测试

注意：如果使用jdk1.4，属性attributes sourcedir, sourcedirref 或者内嵌的 <sourcedir> 必须提供.

注意：使用<classfileset> 并不自动按添加测试类到classpath: 需要报告这些在classpath中的任务要工作的类

内嵌元素
classpath
 <testng> 任务支持一个内嵌的<classpath> 元素来提供PATH-like的结构.

bootclasspath
bootstrap类文件的位置可以用这个PATH形式的结构指定-如果fork没有设置则被忽略

xmlfileset
套餐定义（testng.xml）可以通过一个FiltSet结构传递给任务

classfileset
TestNG可以直接在类上运行，同样支持FiltSet结构

sourcedir
PATH形式的结构，用于jdk1.4的测试，使用javadoc annotation

jvmarg
通过内嵌的<jvmarg>元素将额外的参数传递给新的虚拟机，例如：

<testng>
   <jvmarg value="-Dpiler=NONE" />
   <!-- ... -->
</testng>

sysproperty
使用内嵌的<sysproperty>元素来指定类需要的系统属性。在测试的执行期间虚拟机可以获取这些属性。 这个元素的属性和环境变量相同。

<testng>
   <sysproperty key="basedir" value="${basedir}"/>
   <!-- ... -->
</testng>
将运行测试并且使得测试可以访问basedir属性

reporter

内部的<reporter>元素是一个可选的方式，用于注入自定义的报告监听器，容许用户为调整运行时的报告期行为而
这个元素强制要求设置classname属性，指示自定义监听器的类。为了设置报告期属性，<reporter>元素可以包含多个内嵌的<property>元素来提供name和value属性，如下所示：

<testng ...>
   ...
   <reporter classname="com.test.MyReporter">
      <property name="methodFilter" value="*insert*"/>
      <property name="enableFiltering" value="true"/>
   </reporter>
   ...
</testng>

public class MyReporter {

  public String getMethodFilter() {...}
  public void setMethodFilter(String methodFilter) {...}
  public boolean isEnableFiltering() {...}
  public void setEnableFiltering(boolean enableFiltering) {...}
  ...
}
请注意这里仅仅支持有限的属性类型：String, int, boolean, byte, char, double, float, long, short.

env
可以通过内嵌的 <env>元素给TestNG的单独的虚拟机传递指定的环境变量。
要查阅<env> 元素属性的详细描述，请查看ant的exec任务的描述。

举例：
Suite xml

<testng classpathref="run.cp"
        outputDir="${testng.report.dir}"
        sourcedir="${test.src.dir}"
        haltOnfailure="true">

   <xmlfileset dir="${test14.dir}" includes="testng.xml"/>
</testng>

Class FileSet

<testng classpathref="run.cp"
        outputDir="${testng.report.dir}"
        haltOnFailure="true"M verbose="2">
    <classfileset dir="${test.build.dir}" includes="**/*.class" />
</testng>
TestNG官方文档中文版(5)-测试方法/类和组
5 - Test methods, Test classes and Test groups
5.1 - Test groups

TestNG容许执行复杂的测试方法分组。不仅可以申明方法属于组，而且可以指定分组包含其他分组。
然后TestNG可以被调用，并被要求包含某些分组和排除其他的分组。
这将提供怎样划分测试的最大弹性，并且如果想运行两个不同的测试装置不需要重新编译。

例如，非常普遍的需要至少两个种类的测试

    * Check-in tests.  这些测试将在提交新代码之前运行. 它们典型的被要求快速而且仅仅确认没有基础功能被破坏。
    * Functional tests.  这些测试将覆盖所有的软件功能，并且必须运行至少1天，尽管理想的是连续运行.

代表性的，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>
将运行在类中的所有测试方法，如果使用checkintest调用则将只运行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使用正则表达，而不是wildmats。注意这个差别。

Method groups
同样可以包含或排除个别方法：

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

这在需要使莫个单独的方法失效而不想重新编译时非常方便，但是不建议太多的使用这个机制，因为这将可能破坏你的测试框架 如果你开始重构你的java代码（标签中使用的正则表达式可能不再匹配你的方法）
5.2 - Groups of groups

"functest" itself will contain the groups "windows" and "linux" while "checkintest will only contain "windows".  Here is how you would define this in your property file:
组可以包含其他组。这些组被称为"MetaGroups"。例如，你可能想定义一个"all"组，包括"checkintest" 和"functest"。"functest"自身将包含组 "windows" 和 "linux"，而"checkintest"将包含"windows".

<test name="Regression1">
  <groups>
    <define name="functest">
      <include name="windows"/>
      <include name="linux"/>
    </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.3 - Exclusion groups

TestNG