以下文档原文请参见：http://www.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混合，比较容易让人概念不清晰，尤其是新手 。
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想的太周到了
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文件了解完整的特性列表。
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="-Djava.compiler=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>
其余部分未翻译，请直接参看原始文档：http://www.testng.org/doc/documentation-main.html#methods
转自：http://www.bianceng.cn/Programming/project/201104/25411.htm
浙公网安备 33010602011771号