Robot Framework - 3 - 测试库API

08- 创建测试库--发布测试库

***** 测试库文档

为了便于维护，测试库文档应该从源代码中生成。

Robot  Framework 有自己的文档工具 libdoc.py生成 API 文档。

一个关键字文档的第一行通常应该包括该关键字的简要概述。

这行内容会被 libdoc.py 当作关键字的 tool tip，也会被显示到测试日志中。

 

Robot  Framework User Guide : Library documentation tool (libdoc)

举例： python -m robot.libdoc LibraryExampleD LibraryExampleD.html

***** 对测试库进行测试

单元测试方法：Python 有很好的单元测试工具（unittest /…），非常适合用来验证测试库。

验收测试方法：使用 Robot Framework 本身来验证测试库。

BuiltIn 测试库中有很多有用的关键字可以达到这个目的。

一个特别值得注意的是 Run Keyword And Expect Error 关键字，它能够验证关键字是否如预期地报告了错误。

使用单元测试方法还是验收测试方法取决与具体情况。

***** 打包测试库

简单的库（只有一个文件），让用户拷贝到任意位置，并设置到测试库搜索路径就可以了。

较为复杂的库则应该打包，以使安装更加容易。

对于 Python 来说，打包工具就是 Python 标准库中的 distutils，或者新的 setuptools。

打包工具的好处是测试库会被自动的安装到测试库搜索路径中。

***** 不推荐的关键字

将*DEPRECATED*添加到关键字文档的开始处，该关键字就变成不推荐的（deprecated）。

当这种关键字被执行的时候，警告信息将会输出到控制台和单独的测试日志文件中。

示例： LibraryExampleD.py

# -*- coding: utf-8 -*-
###发布测试库
class LibraryExampleD():
#测试库文档
    """This is an example library with some documentation."""
    def keyword_with_short_documentation(self, argument):
        """This keyword has only a short documentation"""
        pass
    def keyword_with_longer_documentation(self):
        """First line of the documentation is here.
        Longer documentation continues here and it can contain
        multiple lines or paragraphs.
        """
        pass
#不推荐的关键字
    def example_keyword(argument):
        """*DEPRECATED* Use keyword `Other Keyword` instead.
        This keyword does something to given `argument` and returns the result.
        """

09- Robot Framework 的测试库 API

Robot Framework 有三种不同的测试库 API：

 

--- 静态API

这是最简单的方法。

采用一个 Python 的 module 或者 Class，提供一系列的关键字。

module 或 class 的方法名和关键字相匹配，关键字和方法具有同样的参数。

这些关键字可以通报异常，输出日志，返回需要的值等等。

 

--- 动态 API

作为动态API的 Class，要实现两个方法：

一个用来获取它们自己实现了的关键字的名字，另外一个用来执行这些关键字。

关键字具体实现及运行，是在运行期决定的。

这些关键字可以通报异常，输出日志，返回需要的值。

 

--- 混合API

相比静态API，作为混合API的Class ，多了一个方法用来发现实现了哪些关键字，这些关键字可以直接使用。

其他的一切都跟静态 API 一模一样。

10- 创建测试库-- 动态测试库

 动态测试库与静态之间不同：

关键字的实现，关键字参数和文档的实现，以及关键字实际执行的方式

每个动态库必须同时具有 get_keyword_names 和 run_keyword 方法,其他方法都是可选的。

***** 获取关键字的名称

get_keyword_names 方法来发现实现了什么关键字。

这个方法不需要任何参数，必须返回一个字符串的列表（在 Python 中）。

返回值中包含了测试库实现的所有关键字的名称。

动态库必须要有这个方法。如果没有，或者因为某种原因调用该方法失败，这个测试库就会被视为静态库。

***** 运行关键字

run_keyword方法来运行它们的关键字。

这个方法带有 2 个参数:

第一个参数是需要运行的关键字名称，其格式必须与 get_keyword_names 中返回的值相同

第二个参数是将要传到该关键字的参数列表

***** 获取关键字的参数

get_keyword_arguments 方法获取实际需要什么参数，并告诉 Robot Framework。

这个方法将关键字的名称作为一个参数，并返回一个包含了该关键字接受的参数的字符串列表。

动态关键字可以要求任何数量的参数，也可以带具有默认值的参数，可以接受可变数量的参数。

***** 获取关键字的文档

get_keyword_documentation方法取得关键字的文档，并放入用libdoc生成的库文档中。

这个方法带有一个参数，该参数是关键字的名称，并以字符串形式返回它的文档。

***** Remote

