支持的编程语言

Robot Framework本身是用Python编写的，自然测试库扩展它可以使用相同的语言实现。在Jython上运行框架时，也可以使用Java实现库。纯Python代码适用于Python和Jython，假设它不使用Jython上不可用的语法或模块。使用Python时，也可以使用Python C API使用C实现库，尽管使用ctypes模块与Python库中的C代码交互通常更容易 。

使用这些本机支持的语言实现的库也可以充当使用其他编程语言实现的功能的包装。这种方法的一个很好的例子是远程库，另一种广泛使用的方法是将外部脚本或工具作为单独的进程运行。

不同的测试库API

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

静态API

最简单的方法是使用一个模块（在Python中）或一个类（在Python或Java中），其方法直接映射到 关键字名称。关键字也采用与实现它们的方法相同的参数。关键字报告带有异常的失败，通过写入标准输出进行记录，并使用return语句返回值。

动态API

动态库是实现获取它们实现的关键字名称的方法的类，以及使用给定参数执行命名关键字的另一种方法。要实现的关键字的名称以及它们的执行方式可以在运行时动态确定，但报告状态，记录和返回值的方式与静态API类似。

混合API

这是静态API和动态API之间的混合体。库是一种类，它使用一种方法来告知它们实现了哪些关键字，但这些关键字必须直接可用。除了发现实现哪些关键字之外的其他所有内容与静态API中的类似。

本章将介绍所有这些API。一切都基于静态API的工作原理，因此首先讨论它的功能。如何动态库API和混合库API从它的不同，然后在自己的章节中讨论。

本章中的示例主要是关于使用Python，但对于仅限Java的开发人员来说，它们也应该易于理解。在API有差异的少数情况下，两个用法都用适当的例子来解释。

测试库名称

导入库时使用的测试库的名称与实现它的模块或类的名称相同。例如，如果您有一个Python模块MyLibrary（即文件MyLibrary.py），它将创建一个名为MyLibrary的库 。类似地，Java类YourLibrary当它不在任何包中时，会创建一个具有该名称的库。

Python类总是在一个模块中。如果实现库的类的名称与模块的名称相同，则Robot Framework允许在导入库时删除模块名称。例如，类MyLib中在MyLib.py 文件可以被用作与所述名称的库MyLib中。如果模块名称和类名称不同，则必须使用模块和类名称（例如mymodule.MyLibrary）使用库。

必须使用全名来使用非默认包中的Java类。例如，类MyLib中在 com.mycompany.myproject包必须与名称导入 com.mycompany.myproject.MyLib。

为测试库提供参数

作为类实现的所有测试库都可以使用参数。这些参数在库名称后面的Setting表中指定，当Robot Framework创建导入库的实例时，它将它们传递给它的构造函数。作为模块实现的库不能接受任何参数，因此尝试使用这些参数会导致错误。

库所需的参数数量与库的构造函数接受的参数数量相同。参数的默认值和变量数与关键字参数的工作方式类似，但Java库没有变量参数支持。传递给库的参数以及库名称本身可以使用变量指定，因此可以更改它们，例如，从命令行更改它们。

示例实现，第一个在Python中，第二个在Java中，用于上面示例中使用的库：

from example import Connection

class MyLibrary:

    def __init__(self, host, port=80):

        self._conn = Connection(host, int(port))

    def send_message(self, message):

        self._conn.send(message)

public class AnotherLib {

    private String setting = null;

    public AnotherLib(String setting) {

        setting = setting;

    }

    public void doSomething() {

        if setting.equals("42") {

            // do something ...

        }

    }

}

测试库范围

作为类实现的库可以具有内部状态，可以通过关键字和库的构造函数的参数来更改。由于状态会影响关键字的实际行为，因此务必确保一个测试用例中的更改不会意外影响其他测试用例。这种依赖关系可能会产生难以调试的问题，例如，当添加新的测试用例并且它们使用库不一致时。

Robot Framework尝试使测试用例彼此独立：默认情况下，它为每个测试用例创建测试库的新实例。但是，这种行为并不总是令人满意的，因为有时测试用例应该能够共享一个共同的状态。此外，所有库都没有状态，并且根本不需要创建它们的新实例。

测试库可以控制何时使用类属性ROBOT_LIBRARY_SCOPE创建新库。此属性必须是字符串，并且可以具有以下三个值：

