TestNG官方文檔中文版.doc

精品文檔TestNG官方文檔中文版(1)-介紹 最近決定開始使用TestNG來替代junit，作為未來的單元測試基礎組件。 google了一下沒有找到好的詳細的文檔，最后發(fā)現(xiàn)官網(wǎng)上的文檔其實挺全的，決定翻譯一下。 TestNG的官方文檔請見： /doc/documentation-main.html1. 介紹 TestNG是一個設計用來簡化廣泛的測試需求的測試框架，從單元測試（隔離測試一個類）到集成測試（測試由有多個類多個包甚至多個外部框架組成的整個系統(tǒng)，例如運用服務器）。 編寫一個測試的過程有三個典型步驟： * 編寫測試的 業(yè)務邏輯并在代碼中插入TestNG annotation * 將測試信息添加到testng.xml文件或者build.xml中 * 運行TestNG在歡迎頁面上可以找到快速入門示例。下面是這篇文檔使用的概念： * suite由xml文件描述。它包含一個或多個測試并被定義為標簽 * test由描述并包含一個或者多個TestNG類 * TestNG類是包含至少一個TestNG annotation的java類，由標簽描述并包含一個或多個測試方法 * 測試方法是源文件中帶有Testd注釋的java方法 TestNG測試可以被BeforeXXX 和 AfterXXX annotations配置，容許在特定點的前后執(zhí)行一些java邏輯，這些點上面已經列出。這份手冊的剩余部分將講述以下內容： * 所有的annotation列表并帶有簡短說明，為TestNG的多種功能性提供參考, 你可能需要參考為每個annotation提供的代碼片段來學習細節(jié)。 * testng.xml文件描述，它的語法和如果指定它。 * 多個特性的詳細列表和怎樣結合annotation和testng.xml來使用它們*注：上面的內容很簡短，但是請注意其中的一些細節(jié)。1. TestNG是一個設計用來簡化廣泛的測試需求的測試框架，從單元測試到集成測試 這個是TestNG設計的出發(fā)點，不僅僅是單元測試，而且可以用于集成測試。設計目標的不同，對比junit的只適合用于單元測試，TestNG無疑走的更遠。 可以用于集成測試，這個特性是我選擇TestNG的最重要的原因。2. 測試的過程的三個典型步驟，注意和junit(4.0)相比，多了一個將測試信息添加到testng.xml文件或者build.xml 測試信息尤其是測試數(shù)據(jù)不再寫死在測試代碼中，好處就是修改測試數(shù)據(jù)時不需要修改代碼/編譯了，從而有助于將測試人員引入單元測試/集成測試。3. 基本概念，相比junit的TestCase/TestSuite，TestNG有suite/test/test method三個級別，即將test/test method明確區(qū)分開了。 junit中的TestCase將test/test method混合，比較容易讓人概念不清晰，尤其是新手。TestNG官方文檔中文版(2)-annotation TestNG的官方文檔的中文翻譯版第二章，原文請見 /doc/documentation-main.html2 - Annotation這里是TestNG中用到的annotation的快速預覽，還有它們的屬性。BeforeSuite: 被注釋的方法將在所有測試運行前運行AfterSuite: 被注釋的方法將在所有測試運行后運行BeforeTest: 被注釋的方法將在測試運行前運行AfterTest: 被注釋的方法將在測試運行后運行BeforeGroups: 被配置的方法將在列表中的gourp前運行。這個方法保證在第一個屬于這些組的測試方法調用前立即執(zhí)行。AfterGroups: 被配置的方法將在列表中的gourp后運行。這個方法保證在最后一個屬于這些組的測試方法調用后立即執(zhí)行。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 標記一個方法用于為測試方法提供數(shù)據(jù)。 被注釋的方法必須返回Object, 其中每個Object可以指派為這個測試方法的參數(shù)列表。 從這個DataProvider接收數(shù)據(jù)Test方法需要使用一個和當前注釋相同名稱的dataProvider名稱 name 這個DataProvider的名稱Factory 標記方法作為一個返回對象的工廠，這些對象將被TestNG用于作為測試類。這個方法必須返回ObjectParameters 描述如何傳遞參數(shù)給Test方法 value 用于填充這個方法的參數(shù)的變量列表Test 標記一個類或方法作為測試的一部分 alwaysRun 如果設置為true，這個測試方法將總是運行，甚至當它依賴的方法失敗時。 dataProvider 這個測試方法的data provider的名稱 dataProviderClass 用于查找data provider的類。 如果不指定，將在當前測試方法所在的類或者它的基類上查找data provider。 如果這個屬性被指定, 則data provider方法需要是指定類的static方法。 dependsOnGroups 當前方法依賴的組列表 dependsOnMethods 當前方法依賴的方法列表 description 當前方法的描述 enabled 當前類的方法/方法是否被激活 expectedExceptions 測試方法期望拋出的異常列表。如果沒有異?；蛘邟伋龅牟皇橇斜碇械娜魏我粋€，當前方法都將標記為失敗. groups 當前類/方法所屬的組列表 invocationCount 當前方法被調用的次數(shù) successPercentage 當前方法期望的成功率 sequential 如果設置為true，當前測試類上的所有方法保證按照順序運行。甚至測試們在parallel=true的情況下. 這個屬性只能用于類級別，如果用于方法級別將被忽略。 timeOut 當前方法容許花費的最大時間，單位毫秒。 threadPoolSize 當前方法的線程池大小。方法將被多線程調用，次數(shù)由invocationCount參數(shù)指定 注意：如果invocationCount沒有指定則這個屬性將被忽略注： 上面是TestNG中用到的annotation列表，從中我們可以看到TestNG提供的一些特性1. before方法和after方法 帶來了足夠豐富的測試生命周期控制2. dependsOnGroups/dependsOnMethods 提供了依賴檢查機制，并可以嚴格控制執(zhí)行順序3. DataProvider 使得對同一個方法的測試覆蓋變的非常輕松，非常適合進行邊界測試，只要給出多種測試數(shù)據(jù)就可以針對一個測試方法進行覆蓋4. expectedExceptions 使得異常測試變的非常輕松5. invocationCount/threadPoolSize 終于可以簡單的直接進行多線程測試了，這個絕對是junit的超級弱項，回想junit中那個萬惡的System.exist(0).6. timeOut 終于不用死等然后手工強行關閉測試，TestNG想的太周到了TestNG官方文檔中文版(3)-testng.xml TestNG的官方文檔的中文翻譯版第3章，原文請見 /doc/documentation-main.html 3 - testng.xml 調用TestNG由幾種不同方法： * 使用testng.xml文件 * 使用ant * 從命令行 這節(jié)描述testng.xml的格式（文檔的后面會講到ant和命令行）。 當前testng.xml的DTD文件可以從官方找到：/testng-1.0.dtd。（為了方便使用，你可能更喜歡瀏覽HTML版本）。 下面是testng.xml文件的一個例子： 你可以指定包名替代類名： 在這個例子中，TestNG將在包test.sample中查找所有的類，并只保留帶有TestNG annotation的類。 你同樣可以指定包含或不包含的組和方法: 你同樣可以在testng.xml中定義新的組，指定屬性的額外詳細情況，比如是否并行運行測試，使用多少線程，是否運行junit測試，等等. 請查看DTD文件了解完整的特性列表。TestNG官方文檔中文版(4)-運行TestNG 4 - 運行TestNGTestNG可以以不同的方式調用： * Command line * ant * Eclipse * IntelliJs IDEA1) 命令行假設你已經將TestNG加入到class path，調用TestNG最簡單的方法事下面的：java org.testng.TestNG testng1.xml testng2.xml testng3.xml .必須指定最少一個描述你試圖測試的TestNG suite的xml文件。另外，下面的命令行參數(shù)可以使用：命令行參數(shù)列表選項 參數(shù) 文檔說明-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.這個類需要實現(xiàn)接口org.testng.ITestRunnerFactory .-listener 可以在classpath路徑中找到的逗號分隔的類列表。 指定測試的listener. 這個類需要實現(xiàn)接口org.testng.ITestListener-parallel methods|tests 如果指定, 設置運行測試時如何使用并發(fā)線程的默認機制.如果不設置，默認機制是完全不使用并發(fā)線程。這個設置可以被suite定義覆蓋.-threadcount 并發(fā)測試運行時默認使用的線程數(shù) 用于設置并發(fā)測試時默認的線程數(shù). 只在并發(fā)模式被選擇時才生效 (例如, 打開 -parallel 選項). 這個設置可以被suite定義覆蓋.-suitename 測試套件使用的默認名稱. 指定在命令行上定義的測試套件的名稱。如果suite.xml文件或源代碼指定了另外一個不同的套件名稱，這個選項將被忽略?？梢詣?chuàng)建帶空格的套件名稱，如果在名稱前后加雙引號如like this.-testname 測試使用的默認名稱. 指定在命令行上定義的測試的名稱。如果suite.xml文件或源代碼指定了另外一個不同的測試名稱，這個選項將被忽略。可以創(chuàng)建帶空格的測試名稱，如果在名稱前后加雙引號如like this.-reporter 擴展配置用于自定義報告listenner. 類似 -listener 選項, 除了容許reporter示例上由javabean形式的配置. 例如: -reporter com.test.MyReporter:methodFilter=*insert*,enableFiltering=true可以通過不帶任何參數(shù)直接調用TestNFG來獲得這個文檔?？梢詫⒚钚虚_關寫到txt文件中，例如c:command.txt, 然后告訴TestNG使用這個文件類找到參數(shù): C: more c:command.txt -d test-output testng.xml C: java org.testng.TestNG c:command.txt另外，可以通過jvm的命令行來傳遞參數(shù)給TestNG，例如java -Dtestng.test.classpath=c:/build;c:/java/classes; org.testng.TestNG testng.xmlTestNG能夠理解的參數(shù)屬性 類型 文檔testng.test.classpath 分號分隔的包含測試類的一系列目錄 如果這個屬性被設置，TestNG將使用它替代從class path來查找測試類. 如果你正在使用在xml文件里面的包標簽并且在classpath路徑中由很多類而大部分都不是測試類的時候比較方便舉例:java org.testng.TestNG -groups windows,linux -testclass org.test.MyTest注意 ant 任務和testng.xml容許用更多的參數(shù)來啟動TestNG（包含的方法，指定的參數(shù)，等等），因此可以認為命令行適用于學習TestNG并且想快速入門。2) Ant 可以這樣定義TestNG的ant任務：這個任務運行TestNG測試，并且通常是在單獨的jvm中。接受下面的屬性：屬性名 描述 是否必須annotations 字符串JDK或者Javadoc. 定義測試適用的注釋類型.如果使用Javadoc, 則需要同時指定sourcedir. 不是必須. 如果適用jkd5則默認為JDK，如果適用jdk1.4則默認為Javadocclassfilesetref 要運行的測試類的FileSet結構的引用. classpath 要運行的測試的PATH-like 結構. classpathref 要運行的測試的PATH-like 結構的引用. dumpCommand 打印TestNG啟動命令. 不是必須,默認falseenableAssert 開啟JDK 1.4的斷言. 不是必須,默認truefailureProperty 失敗發(fā)生時要設置的屬性的名稱. 只有haltonfailure沒有設置時才有效. 不是必須.haltonfailure 如果測試運行期間發(fā)生失敗，停止構造過程. 不是必須,默認falsehaltonskipped 如果發(fā)生至少一次測試跳過，停止構造過程. 不是必須,默認falsegroups 要運行的組列表，空格或逗號分隔 excludedgroups 排除在外的組列表，空格或逗號分隔jvm 使用的jvm，將被Runtime.exec()運行 javalisteners 逗號或空格分隔的全路徑類列表，需要實現(xiàn)org.testng.ITestListener或org.testng.IReporter 不是必須outputdir 報告輸出目錄 不是必須,默認輸出到test-output.skippedProperty 當發(fā)生測試被跳過時設置的property的名稱.只有當haltonskipped沒有設置時才使用 不是必須sourcedir 用于jdk1.4測試的PATH-like結構(使用JavaDoc形式的annotations) sourcedirref 用于jdk1.4測試的PATH-like結構的引用(使用JavaDoc形式的annotations) suiteRunnerClass TestNG啟動器的全路徑名稱 不是必須. 默認使用org.testng.TestNGparallel 運行測試時使用的并行模式 - methods或者tests 不是必須 - 如果沒有指定，并行模式不被選擇threadCount 運行時使用的線程數(shù)量。如果并行模式被同時指定否則忽略。 默認1testJar 包含測試和套件定義的jar包路徑timeOut 所有測試必須運行完成的最大超時時間，單位毫秒 useDefaultListeners 是否使用默認監(jiān)聽器和報告器. 默認true.workingDir 運行TestNG前ant任務應該轉移到的目錄。xmlfilesetref 用于要測試的套件定義的FileSet結構的引用 suitename 設置測試套件的默認名稱如果在suite的xml文件或者源代碼中都沒有被定義。 不是必須，默認設置為Ant suitetestname 設置測試的默認名稱如果在suite的xml文件或者源代碼中都沒有被定義。 不是必須，默認設置為Ant test屬性classpath, classpathref或者內嵌的必須設置一個，用于提供測試的classpath屬性xmlfilesetref, classfilesetref 或者內嵌的 , 分別的必須使用用來提供測試注意：如果使用jdk1.4，屬性attributes sourcedir, sourcedirref 或者內嵌的 必須提供.注意：使用 并不自動按添加測試類到classpath: 需要報告這些在classpath中的任務要工作的類內嵌元素classpath 任務支持一個內嵌的 元素來提供PATH-like的結構.bootclasspathbootstrap類文件的位置可以用這個PATH形式的結構指定-如果fork沒有設置則被忽略xmlfileset套餐定義（testng.xml）可以通過一個FiltSet結構傳遞給任務classfilesetTestNG可以直接在類上運行，同樣支持FiltSet結構sourcedirPATH形式的結構，用于jdk1.4的測試，使用javadoc annotationjvmarg通過內嵌的元素將額外的參數(shù)傳遞給新的虛擬機，例如： sysproperty使用內嵌的元素來指定類需要的系統(tǒng)屬性。在測試的執(zhí)行期間虛擬機可以獲取這些屬性。 這個元素的屬性和環(huán)境變量相同。 將運行測試并且使得測試可以訪問basedir屬性reporter內部的元素是一個可選的方式，用于注入自定義的報告監(jiān)聽器，容許用戶為調整運行時的報告期行為而這個元素強制要求設置classname屬性，指示自定義監(jiān)聽器的類。為了設置報告期屬性，元素可以包含多個內嵌的元素來提供name和value屬性，如下所示： . .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可以通過內嵌的 元素給TestNG的單獨的虛擬機傳遞指定的環(huán)境變量。要查閱 元素屬性的詳細描述，請查看ant的exec任務的描述。舉例：Suite xml Class FileSet TestNG官方文檔中文版(5)-測試方法/類和組 5 - Test methods, Test classes and Test groups5.1 - Test groupsTestNG容許執(zhí)行復雜的測試方法分組。不僅可以申明方法屬于組，而且可以指定分組包含其他分組。然后TestNG可以被調用，并被要求包含某些分組和排除其他的分組。這將提供怎樣劃分測試的最大彈性，并且如果想運行兩個不同的測試裝置不需要重新編譯。例如，非常普遍的需要至少兩個種類的測試 * Check-in tests. 這些測試將在提交新代碼之前運行. 它們典型的被要求快速而且僅僅確認沒有基礎功能被破壞。 * Functional tests. 這些測試將覆蓋所有的軟件功能，并且必須運行至少1天，盡管理想的是連續(xù)運行.代表性的，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，使用 將運行在類中的所有測試方法，如果使用checkintest調用則將只運行testMethod1()和testMethod2().這里由其他例子，這次使用正則表達式。假設某些測試方法可能無法在Linux上運行，測試將是類似如此：Testpublic 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方法： 注意：TestNG使用正則表達，而不是wildmats。注意這個差別。Method groups同樣可以包含或排除個別方法： 這在需要使莫個單獨的方法失效而不想重新編譯時非常方便，但是不建議太多的使用這個機制，因為這將可能破壞你的測試框架 如果你開始重構你的java代碼（標簽中使用的正則表達式可能不再匹配你的方法）5.2 - Groups of groupsfunctest 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. 5.3 - Exclusion groupsTestNG 容許包含組也容許排除組.例如，當由因為最近的修改而臨時破壞的測試而又沒有時間去修復它們時非常有用。無論如何，你想要干凈的運行功能性測試，因此你想要是這些測試失效，但是記住它們重新被激活。一個簡單的解決這個問題的方法是創(chuàng)建一個稱為broken的組并讓這些測試方法歸屬它。例如，在上面的例子中，我知道testMethod2() 現(xiàn)在被破壞了，所有我想關閉它：Test(groups = checkintest, broken )public void testMethod2() 現(xiàn)在我所想要做的只是在運行中排除這個組： 用這種方法，我將得到一個干凈的測試運行，同時記錄了那些被破壞并想要后續(xù)修復的測試。注意：你也可以通過使用在Test and Before/After annotations上的enabled屬性在個體的層面上關閉測試，5.4 - Partial groups你可以在類的級別上定義組，然后在方法的層次上添加組：Test(groups = checkin-test )public class All Test(groups = func-test ) public void method1() . public void method2() . 在這個類中，method2() 屬于組checkin-test，在類的級別定義。而method1() 同時屬于 checkin-test 和 func-test.TestNG官方文檔中文版(6)-參數(shù) 5.5 - Parameters測試方法不要求是無參數(shù)的。你可以在每個測試方法上使用任意數(shù)量的參數(shù)，并指示testNG傳遞正確的參數(shù)。有兩種方式用于設置參數(shù)：使用testng.xml或者編程式。 5.5.1 - Parameters from testng.xml如果你要為你的參數(shù)使用簡單值，你可以在你的testng.xml中明確指定：Parameters(first-name)TestpublicvoidtestSingleString(StringfirstName)System.out.println(InvokedtestString+firstName);assertCedric.equals(firstName);在這個代碼中，我們明確指定java方法的參數(shù)“firstName”應該接收名為“first-name”xml參數(shù)的值。 這個xml參數(shù)在testng.xml中定義：同樣的方法可以用于注解Before/After和Factory:Parameters(datasource,jdbcDriver)BeforeMethodpublicvoidbeforeTest(Stringds,Stringdriver)m_dataSource=;/lookupthevalueofdatasourcem_jdbcDriver=driver;這次，兩個java參數(shù)ds和driver將分別接收被設置給屬性datasource和jdbc-driver的值。參數(shù)可以通過可選注解來聲明為可選：Parameters(db)TestpublicvoidtestNonExistentParameter(Optional(mysql)Stringdb)如果在testng.xml文件中沒有找到名為db的參數(shù)，測試方法將接受在Optional注解中指定的默認值：mysqlParameters 注解可以在下面位置使用： * 在任何有Test, Before/After或者Factory注解的方法上 * 在測試類的最多一個構造函數(shù)上。這種情況下，當TestNG需要實例化測試類時，他將調用這個特別的帶有初始化為testng.xml中指定的值的參數(shù)的構造函數(shù)。這個特性可以被用于初始化類內部的值域為將用于測試方法的值。 注意: * xml參數(shù)被以在注解中出現(xiàn)的相同順序映射到java參數(shù)，如果參數(shù)數(shù)量不匹配testNG將發(fā)生錯誤。 * 參數(shù)是有范圍的。在testng.xml中，你可以在標簽或者標簽下聲明參數(shù)。如果兩個參數(shù)同名，在標簽下定義的參數(shù)優(yōu)先。非常適用于這樣的場合：需要指定一個應用于所有測試的參數(shù)，但是又希望在特定測試用覆蓋它的值。 5.5.2 - Parameters with DataProviders在testng.xml中指定參數(shù)，對于以下情況是不夠的： * 不使用testng.xml * 需要傳遞復雜參數(shù)，或者參數(shù)需要從java中創(chuàng)建（復雜對象，從屬性文件或者數(shù)據(jù)庫中讀取的對象）在這種情況下，你可以使用Data Provider來提供你測試需要的數(shù)值。Data Provider是類中的一個返回對象數(shù)組的數(shù)組的方法。這個方法帶有DataProvider注解：/這個方法將提供數(shù)據(jù)給任何聲明它的DataProvider名為test1的測試方法DataProvider(name=test1)publicObjectcreateData1()returnnewObjectCedric,newInteger(36),Anne,newInteger(37),;/這個方法聲明它的數(shù)據(jù)將由名為test1的DataProvider提供Test(dataProvider=test1)publicvoidverifyData1(Stringn1,Integern2)System.out.println(n1+n2); 將打印 Cedric 36 Anne 37 Test方法用dataProvider屬性來指定它的Data Provider。這個名字必須符合同一個類中用DataProvider(name=.)注解的方法，它們要使用同一個匹配的名字。默認，將在當前類或者它的基類中查找data provider。如果你想將data provider放置到另一個類中，