ct

模

CT

模块摘要

Common Test框架的主要用户界面。

描述

Common Test框架的主要用户界面。

此模块实现了用于运行测试的命令行界面以及Common Test案例问题的基本功能，例如配置和日志记录。

测试套件支持宏

config宏定义在ct.hrl。这个宏将被用来从Config发送到所有测试用例的变量中检索信息。它与两个参数一起使用; 第一个是要检索的配置变量的名称，第二个是Config提供给测试用例的变量。

可能的配置变量包括：

• data_dir-数据档案目录

• priv_dir-划痕文件目录

• 无论在测试套件中init_per_suite/1还是init_per_testcase/2在测试套件中添加。

数据类型

handle() = pid()

连接的身份（句柄）。

config_key() = atom()

配置文件中存在的配置键。

target_name() = atom()

ct:require/2例如，通过require语句或调用引入的配置数据的名称和关联ct:require(mynodename,{node,[telnet]})。

key_or_name() = config_key() | target_name()conn_log_options() = [conn_log_option()]

可以赋予cth_conn_log挂钩的选项，用于记录NETCONF和Telnet连接。查看ct_netconfc或ct_telnet了解如何使用此钩子的说明和示例。

conn_log_option() = {log_type,conn_log_type()} | {hosts,[key_or_name()]}conn_log_type() = raw | pretty | html | silentconn_log_mod() = ct_netconfc | ct_telnet

出口

abort_current_testcase(Reason) -> ok | {error, ErrorReason}

类型

中止当前正在执行的测试用例。用户必须确定地知道当前正在执行哪个测试用例。因此该函数只能从被测试用例调用（或同步调用）的函数中调用。

Reason，中止测试用例的原因将打印在测试用例日志中。

add_config(Callback, Config) -> ok | {error, Reason}

类型

使用指定的回调模块和配置字符串加载配置变量。回调模块将被加载或存在于代码部分。加载的配置变量稍后可以使用函数删除ct:remove_config/2。

break(Comment) -> ok | {error, Reason}

类型

取消任何活动的时间间隔并暂停当前测试用例的执行，直到用户调用函数continue/0。然后，用户可以与运行测试的Erlang节点进行交互，例如，用于调试目的或手动执行测试用例的一部分。如果并行组正在执行，则将ct:break/2被调用。

取消的时间间隔不会在休息后自动重新激活，但必须以明确方式开始ct:timetrap/1。

为了使break / continue功能正常工作，Common Test必须释放shell进程控制stdin。这是通过将开始选项设置release_shell为true。有关详细信息，请参阅Running Tests from the Erlang Shell or from an Erlang Program用户指南中的部分。

break(TestCase, Comment) -> ok | {error, Reason}

类型

与工作方式相同ct:break/1，只有参数TestCase才能暂停在并行组中执行的测试用例。函数ct:continue/1被用来恢复执行TestCase。

有关详情，请参阅ct:break/1。

capture_get() -> ListOfStrings

类型

相当于ct:capture_get([default])。

capture_get(ExclCategories) -> ListOfStrings

类型

返回并清除最近一次捕获打印输出期间缓冲的文本字符串列表stdout。需要忽略的日志类别ListOfStrings可以用来指定ExclCategories。如果ExclCategories = []没有过滤发生。

又见ct:capture_start/0，ct:capture_stop/0，ct:log/3。

capture_start() -> ok

开始捕获stdout测试用例执行过程中打印的所有文本字符串。

另见ct:capture_get/1，ct:capture_stop/0。

capture_stop() -> ok

停止捕获文本字符串（以会话开始capture_start/0）。

另见ct:capture_get/1，ct:capture_start/0。

comment(Comment) -> ok

类型

Comment在测试套件结果页面的表格的注释字段中打印指定的内容。

如果多次调用，则只打印最后的注释。测试用例返回值将{comment,Comment}覆盖此函数设置的字符串。

comment(Format, Args) -> ok

类型

在测试套件结果页的表中的注释字段中打印格式化字符串。

参数Format并Args用于调用io_lib:format/2以创建注释字符串。其他行为comment/2与函数相同ct:comment/1。

continue() -> ok

在测试用例（不在并行组中执行）调用函数之后，必须调用此函数才能继续ct:break/1。

continue(TestCase) -> ok

类型

在测试用例调用后，必须调用该函数才能继续ct:break/2。如果已暂停的测试用例TestCase在并行组中执行continue/0，则必须使用此函数而不是用于让测试用例继续。

decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error, Reason}

类型

解密EncryptFileName，以前生成ct:encrypt_config_file/2,3。原始文件内容保存在目标文件中。加密密钥（一个字符串）必须在名为的文本文件中可用.ct_config.crypt，可以在当前目录或用户的主目录中（按照该顺序搜索它）。

decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok | {error, Reason}

类型