测试用例

为每个测试用例创建一个新实例。可能的套件设置和套件拆解共享另一个实例。这是默认值。

测试套房

为每个测试套件创建一个新实例。从测试用例文件创建并包含测试用例的最低级别测试套件具有自己的实例，而更高级别的套件都可以获得自己的实例来进行可能的设置和拆卸。

全球

在整个测试执行期间只创建一个实例，并由所有测试用例和测试套件共享。从模块创建的库始终是全局的。

当TEST SUITE或GLOBAL范围与具有状态的测试库一起使用时，建议库具有一些用于清理状态的特殊关键字。然后可以使用此关键字，例如，在套件设置或拆卸中，以确保下一个测试套件中的测试用例可以从已知状态开始。例如， SeleniumLibrary使用GLOBAL范围来启用在不同测试用例中使用相同的浏览器而无需重新打开它，并且它还具有Close All Browsers关键字，可以轻松关闭所有打开的浏览器。

使用TEST SUITE范围的示例Python库：

class ExampleLibrary:

    ROBOT_LIBRARY_SCOPE = 'TEST SUITE'

    def __init__(self):

        self._counter = 0

    def count(self):

        self._counter += 1

        print self._counter

    def clear_counter(self):

        self._counter = 0

使用GLOBAL范围的示例Java库：

public class ExampleLibrary {

    public static final String ROBOT_LIBRARY_SCOPE = "GLOBAL";

    private int counter = 0;

    public void count() {

        counter += 1;

        System.out.println(counter);

    }

    public void clearCounter() {

        counter = 0;

    }

}

指定库版本

当测试库被使用时，Robot Framework会尝试确定其版本。然后将此信息写入syslog 以提供调试信息。库文档工具 libdoc还将此信息写入其生成的关键字文档中。

从属性ROBOT_LIBRARY_VERSION读取版本信息 ，类似于从ROBOT_LIBRARY_SCOPE读取测试库作用域。如果 ROBOT_LIBRARY_VERSION不存在，则尝试从__version__属性读取信息。这些属性必须是类或模块属性，具体取决于库是作为类还是模块实现的。对于Java库，必须将version属性声明为static final。

使用__version__的示例Python模块：

__version__ = '0.1'

def keyword():

    pass

使用ROBOT_LIBRARY_VERSION的Java类：

public class VersionExample {

    public static final String ROBOT_LIBRARY_VERSION = "1.0.2";

    public void keyword() {

    }

}

哪些方法被视为关键字

使用静态库API时，Robot Framework使用反射来查找库类或模块实现的公共方法。它将排除以下划线开头的所有方法，并且对于Java库，也会忽略仅在java.lang.Object中实现的方法 。所有未被忽略的方法都被视为关键字。例如，下面的Python和Java库实现了单个关键字My Keyword。

class MyLibrary:

    def my_keyword(self, arg):

        return self._helper_method(arg)

    def _helper_method(self, arg):

        return arg.upper()

public class MyLibrary {

    public String myKeyword(String arg) {

        return helperMethod(arg);

    }

    private String helperMethod(String arg) {

        return arg.toUpperCase();

    }

}

当库作为Python模块实现时，也可以通过使用Python的__all__属性来限制关键字的方法 。如果使用__all__，则只有其中列出的方法可以是关键字。例如，下面的库实现关键字示例关键字和第二示例。如果没有__all__，它还会实现关键字 Not Exposed As Keyword和Current Thread。__all__最重要的用法是确保导入的辅助方法（例如下面示例中的current_thread）不会被意外地公开为关键字。

from threading import current_thread

__all__ = ['example_keyword', 'second_example']

def example_keyword():

    if current_thread().name == 'MainThread':

        print 'Running in main thread'

def second_example():

    pass

def not_exposed_as_keyword():

    pass

关键字名称

将测试数据中使用的关键字名称与方法名称进行比较，以找到实现这些关键字的方法。名称比较不区分大小写，并且忽略空格和下划线。例如，方法hello映射到关键字名称 Hello，hello甚至hello。类似地， do_nothing和doNothing方法都可以用作测试数据中的 Do Nothing关键字。

示例Python库作为MyLibrary.py文件中的模块实现：

def hello(name):

    print "Hello, %s!" % name