使用动态 API 最好的例子就是 Robot Framework 的 Remote 库

示例： LibraryExampleE.py

# -*- coding: utf-8 -*-
 
###动态测试库
 
class LibraryExampleE():
 
#获取关键字名称
    def get_keyword_names(self):
        return ['first keyword', 'second keyword']
#运行关键字
    def run_keyword(self, name, args):
        print "Running keyword '%s' with arguments %s." % (name, args)
#获取关键字的参数
    def get_keyword_arguments(self, name):
        return ['*arguments']  
#获取关键字的文档
    def get_keyword_documentation(self, name):
        return """This is an example Dynamic library with some documentation."""

11- 创建测试库-- 混合测试库

混合 API 的库，介于静态和动态 API 之间，既能直接实现一些方法，更重要的是，还能够动态的处理它们。

***** 获取关键字的名称

get_keyword_names方法来返回一个它所实现的关键字的名称列表，与动态 API 类似。

***** 运行关键字

采用反射来发现实现关键字的方法,与静态 API 类似。

***** 获取关键字的参数和文档

跟静态 API 的方式一样，取得这个方法的引用之后，它就从引用中去搜索参数和文档信息。

***** 小结

混合 API 一个很大的好处就是，它不需要特殊的方法来取得关键字的参数和文档。

真正动态的关键字在__getattr__中处理，其他的就直接在主库类中实现，这在实践中也经常用到。

 

当使用 Python 的时候，混合 API 在大多数情况下是更好的选择。

***** Telent

使用混合 API 的好例子就是 Robot Framework 自带的 Telnet 库。

示例： LibraryExampleF.py

# -*- coding: utf-8 -*-
#混合测试库
 
import LibraryExampleFlib
 
class LibraryExampleF():
    """This is an example Dynamic library with some documentation."""
#获取关键字名称
    def get_keyword_names(self):
        return ['my_keyword','external_keyword']
#运行关键字
    def my_keyword(self, arg):
        print "My Keyword called with '%s'" % arg
#__getattr__方法
    def __getattr__(self, name):
        if name == 'external_keyword':
            return LibraryExampleFlib.hello
        raise AttributeError("Non-existing attribute '%s'" % name)

LibraryExampleFlib.py
def hello():
    print "Hello, world!"
def Nothing():
    pass

12- 创建测试库-- 使用 Robot Framework 内部模块

Python 实现的测试库可以使用 Robot Framework 的内部模块。

小心使用!

Robot Framework 的API并不是都能从外部调用，而且不同版本之间的API 有些本质上的变化。

 

最安全的 API 就是实现 BuiltIn 库中关键字的那些方法。

关键字的改变要非常谨慎，一般首先就要把以前的老用法废弃掉。

最有用的方式之一就是 replace_variables，这个方法允许访问当前可用的变量。

示例： LibraryExampleG.py

# -*- coding: utf-8 -*-
 
###使用RobotFramework内部模块
 
import os.path
from robot.libraries.BuiltIn import BuiltIn
 
class LibraryExampleG():
 
    def do_something(argument):
        output = 'do_something_that_creates_a_lot_of_output(argument)'
        outputdir = BuiltIn().replace_variables('${OUTPUTDIR}')
        path = os.path.join(outputdir, 'results.txt')
        f = open(path, 'w')
        f.write(output)
        f.close()
        print '*HTML* Output written to <a href="results.txt">results.txt</a>'

13- 创建测试库-- 扩展已存在的测试库

添加新的功能给已存在的测试库，以及怎么在自己的库中使用它们。

***** 修改原始代码

直接修改其源代码的方式的问题是容易产生混乱，而且也需要额外重新打包。

***** 继承

使用继承来扩展一个已存在的库。

新的测试库与原始库的名称不相同。能够很容易地识别出正在使用一个定制库。

问题是新库将和原始库拥有同样的关键字，意味着会有冲突。另外一个问题是测试库不能共享它们的状态。

***** 直接使用其他测试库

方法是静态的，也不依赖测试库的状态的时候，可以简单地引入这个测试库，并使用它的方法。

***** 从 Robot Framework 中获取活动的测试库实例

BuiltIn 关键字 Get Library Instance，它被用来从 Robot Framework 自身中获取当前活动的库实例。

这个关键字返回的库实例，这个实例能看见当前的库状态。

***** 使用动态库或者混合库 API 的测试库

动态或者混合库 API 的测试库通常都有一套它们自己的扩展方式。

对于这些测试库，你需要从库的开发者，或者参考库文档或源代码中获取相关指南。