解密EncryptFileName，以前生成ct:encrypt_config_file/2,3。原始文件内容保存在目标文件中。密钥必须与用于加密的密钥值相同。

encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Reason}

类型

使用DES3加密源配置文件并将结果保存到文件中EncryptFileName。密钥（字符串）必须在名为的文本文件中可用，该文件名称.ct_config.crypt可以在当前目录或用户的主目录中（按照该顺序搜索）。

有关运行测试时使用加密配置文件的信息，请参见Encrypted Configuration Files用户指南中的一节。

有关DES3加密/解密的详细信息，请参阅应用程序Crypto。

encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ok | {error, Reason}

类型

使用DES3加密源配置文件并将结果保存到目标文件中EncryptFileName。要使用的加密密钥是{key,Key}指定的文件中的值或存储在其中的值{file,File}。

有关运行测试时使用加密配置文件的信息，请参见Encrypted Configuration Files用户指南中的一节。

有关DES3加密/解密的详细信息，请参阅应用程序Crypto。

fail(Reason) -> ok

类型

用指定的错误终止测试用例Reason。

fail(Format, Args) -> ok

类型

用一个格式字符串和一个值列表（用作参数io_lib:format/2）指定的错误消息来终止测试用例。

get_config(Required) -> Value

相当于ct:get_config(Required, undefined, [])。

get_config(Required, Default) -> Value

相当于ct:get_config(Required, Default, [])。

get_config(Required, Default, Opts) -> ValueOrElement

类型

读取配置数据值。

给定配置变量键或其关联名称（如果已经使用ct:require/2或指定了一个require语句），返回匹配值或配置元素。

例子：

给定以下配置文件：

{unix,[{telnet,IpAddr},
       {user,[{username,Username},
              {password,Password}]}]}.

然后：

ct:get_config(unix,Default) -> [{telnet,IpAddr}, 
 {user, [{username,Username}, {password,Password}]}]
ct:get_config({unix,telnet},Default) -> IpAddr
ct:get_config({unix,user,username},Default) -> Username
ct:get_config({unix,ftp},Default) -> Default
ct:get_config(unknownkey,Default) -> Default

如果一个配置变量键已经与一个名字（通过ct:require/2或一个require语句）相关联，则可以使用该名称而不是该键来读取该值：

ct:require(myuser,{unix,user}) -> ok.
ct:get_config(myuser,Default) -> [{username,Username}, {password,Password}]

如果配置变量在多个文件中定义，请使用选项all访问所有可能的值。这些值在列表中返回。元素的顺序对应于启动时指定配置文件的顺序。

如果配置元素（键值元组）要作为结果而不是值返回，请使用选项element。返回的元素在表单上{Required,Value}。

又见ct:get_config/1，ct:get_config/2，ct:require/1，ct:require/2。

get_event_mgr_ref() -> EvMgrRef

类型

获取对Common Test事件管理器的引用。例如，引用可用于在测试运行时添加用户特定的事件处理程序。

例子：

gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])

get_status() -> TestStatus | {error, Reason} | no_tests_running

类型

返回正在进行的测试状态。返回的列表包含有关哪个测试用例正在执行的信息（并行测试用例组正在执行的情况列表）以及迄今为止成功，失败，跳过和总测试用例的计数器。

get_target_name(Handle) -> {ok, TargetName} | {error, Reason}

类型

返回指定连接所属目标的名称。

get_testspec_terms() -> TestSpecTerms | undefined

类型

获取用于配置和运行此测试的所有测试规范术语的列表。

get_testspec_terms(Tags) -> TestSpecTerms | undefined

类型

从用于配置和运行此测试的测试规范中读取一个或多个术语。Tag是任何有效的测试规范标签，例如label，config，或logdir。如果allow_user_terms设置了选项，用户特定的术语也可以读取。

除用户术语外，所有返回的值元组都将节点名称作为第一个元素。