def do_nothing():

    pass

在MyLibrary.java文件中作为类实现的示例Java库：

public class MyLibrary {

    public void hello(String name) {

        System.out.println("Hello, " + name + "!");

    }

    public void doNothing() {

    }

}

下面的示例说明了如何使用上面的示例库。如果您想自己尝试，请确保库位于库搜索路径中。

关键字参数

使用静态和混合API，关键字所需的参数数量的信息直接来自实现它的方法。使用动态库API的库具有共享此信息的其他方法，因此本节与它们无关。

最常见也是最简单的情况是关键字需要确切数量的参数。在这种情况下，Python和Java方法都只是完全采用这些参数。例如，实现不带参数的关键字的方法也不带参数，实现带有一个参数的关键字的方法也需要一个参数，依此类推。

示例Python关键字使用不同数量的参数：

def no_arguments():

    print "Keyword got no arguments"

def one_argument(arg):

    print "Keyword got one argument '%s'" % arg

def multiple_arguments(a1, a2, a3):

    print "Keyword got three arguments '%s', '%s' and '%s'" % (a1, a2, a3)

关键字的默认值

关键字使用的某些参数具有默认值通常很有用。Python和Java具有不同的语法来处理方法的默认值，并且在为Robot Framework创建测试库时可以使用这些语言的自然语法。

def one_default(arg='default'):

    print "Argument has value '%s'" % arg

def multiple_defaults(arg1, arg2='default 1', arg3='default 2'):

    print "Got arguments %s, %s and %s" % (arg1, arg2, arg3)

public void oneDefault(String arg) {

    System.out.println("Argument has value '" + arg "'");

}

public void oneDefault() {

    oneDefault("default");

}

public void multipleDefaults(String arg1, String arg2, String arg3) {

    System.out.println("Got arguments " + arg1 + ", " + arg2 + " and " + arg3);

}

public void multipleDefaults(String arg1, String arg2) {

    multipleDefaults(arg1, arg2, "default 2");

}

public void multipleDefaults(String arg1) {

    multipleDefaults(arg1, "default 1");

}

可变数量的参数

Robot Framework还支持带有任意数量参数的关键字。与默认值类似，在Python和Java中，测试库中使用的实际语法也不同。

def any_arguments(*args):

    print "Got arguments:"

    for arg in args:

        print arg

def one_required(required, *others):

    print "Required: %s\nOthers:" % required

    for arg in others:

        print arg

def also_defaults(req, def1="default 1", def2="default 2", *rest):

    print req, def1, def2, rest

public void anyNumberOfArguments(String... varargs) {

    System.out.println("Got arguments:");

    for (String arg: varargs) {

        System.out.println(arg);

    }

}

public void oneArgumentRequired(String required, String... others) {

    System.out.println("Required: " + required + "\nOthers:");

    for (String arg: others) {

        System.out.println(arg);

    }

}

public void usingAnArray(String[] args) {

    System.out.println("Got arguments:");

    for (String arg: args) {

        System.out.println(arg);

    }

}

参数类型

通常，关键字参数作为字符串来到Robot Framework。如果关键字需要其他类型，则可以使用 变量或将字符串转换为关键字中的必需类型。使用 Java关键字时，基类型也会自动强制执行。

def connect_to_host(address, port=25):

    port = int(port)

    # ...

public void doubleArgument(double arg) {}

public void compatibleTypes(String arg1, Integer arg2) {}

public void compatibleTypes(String arg2, Integer arg2, Boolean arg3) {}

public void conflictingTypes(String arg1, int arg2) {}

public void conflictingTypes(int arg1, String arg2) {}

报告关键字状态

报告关键字状态只需使用例外即可完成。如果执行的方法引发异常，则关键字status为FAIL，如果正常返回，则状态为PASS。

日志，报告和控制台中显示的错误消息是根据异常类型及其消息创建的。对于通用异常（例如，AssertionError，Exception和 RuntimeError），仅使用异常消息，而对于其他异常消息，将以ExceptionType：Actual消息的格式创建消息。在这两种情况下，对于用户而言，异常消息尽可能地提供信息是很重要的。

如果错误消息超过40行，它将从中间自动切断，以防止报告过长且难以阅读。完整错误消息始终显示在failed关键字的日志消息中。

