测试库的分发

测试库的文档

一个测试库如果没有提供文档来说明其中包含了哪些关键字, 以及这些关键字的用途的话, 那么不如说这个测试库是没用的(useless).

为了容易维护, 强烈建议把测试库的文档内容直接写在源代码里, 并从中生成文档. 基本上, 这意味着在Python中要使用 docstrings, 在Java中使用 Javadoc. 如下例所示:

  1. class MyLibrary:
  2.     """This is an example library with some documentation."""
  3.  
  4.     def keyword_with_short_documentation(self, argument):
  5.         """This keyword has only a short documentation"""
  6.         pass
  7.  
  8.     def keyword_with_longer_documentation(self):
  9.         """First line of the documentation is here.
  10.  
  11.         Longer documentation continues here and it can contain
  12.         multiple lines or paragraphs.
  13.         """
  14.         pass
  1. /**
  2.  *  This is an example library with some documentation.
  3.  */
  4. public class MyLibrary {
  5.  
  6.     /**
  7.      * This keyword has only a short documentation
  8.      */
  9.     public void keywordWithShortDocumentation(String argument) {
  10.     }
  11.  
  12.     /**
  13.      * First line of the documentation is here.
  14.      *
  15.      * Longer documentation continues here and it can contain
  16.      * multiple lines or paragraphs.
  17.      */
  18.     public void keywordWithLongerDocumentation() {
  19.     }
  20.  
  21. }

对于如上所示的源码中的库文档, Python和Java都有各自的工具来生成API文档. 不过, 这些工具的使用对某些用户来说显得稍微有些专业.

另一种方式是使用 Robot Framework自带的文档工具 Libdoc_. 这个工具不但可以创建使用静态库API的库文档, 不管是使用Python还是Java, 同时还能处理使用了 动态库API 和 混合库API

关键字文档的第一行用于特殊用途, 一般包含对该关键字的简短概述. 它在某些情况下被当作是 短文档 (即摘要)来使用, 例如在 Libdoc_ 中将作为工具提示(tool tip), 也在日志中展示( 在日志中展示对Java静态库不适用, 因为Java源码中的文档会在编译时去掉, 自然也不能在运行时获取到了).

默认情况下, 文档内容被认为是遵从 Robot Framework的 文档格式 规则的. 这份简单的格式允许使用常用的样式, 如 粗体 和 斜体, 表格, 列表, 链接等.

从 Robot Framework 2.7.5版本开始, 还可以使用HTML, 纯文本和 reStructuredText_ 格式.

关于如何设置库源码的格式请参见 指定文档格式, 关于格式的更多信息请参阅 Libdoc_ 相关章节.

注解

If you want to use non-ASCII characters in the documentation ofPython libraries, you must either use UTF-8 as your source codeencoding or create docstrings as Unicode.

库的测试

所有正式应用的测试库自身都需要彻底的被测试, 以避免其中的bug. 当然, 这些测试应该是自动化的, 这样当库有所改变时可以快速的回归测试.

Python和Java都有出色的单元测试工具, 很适合用来测试自己开发的库.使用这些单元测试工具来测试库和测试其它代码没什么区别. 熟悉这些工具的开发者无需额外学习新东西即可掌握, 当然, 不熟悉的开发者需要先学习一下.

使用Robot Framework自己来测试这些测试库也很简单, 这种方式对它们来说实际上是端到端的验收测试. BuiltIn_ 库提供了很多有用的关键字用于此类目的.特别值得一提的关键字 Run Keyword And Expect Error 就对测试关键字是否能正确地报告错误很有用.

到底是使用单元测试还是验收测试的方式取决于具体情况. 如果需要模拟真实的待测系统, 使用单元测试往往比较简单. 另一方面, 验收测试能保证关键字在Robot Framework上运行正常.当然, 如果很难取舍, 同时使用这两种方法也是可以的.

测试库打包

当测试库开发完, 文档完成, 并且通过了测试, 接下来就是分发给用户. 对于那种只包含单个文件的简单的库, 告知用户将文件拷贝到相应的 模块搜索路径 就可以了. 更复杂的库应该打包, 以便能轻松安装.

因为测试库也是普通的源代码, 所以它们也可以使用普通的打包工具. 对于Python, 一个不错的选择是 distutils_, 包含在Python的标准库中, 或者较新一点的 setuptools_.使用这些工具一个好处是, 测试库被安装的目标路径是自动包含在:ref:module search path 中的.

当使用Java时, 把库打包为JAR包是很自然的选择. 测试前必须先把这个JAR包放到 模块搜索路径, 不过, 创建一个 start-up script 来自动化处理这些事情会更轻松.

废弃关键字

有时候需要将现有的关键字替换为新的, 或者完全删除. 仅仅知会用户这些变更并不总是足够, 更有效的方式是在运行时刻发出警告. 为了达到此目的, Robot Framework 的关键字可以被标记为 废弃的 (deprecated), 这样就可以很容易发现已经过时的关键字, 并把它们删除或替换掉.

想要废弃一个关键字的话, 在关键字的文档中的第一行以 DEPRECATED 开始, 并且以一个 结束, 注意这里需要区分大小写. 例如, DEPRECATED, DEPRECATED., DEPRECATED in version 1.5. 都是合法的标记.

当执行了一个废弃的关键字, 一条已废弃警告会被记入日志, 并且这个警告同时会出现在 控制台和日志文件中的测试执行错误章节. 这个警告消息以 Keyword '<name>' is deprecated. 开头, 后面是该关键字的 短文档.

例如, 如果下面的关键字被执行, 会有如下日志文件中所示的警告:

  1. def example_keyword(argument):
  2.     """*DEPRECATED!!* Use keyword `Other Keyword` instead.
  3.  
  4.     This keyword does something to given ``argument`` and returns results.
  5.     """
  6.     return do_something(argument)
20080911 16:00:22.650WARNKeyword 'SomeLibrary.Example Keyword' is deprecated. Use keyword Other Keyword instead.

这个废弃系统对大多数的库都有效, 包括 用户关键字. 唯一的例外是用Java 静态库接口 实现的静态关键字, 因为文档会在编译时丢失, 无法在运行时获取到. 对于这些关键字, 可以使用用户关键字作为封装, 然后废弃.

注解

Robot Framework 2.9版本之前, 文档必须精确地以 DEPRECATED 开始,在结束星号 * 之前不能有任何额外的内容.