为了读取测试方面，使用Tag = tests（而不是suites，groups或cases）。Value然后是表单上所有测试的列表[{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...]，其中GroupsAndCases = [{Group,[Case]}] | [Case]。

get_timetrap_info() -> {Time, {Scaling,ScaleVal}}

类型

读取有关当前测试用例的时间集设置的信息。Scaling指示是否Common Test会尝试自动补偿由例如工具（如封面）引入的运行时延迟的时间限制。ScaleVal是当前缩放倍数的值（如果缩放禁用，则始终为1）。请注意，Time这不是缩放结果。

get_verbosity(Category) -> Level | undefined

类型

该函数返回指定日志记录类别的详细级别。查看User's Guide详情。使用该值default来阅读一般的详细程度级别。

install(Opts) -> ok | {error, Reason}

类型

安装配置文件和事件处理程序。

在第一个测试之前运行这个函数一次。

例子：

install([{config,["config_node.ctc","config_user.ctc"]}])

该功能由程序自动运行ct_run。

listenv(Telnet) -> [Env]

类型

listenv对指定的Telnet连接执行命令，并将结果作为键值对列表返回。

log(Format) -> ok

相当于ct:log(default, 50, Format, [], [])。

log(X1, X2) -> ok

类型

相当于ct:log(Category, Importance, Format, FormatArgs, [])。

log(X1, X2, X3) -> ok

类型

相当于ct:log(Category, Importance, Format, FormatArgs, Opts)。

log(X1, X2, X3, X4) -> ok

类型

相当于ct:log(Category, Importance, Format, FormatArgs, Opts)。

log(Category, Importance, Format, FormatArgs, Opts) -> ok

类型

从测试用例打印到日志文件。

此函数用于直接从测试用例打印字符串到测试用例日志文件。

缺省值Category是default，缺省值Importance是?STD_IMPORTANCE，缺省值FormatArgs是[]。

有关详细信息Category，Importance与no_css选项，请参见Logging - Categories and Verbosity Levels用户指南中。

在使用此功能打印的文本中，Common Test不会转义特殊的HTML字符（<，>和＆），除非使用该esc_chars选项。

make_priv_dir() -> ok | {error, Reason}

类型

如果测试开始于选项create_priv_dir设置为manual_per_tc，为了使测试用例使用私人目录，它必须首先通过调用该函数来创建。

notify(Name, Data) -> ok

类型

发送类型的异步通知Name用Data的公共测试事件管理器。这可以在以后被任何安装的事件管理器捕获。

另见gen_event(3)。

pal(Format) -> ok

相当于ct:pal(default, 50, Format, [], [])。

pal(X1, X2) -> ok

类型

相当于ct:pal(Category, Importance, Format, FormatArgs, [])。

pal(X1, X2, X3) -> ok

类型

相当于ct:pal(Category, Importance, Format, FormatArgs, Opts)。

pal(X1, X2, X3, X4) -> ok

类型

相当于ct:pal(Category, Importance, Format, FormatArgs, Opts)。

pal(Category, Importance, Format, FormatArgs, Opts) -> ok

类型

从测试用例中打印和记录。

此函数用于从测试用例中打印字符串，同时打印到测试用例日志文件和控制台。

缺省值Category是default，缺省值Importance是?STD_IMPORTANCE，缺省值FormatArgs是[]。

有关详细信息Category，并Importance，见Logging - Categories and Verbosity Levels用户指南中。

请注意，在将文本打印到日志文件之前，文本中的特殊字符（<，>和＆）将被Common Test转义。

parse_table(Data) -> {Heading, Table}

类型

解析SQL表中的打印输出并返回元组列表。

要解析的打印输出通常是selectSQL 中的命令的结果。返回的Table是元组列表，其中每个元组都是表中的一行。

Heading表示表中每个列的标题的字符串的元组。

print(Format) -> ok

相当于ct:print(default, 50, Format, [], [])。

print(X1, X2) -> ok

类型

相当于ct:print(Category, Importance, Format, FormatArgs, [])。

print(X1, X2, X3) -> ok

类型

相当于ct:print(Category, Importance, Format, FormatArgs, Opts)。

print(X1, X2, X3, X4) -> ok

类型

相当于ct:print(Category, Importance, Format, FormatArgs, Opts)。

print(Category, Importance, Format, FormatArgs, Opts) -> ok

类型

从测试用例打印到控制台。

此函数用于将字符串从测试用例打印到控制台。

缺省值Category是default，缺省值Importance是?STD_IMPORTANCE，缺省值FormatArgs是[]。

有关详细信息Category，并Importance，见Logging - Categories and Verbosity Levels用户指南中。

reload_config(Required) -> ValueOrElement | {error, Reason}

类型

重新载入包含指定配置密钥的配置文件。

该函数更新从中读取指定配置变量的配置数据，并返回此变量的（可能）新值。

如果某些变量存在于配置中，但未使用此功能加载，则会将它们连同其别名一起从配置表中删除。

remove_config(Callback, Config) -> ok

类型

删除使用指定的回调模块和配置字符串加载的配置变量（与其别名一起）。

require(Required) -> ok | {error, Reason}

类型

检查所需的配置是否可用。任意深的元组可以被指定为Required。只有元组的最后一个元素可以是SubKeys 的列表。

例1.要求变量myvar*

ok = ct:require(myvar).

在这种情况下，配置文件至少必须包含：

{myvar,Value}.

示例2.需要键myvar和子键sub1和sub2：

ok = ct:require({myvar,[sub1,sub2]}).

在这种情况下，配置文件必须至少包含：

{myvar,[{sub1,Value},{sub2,Value}]}.

实施例3.需要键myvar与子项sub1与subsub1：

ok = ct:require({myvar,sub1,sub2}).

在这种情况下，配置文件必须至少包含：

{myvar,[{sub1,[{sub2,Value}]}]}.

又见ct:get_config/1，ct:get_config/2，ct:get_config/3，ct:require/2。

require(Name, Required) -> ok | {error, Reason}

类型

检查所需的配置是否可用并给出名称。除了无法指定s 的列表之外，它的语义Required与in ct:require/1相同SubKey。

如果所请求的数据可用，则该子条目与该条目相关联，Name使得可以使用ct:get_config/1,2提供来读取该元素的值Name而不是整个Required词条。

例子：

要求一个节点具有Telnet连接和FTP连接。命名节点a：

ok = ct:require(a,{machine,node}).

所有对此节点的引用都可以使用节点名称。例如，通过FTP获取文件的方式如下所示：

ok = ct:ftp_get(a,RemoteFile,LocalFile).

为此，配置文件必须至少包含：

{machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.

注

这个函数的行为在Common Test1.6.2中发生了根本性的变化。为了保持一些向后兼容性，仍然可以这样做：

ct:require(a,{node,[telnet,ftp]}).

这将名称a与顶级node条目相关联。为此，配置文件必须至少包含：

{node,[{telnet,IpAddr},{ftp,IpAddr}]}.

又见ct:get_config/1，ct:get_config/2，ct:get_config/3，ct:require/1。

run(TestDirs) -> Result

类型

在指定目录中的所有套件中运行所有测试用例。

另见ct:run/3。

run(TestDir, Suite) -> Result

运行指定套件中的所有测试用例。

另见ct:run/3。

run(TestDir, Suite, Cases) -> Result

类型

运行指定的测试用例。

要求ct:install/1是第一个运行的。

Suites（*_SUITE.erl）文件必须存储在TestDir或中TestDir/test。所有套件都在测试运行时编译。

run_test(Opts) -> Result

类型

按照选项组合中的指定运行测试Opts。这些选项是相同的那些程序中使用ct_run，请Run Tests from Command Line在ct_run手册页。

这里TestDir可以用来指出a的路径Suite。选项testcase对应-case于程序中的选项ct_run。Opts在启动时自动安装指定的配置文件。

TestRunnerPid如果返回release_shell == true。有关详情，请参阅ct:break/1。

Reason指示遇到的错误类型。

run_testspec(TestSpec) -> Result

类型

运行指定的测试TestSpec。在测试规范文件中使用相同的术语。

Reason指示遇到的错误类型。

set_verbosity(Category, Level) -> ok

类型

使用此功能可设置或修改日志记录类别的详细级别。查看User's Guide详情。使用该值default设置常规详细程度级别。

sleep(Time) -> ok

类型

该函数与timer:sleep/1STDLIB中的类似，将测试用例暂停指定的时间。但是，该函数也会Time与multiply_timetraps值（如果已设置）相乘，并且在某些情况下，如果scale_timetraps设置为true（默认值），也会自动放大时间false。

start_interactive() -> ok

开始Common Test在互动模式下。

在这种模式下，所有的测试用例支持功能都可以直接从Erlang shell中执行。交互模式也可以从OS命令行开始ct_run -shell [-config File...]。

如果使用“必需的配置数据”的任何功能（例如，Telnet或FTP）将从Erlang shell中调用，则必须首先使用配置数据ct:require/2。

例子：

> ct:require(unix_telnet, unix).
ok
> ct_telnet:open(unix_telnet).
{ok,<0.105.0>}
> ct_telnet:cmd(unix_telnet, "ls .").
{ok,["ls","file1  ...",...]}

step(TestDir, Suite, Case) -> Result

类型

使用调试器执行测试用例。

另见ct:run/3。

step(TestDir, Suite, Case, Opts) -> Result

类型

使用调试器执行测试用例。如果选项config已被指定，则也会在中的配置函数中设置断点Suite。

另见ct:run/3。

stop_interactive() -> ok

退出交互模式。

另见ct:start_interactive/0。

sync_notify(Name, Data) -> ok

类型

发送一个类型的同步通知Name与Data该Common Test事件管理器。这可以在以后被任何安装的事件管理器捕获。

另见gen_event(3)。

testcases(TestDir, Suite) -> Testcases | {error, Reason}

类型

返回指定套件中的所有测试用例。

timetrap(Time) -> ok

类型

为正在运行的测试用例设置一个新的计时器。

如果参数是Func，则此函数返回时会触发时间戳。Func也可以返回一个新Time值，在这种情况下，这是新时间戳的值。

userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}

类型

返回userdata从返回的元组列表中指定了tag的数据suite/0。

userdata(TestDir, Suite, Case::GroupOrCase) -> TCUserData | {error, Reason}

类型

返回userdata从Suite:group(GroupName)or 返回的元组列表中由tag指定的任何数据Suite:Case()。