还使用DEBUG 日志级别记录异常的回溯。默认情况下，这些消息在日志文件中不可见，因为普通用户很少感兴趣。在开发库时，使用--loglevel DEBUG运行测试通常是个好主意。

停止测试执行

从Robot Framework 2.5开始，可能会使测试用例失败，从而 停止整个测试执行。这只需要通过一个特殊的ROBOT_EXIT_ON_FAILURE属性来完成，该 属性在从关键字引发的异常上设置了True值。这在以下示例中说明。

class MyFatalError(RuntimeError):

    ROBOT_EXIT_ON_FAILURE = True

public class MyFatalError extends RuntimeException {

    public static final boolean ROBOT_EXIT_ON_FAILURE = true;

}

尽管失败，仍继续执行测试

从Robot Framework 2.5开始，即使出现故障，也可以继续测试执行。从测试库发出信号的方法是向用于传达故障的异常添加一个特殊的ROBOT_CONTINUE_ON_FAILURE 属性，其值为True。这通过以下实施例证明。

class MyContinuableError(RuntimeError):

    ROBOT_CONTINUE_ON_FAILURE = True

public class MyContinuableError extends RuntimeException {

    public static final boolean ROBOT_CONTINUE_ON_FAILURE = true;

}

记录信息

异常消息不是向用户提供信息的唯一方式。除此之外，方法还可以通过写入标准输出流（stdout）或标准错误流（stderr）将消息发送到日志文件，甚至可以使用不同的 日志级别。另一种（通常更好的）日志记录可能性是使用编程日志API。

默认情况下，方法写入标准输出的所有内容都将作为日志级别为INFO的单个条目写入日志文件 。写入标准错误的消息将以类似方式处理，但在关键字执行完成后它们将回显到原始stderr。因此，如果您需要在执行测试的控制台上显示某些消息，则可以使用stderr。

*INFO:1308435758660* Message with timestamp

*HTML:1308435758661* <b>HTML</b> message with timestamp

import time

def example_keyword():

    print '*INFO:%d* Message with timestamp' % (time.time()*1000)

public void exampleKeyword() {

    System.out.println("*INFO:" + System.currentTimeMillis() + "* Message with timestamp");

}

import sys

def my_keyword(arg):

   sys.__stdout__.write('Got arg %s\n' % arg)

from robot.api import logger

def log_to_console(arg):

   logger.console('Got arg %s' % arg)

def log_to_console_and_log_file(arg)

   logger.info('Got arg %s' % arg, also_console=True)

print 'Hello from a library.'

print '*WARN* Warning from a library.'

print '*INFO* Hello again!'

print 'This will be part of the previous message.'

print '*INFO* This is a new message.'

print '*INFO* This is <b>normal text</b>.'

print '*HTML* This is <b>bold</b>.'

print '*HTML* <a href="http://robotframework.org">Robot Framework</a>'

程序化日志API

与使用标准输出和错误流相比，程序化API提供了更简洁的日志信息记录方式。目前，这些接口仅适用于Python基础测试库。

from robot.api import logger

def my_keyword(arg):

    logger.debug('Got argument %s' % arg)

    do_something()

    logger.info('<i>This</i> is a boring example', html=True)

    logger.console('Hello, console!')

import logging

def my_keyword(arg):

    logging.debug('Got argument %s' % arg)

    do_something()

    logging.info('This is a boring example')

在库初始化期间记录

库也可以在测试库导入和初始化期间记录。这些消息不像普通日志消息那样出现在日志文件中，而是写入syslog。这允许记录有关库初始化的任何有用的调试信息。使用WARN级别记录的消息也会 在日志文件的测试执行错误部分中显示。

使用标准输出和错误流以及编程日志API可以在导入和初始化期间进行 日志记录。以下都说明了这两点。

初始化期间通过stdout记录Java库：

public class LoggingDuringInitialization {

    public LoggingDuringInitialization() {

        System.out.println("*INFO* Initializing library");

    }

    public void keyword() {

        // ...

    }

}

导入期间使用日志记录API的Python库日志记录：

from robot.api import logger

logger.debug("Importing library")

def keyword():

    # ...

回归价值观

关键字与核心框架进行通信的最终方式是返回从被测系统检索到的信息或通过其他方式生成的信息。返回的值可以分配给测试数据中的变量，然后用作其他关键字的输入，甚至可以用于不同的测试库。

