TestNG官方文档中文版(6)-参数

5.5 - Parameters

测试方法不要求是无参数的。你可以在每个测试方法上使用任意数量的参数，并指示testNG传递正确的参数。
有两种方式用于设置参数：使用testng.xml或者编程式。

  5.5.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的值。
参数可以通过可选注解来声明为可选：

@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.5.2 - Parameters with DataProviders

在testng.xml中指定参数，对于以下情况是不够的：
    * 不使用testng.xml
    * 需要传递复杂参数，或者参数需要从java中创建（复杂对象，从属性文件或者数据库中读取的对象）在这种情况下，你可以使用DataProvider来提供你测试需要的数值。DataProvider是类中的一个返回对象数组的数组的方法。这个方法带有@DataProvider注解：

//这个方法将提供数据给任何声明它的Data Provider名为"test1"的测试方法
@DataProvider(name = "test1")
public Object[][] createData1() {
 return new Object[][] {
   { "Cedric", new Integer(36) },
   { "Anne", new Integer(37)},
 };
}

//这个方法声明它的数据将由名为"test1"的Data Provider提供
@Test(dataProvider = "test1")
public void verifyData1(String n1, Integer n2) {
 System.out.println(n1 + " " + n2);
}

将打印
    Cedric 36
    Anne 37
@Test方法用dataProvider属性来指定它的Data Provider。这个名字必须符合同一个类中用@DataProvider(name="...")注解的方法，它们要使用同一个匹配的名字。
默认，将在当前类或者它的基类中查找data provider。如果你想将data provider放置到另一个类中，需要将这个data provider方法设置为静态方法，并在dataProviderClass属性中指定在哪个类中可以找到这个方法。

public static class StaticProvider {
  @DataProvider(name = "create")
  public static Object[][] createData() {
    return new Object[][] {
      new Object[] { new Integer(42) }
    }
  }
}

public class MyTest {
  @Test(dataProvider = "create", dataProviderClass = StaticProvider.class)
  public void test(Integer n) {
    // 
  }
}

Data Provider方法将返回下面两个类型中的一种：
The Data Provider method can return one of the following two types:
    * 对象数组的数组(Object[][]) ，外围数据的大小是测试方法将被调用的次数，而内层数组的大小和类型必须和测试方法的参数列表匹配。如同上面举例说明的。
    *<Object[]>的Iterator,和Object[][]的唯一差别在于Iterator容许延迟创建测试数据。testNG将一个接一个的调用iterator，再用iterator返回的参数调用测试方法。如果有很多参数集合需要传递给方法而又不想一开始就创建所有参数，会非常有用。

Here is an example of this feature for both JDK 1.4 and JDK5 (note that the JDK 1.4 example does not use Generics):
这里有一个同时适用于JDK 1.4和JDK5的例子（注意JDK 1.4的例子不使用注解）：

/**
 * @testng.data-provider name="test1"
 */
public Iterator createData() {
  return new MyIterator(DATA);
)

@DataProvider(name = "test1")
public Iterator createData() {
  return new MyIterator(DATA);
}

如果将测试方法的第一个参数申明为java.lang.reflect.Method，TestNG将使用这个第一个参数来传递当前测试方法。当多个测试方法使用同一个@DataProvider而需要依当前申请数据的方法而定来返回不同值时特别有用。
举例说明，下面的代码在@DataProvider中打印测试方法的名字:

@DataProvider(name = "dp")
public Object[][] createData(Method m) {
  System.out.println(m.getName());  // print test method name
  return new Object[][] { new Object[] { "Cedric" }};
}

@Test(dataProvider = "dp")
public void test1(String s) {
}

@Test(dataProvider = "dp")
public void test2(String s) {
}

将会显示:
    test1
    test2

  5.5.3 - Parameters in reports

被用于调用测试方法的参数将在TestNG生成的HTML报告中显示。实例如下：