使用Python和Java方法中的return语句返回值。通常，一个值被分配到一个 标量变量中，如下面的示例所示。此示例还说明可以返回任何对象并使用 扩展变量语法来访问对象属性。

from mymodule import MyObject

def return_string():

    return "Hello, world!"

def return_object(name):

    return MyObject(name)

关键字还可以返回值，以便可以将它们一次分配到多个标量变量中，分配到列表变量中，或者分配到标量变量和列表变量中。所有这些用法都要求返回的值是Python列表或元组，或者是Java数组，列表或迭代器。

def return_two_values():

    return 'first value', 'second value'

def return_multiple_values():

    return ['a', 'list', 'of', 'strings']

使用线程时的通信

如果库使用线程，它通常应该仅从主线程与框架通信。例如，如果工作线程无法报告或记录某些内容，则应首先将信息传递给主线程，然后主线程可以使用本节中说明的异常或其他机制与框架进行通信。

当线程在后台运行而其他关键字正在运行时，这一点尤为重要。在这种情况下与框架通信的结果是未定义的，并且在工作情况下可能导致崩溃或损坏的输出文件。如果关键字在后台启动某些内容，则应该有另一个关键字来检查工作线程的状态并相应地报告收集​​的信息。

记录库

没有关于它包含哪些关键字以及这些关键字做什么的文档的测试库是没有用的。为了便于维护，强烈建议库文档包含在源代码中并从中生成。基本上，这意味着使用带Python的docstrings和Java的Javadoc，如下面的示例所示。

class MyLibrary:

    """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

/**

 *  This is an example library with some documentation.

 */

public class MyLibrary {

    /**

     * This keyword has only a short documentation

     */

    public void keywordWithShortDocumentation(String argument) {

    }

    /**

     * First line of the documentation is here.

     *

     * Longer documentation continues here and it can contain

     * multiple lines or paragraphs.

     */

    public void keywordWithLongerDocumentation() {

    }

}

Python和Java都有用于创建如上所述的库的API文档的工具。但是，对于某些用户来说，这些工具的输出可能略有技术性。另一种方法是使用Robot Framework自己的文档工具libdoc。此工具可以使用静态库API（例如上面的API）从Python和Java库创建库文档，但它也使用动态库API和混合库API处理库。

关键字文档的第一行用于特殊目的，应包含关键字的简短总体描述。它被用作一个简短的文档，例如libdoc的工具提示，也可以在测试日志中显示。但是，后者不能与使用静态API的Java库一起使用，因为它们的文档在编译时丢失，在运行时不可用。

测试库

任何非平凡的测试库都需要进行全面测试，以防止其中的错误。当然，此测试应该是自动化的，以便在更改库时轻松重新运行测试。

Python和Java都有出色的单元测试工具，它们非常适合测试库。与将其用于其他测试相比，将它们用于此目的没有重大差异。熟悉这些工具的开发人员不需要学习任何新东西，不熟悉它们的开发人员也应该学习它们。

使用Robot Framework本身也很容易测试库，这种方式对它们进行实际的端到端验收测试。为此，BuiltIn库中有许多有用的关键字。值得一提的是运行关键字和期望错误，这对于测试关键字是否正确报告错误非常有用。

是否使用单元或验收级别的测试方法取决于上下文。如果需要模拟测试中的实际系统，则在单元级别上通常更容易。另一方面，验收测试确保关键字通过Robot Framework工作。如果您无法决定，当然可以使用这两种方法。

包装库

在实施，记录和测试库之后，仍然需要将其分发给用户。对于由单个文件组成的简单库，通常要求用户在某处复制该文件并相应地设置库搜索路径。应该打包更复杂的库以使安装更容易。

由于库是普通的编程代码，因此可以使用普通的打包工具进行打包。使用Python，很好的选项包括Python标准库包含的 distutils和更新的 setuptools。这些工具的一个好处是库模块安装在库搜索路径中自动的位置。

使用Java时，将库打包到JAR存档中是很自然的。 在运行测试之前，必须将JAR包放入库搜索路径，但是很容易创建一个自动执行该操作的启动脚本。

弃用关键字

有时需要用新的关键字替换现有的关键字或完全删除它们。仅通知用户有关更改的信息可能并不总是足够，并且在运行时获取警告更有效。为了支持这一点，Robot Framework能够标记已弃用的关键字。这样可以更轻松地从测试数据中查找旧关键字并删除或替换它们。

通过使用* DEPRECATED *启动文档来弃用关键字 。执行这些关键字时，会将包含其余简短文档的警告写入 控制台，并写入日志文件中的单独“测试执行错误”部分。例如，如果执行了以下关键字，则会在日志文件中显示如下所示的警告。

def example_keyword(argument):

    """*DEPRECATED* Use keyword `Other Keyword` instead.

    This keyword does something to given `argument` and returns the result.

    """

    return do_something(argument)

此弃用系统适用于大多数测试库以及 用户关键字。唯一的例外是在使用静态库接口的Java测试库中实现的关键字，因为它们的文档在运行时不可用。使用这样的关键字，可以将用户关键字用作包装并弃用它们。

计划实施一种工具，可以使用弃用信息自动替换已弃用的关键字。该工具很可能从文档中获取新关键字的名称，以便它在反引号（`）中搜索单词。因此，它会从前面的例子中找到其他关键字。请注意，libdoc还使用相同的语法自动创建内部链接。

获取关键字名称

动态库通过get_keyword_names方法告知它们实现了哪些关键字 。该方法还具有在编写Java时建议使用的别名 getKeywordNames。此方法不能接受任何参数，并且必须返回包含库实现的关键字名称的字符串列表（在Python中）或字符串数​​组（在Java中）。

如果返回的关键字名称包含多个单词，则可以使用空格或下划线或camelCase格式返回它们。例如，['first keyword'，'second keyword']， ['first_keyword'，'second_keyword']和 ['firstKeyword'，'secondKeyword']都会产生关键字 First Keyword和Second Keyword。

动态库必须始终具有此方法。如果它丢失，或者由于某种原因调用它失败，则库被视为静态库。

运行关键字

动态库有一个特殊的run_keyword（别名 runKeyword）方法来执行它们的关键字。当在测试数据中使用动态库中的关键字时，Robot Framework使用库的run_keyword方法来执行它。此方法有两个参数。第一个参数是一个字符串，其中包含要以与get_keyword_names返回的格式相同的格式执行的关键字的名称。第二个参数是给测试数据中的关键字的参数列表（Java中的对象数组）。

在获得关键字名称和参数之后，它可以*地执行关键字，但它必须使用相同的机制与框架作为静态库进行通信。这意味着使用异常来报告关键字状态，通过写入标准输出进行日志记录，并使用run_keyword中的return语句 返回内容。

每个动态库都必须同时具有get_keyword_names和 run_keyword方法。动态API中的其余方法是可选的，因此下面的示例显示了一个有效的（虽然是微不足道的）动态库。

class DynamicExample:

    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)

获取关键字参数

如果动态库仅实现get_keyword_names和 run_keyword方法，则Robot Framework不具有有关实现的关键字所需参数的任何信息。例如，上例中的第一关键字和第二关键字都可以与任意数量的参数一起使用。这是有问题的，因为大多数真正的关键字都需要一定数量的关键字，在这种情况下，他们需要自己检查参数计数。

动态库可以使用get_keyword_arguments（别名getKeywordArguments）方法告诉Robot Framework它实现的关键字实际上期望的参数 。此方法将关键字的名称作为参数，并返回包含该关键字接受的参数的字符串列表（Java中的字符串数组）。

与静态关键字类似，动态关键字可以要求任意数量的参数，具有默认值并接受可变数量的参数。下表说明了如何表示所有这些不同情况的语法。请注意，这些示例使用Python字符串列表，但Java开发人员应该能够将它们转换为字符串数组。

使用get_keyword_arguments时，Robot Framework会自动计算关键字所需的参数数量。如果关键字与无效数量的参数一起使用，则会发生错误，甚至不会调用run_keyword。上表的最后一列显示了根据提供的示例计算的最小和最大参数计数。

执行测试时，实际参数名称无关紧要，因为只有参数计数与Robot Framework有关。另一方面，如果使用libdoc工具来记录库，则文档中会显示参数，在这种情况下，它们需要具有有意义的名称。

获取关键字文档

动态库可以实现的最终特殊方法是 get_keyword_documentation（别名为 getKeywordDocumentation）。它将关键字名称作为参数，并且正如方法名称所暗示的那样，将其文档作为字符串返回。

返回的文档与使用Python实现的静态库的关键字文档字符串类似。主要用例是将关键字的文档记录到使用libdoc生成的库文档中。此外，文档的第一行（直到第一行\ n）显示在测试日志中。

获取通用库文档

该get_keyword_documentation方法也可以用于指定整体库文档。执行测试时不使用此文档，但它可以使libdoc生成的文档更好。

动态库可以提供与使用库相关的通用库文档和文档。前者是通过使用特殊值 __intro__调用get_keyword_documentation得到的，后者是使用值 __init__获得的。如何使用libdoc在实践中最好地测试文档的呈现方式。

基于Python的动态库还可以直接在代码中将通用库文档指定为库类的文档字符串或其__init__方法。如果直接从代码和get_keyword_documentation方法获得非空文档 ，则后者具有更高的优先级。

摘要

动态API中的所有特殊方法都列在下表中。方法名称以下划线格式列出，但它们的camelCase别名的工作方式完全相同。

可以用Java编写正式的接口规范，如下所示。但是，请记住库不需要实现任何显式接口，因为如果库具有所需的get_keyword_names和 run_keyword方法，Robot Framework会直接检查反射。此外， get_keyword_arguments和get_keyword_documentation 是完全可选的。

public interface RobotFrameworkDynamicAPI {

    String[] getKeywordNames();

    Object runKeyword(String name, Object[] arguments);

    String[] getKeywordArguments(String name);

    String getKeywordDocumentation(String name);

}

使用动态API的一个很好的例子是Robot Framework自己的 远程库。

获取关键字名称

关键字名称的获取方式与动态API完全相同。实际上，库需要使用 get_keyword_names或getKeywordNames方法返回库实现的关键字名称列表。

运行关键字

在混合API中，没有用于执行关键字的run_keyword方法。相反，Robot Framework使用反射来查找实现关键字的方法，与静态API类似。使用混合API的库可以直接实现这些方法，或者更重要的是，它可以动态处理它们。

在Python中，使用__getattr__方法可以轻松地动态处理缺少的 方法。大多数Python程序员可能都熟悉这种特殊方法，他们可以立即理解以下示例。其他人可能会发现首先参考Python参考手册更容易。

from somewhere import external_keyword

class HybridExample:

    def get_keyword_names(self):

        return ['my_keyword', 'external_keyword']

    def my_keyword(self, arg):

        print "My Keyword called with '%s'" % arg

    def __getattr__(self, name):

        if name == 'external_keyword':

            return external_keyword

        raise AttributeError("Non-existing attribute '%s'" % name)

请注意，__ getattr__不会像动态API 那样执行run_keyword这样的实际关键字 。相反，它只返回一个可调用的对象，然后由Robot Framework执行。

另一点需要注意的是，Robot Framework使用与get_keyword_names相同的名称来查找实现它们的方法。因此，必须以与定义它们相同的格式返回在类本身中实现的方法的名称。例如，如果get_keyword_names返回My Keyword而不是 my_keyword，则上面的库将无法正常工作 。

混合API对Java不是很有用，因为它不可能用它来处理丢失的方法。当然，可以实现库类中的所有方法，但与静态API相比，这几乎没有什么好处。

获取关键字参数和文档

使用此API时，Robot Framework使用反射来查找实现关键字的方法，与静态API类似。在获得对该方法的引用之后，它将从中搜索参数和文档，其方式与使用静态API时相同。因此，不需要像动态API那样获取参数和文档的特殊方法。

摘要

在Python中实现测试库时，混合API具有与实际动态API相同的动态功能。它的一大好处是没有必要使用特殊的方法来获取关键字参数和文档。唯一真正的动态关键字需要在__getattr__中处理，而其他关键字可以直接在主库类中实现。

由于具有明显的优势和相同的功能，在使用Python时，混合API在大多数情况下是比动态API更好的替代方案。一个值得注意的例外是将库实现为其他地方的实际库实现的代理，因为实际的关键字必须在别处执行，代理只能传递关键字名称和参数。

使用混合API的一个很好的例子是Robot Framework自己的 Telnet库。

可用的API

从Robot Framework 2.7开始，API文档在优秀的Read the Docs服务中单独托管。如果您不确定如何使用某些API或使用它们向前兼容，请将问题发送到邮件列表。

使用BuiltIn库

最安全的API是在BuiltIn库中实现关键字的方法 。对关键字的更改很少见，并且总是这样做，以便首先弃用旧用法。最有用的方法之一是replace_variables，它允许访问当前可用的变量。以下示例演示了如何获取 $ {OUTPUT_DIR}，这是许多方便的自动变量之一。也可以使用set_test_variable，set_suite_variable和 set_global_variable从库中设置新变量。

import os.path

from robot.libraries.BuiltIn import BuiltIn

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>'

使用BuiltIn方法的唯一方法是必须特别处理所有 run_keyword方法变体。使用run_keyword方法的方法必须使用BuiltIn模块中的register_run_keyword 方法自行注册为运行关键字。这个方法的文档解释了为什么需要这样做，显然也是如何做到这一点。

修改原始源代码

如果您可以访问要扩展的库的源代码，则可以自然地直接修改源代码。这种方法的最大问题是，您可能很难在不影响更改的情况下更新原始库。对于用户而言，使用具有与原始功能不同的功能的库也可能会令人困惑。重新包装库也可能是一项重大的额外任务。

如果增强功能是通用的，并且您计划将它们提交给原始开发人员，则此方法非常有效。如果您的更改应用于原始库，则它们将包含在将来的版本中，并且可以减轻上面讨论的所有问题。如果更改是非泛型的，或者由于某些其他原因无法将其提交回来，则后续部分中解释的方法可能会更好。

使用继承

扩展现有库的另一种直接方法是使用继承。下面的示例说明了这一点，它为SeleniumLibrary添加了新的 Title At Start With关键字。此示例使用Python，但您显然可以用相同的方式在Java代码中扩展现有Java库。

from SeleniumLibrary import SeleniumLibrary

class ExtendedSeleniumLibrary(SeleniumLibrary):

    def title_should_start_with(self, expected):

        title = self.get_title()

        if not title.startswith(expected):

            raise AssertionError("Title '%s' did not start with '%s'"

                                 % (title, expected))

与修改原始库相比，这种方法的一个重大区别是新库的名称与原始库的名称不同。一个好处是，您可以轻松地告诉您正在使用自定义库，但一个大问题是您无法轻松地将新库与原始库一起使用。首先，您的新库将具有与原始含义相同的关键字，即始终 存在冲突。另一个问题是图书馆不共享其状态。

当您开始使用新库并希望从头开始添加自定义增强功能时，此方法很有效。否则，本节中解释的其他机制可能更好。

直接使用其他库

因为测试库在技术上只是类或模块，所以使用另一个库的简单方法是导入它并使用其方法。当方法是静态的并且不依赖于库状态时，这种方法很有效。前面使用Robot Framework的BuiltIn库的示例说明了这一点。

但是，如果图书馆有州，那么事情可能无法发挥作用。您在库中使用的库实例将与框架使用的库实例不同，因此库中不会显示由执行的关键字完成的更改。下一节将介绍如何访问框架使用的同一个库实例。

从Robot Framework获取活动库实例

Robot Framework 2.5.2添加了新的BuiltIn关键字Get Library Instance，可用于从框架本身获取当前活动的库实例。此关键字返回的库实例与框架本身使用的相同，因此查看正确的库状态没有问题。虽然此功能可作为关键字使用，但它通常通过导入BuiltIn库类直接在测试库中使用，如前所述。以下示例说明了如何实现与前面关于使用继承的示例相同的Title Should Start With关键字。

from robot.libraries.BuiltIn import BuiltIn

def title_should_start_with(expected):

    seleniumlib = BuiltIn().get_library_instance('SeleniumLibrary')

    title = seleniumlib.get_title()

    if not title.startswith(expected):

        raise AssertionError("Title '%s' did not start with '%s'"

                             % (title, expected))

这种方法明显优于直接导入库并在库具有状态时使用它。继承的最大好处是您可以正常使用原始库，并在需要时使用新库。这在下面的示例中进行了演示，其中前面示例中的代码预计可在新库SeLibExtensions中使用。

使用动态或混合API的库

使用动态或混合库API的测试库通常有自己的系统如何扩展它们。使用这些库，您需要向库开发人员咨询或查阅库文档或源代码。