檢視原始碼 ct (common_test v1.27.5)
用於 Common Test 框架的主要使用者介面。
此模組實作了用於執行測試的命令列介面，以及 Common Test 案例問題的基本功能，例如組態和日誌記錄。
框架將組態值儲存在通常名為 Config 的屬性列表中。此列表包含框架本身添加的關於測試執行的資訊，並且可能還包含使用者提供的值。組態會傳遞到個別的測試案例以及支援函式（如果已定義）。
可能的組態變數包括：
data_dir- 資料檔案目錄priv_dir- 暫存檔案目錄- 由測試套件中的
init_per_suite/1或init_per_testcase/2添加的任何內容。
警告
用於從
Config屬性列表接收個別組態值的?config巨集已被棄用。請改用proplists:get_value/2-3。
摘要
類型
組態檔案中存在的組態鍵
可以給予 cth_conn_log 鉤子的選項，用於記錄 NETCONF 和 Telnet 連線。有關如何使用此鉤子的描述和範例，請參閱 ct_netconfc 或 ct_telnet。
連線的識別 (handle)。
透過 require 語句或呼叫 ct:require/2 引入的名稱和與組態資料的關聯，例如 ct:require(mynodename,{node,[telnet]})。
函式
中止目前正在執行的測試案例。使用者必須明確知道目前正在執行的測試案例。因此，此函式僅能從已由測試案例呼叫（或同步調用）的函式中安全呼叫。
使用指定的回呼模組和組態字串載入組態變數。回呼模組必須已載入或存在於程式碼路徑中。載入的組態變數稍後可以使用函式 ct:remove_config/2 移除。
取消任何活動的計時陷阱，並暫停目前測試案例的執行，直到使用者呼叫函式 continue/0。然後，使用者可以與執行測試的 Erlang 節點互動，例如用於除錯目的或手動執行測試案例的一部分。如果正在執行平行群組，則應改為呼叫 ct:break/2。
與 ct:break/1 的運作方式相同，只是參數 TestCase 可以暫停在平行群組中執行的測試案例。函式 ct:continue/1 用於繼續執行 TestCase。
傳回並清除在最新擷取列印到 stdout 的期間緩衝的文字字串列表。ExclCategories 可以指定在 ListOfStrings 中要忽略的記錄類別。如果 ExclCategories = []，則不會進行篩選。
開始擷取測試案例執行期間列印到 stdout 的所有文字字串。
停止擷取文字字串（使用 capture_start/0 開始的工作階段）。
在測試套件結果頁面的表格的註解欄位中列印指定的 Comment。
在測試套件結果頁面的表格的註解欄位中列印格式化的字串。
在測試案例（不在平行群組中執行）呼叫函式 ct:break/1 後，必須呼叫此函式才能繼續執行。
在測試案例呼叫 ct:break/2 後，必須呼叫此函式才能繼續執行。如果暫停的測試案例 TestCase 在平行群組中執行，則必須使用此函式而不是 continue/0 來讓測試案例繼續執行。
解密先前使用 ct:encrypt_config_file/2,3 產生的 EncryptFileName。原始檔案內容會儲存在目標檔案中。加密金鑰（一個字串）必須在名為 .ct_config.crypt 的文字檔案中提供，該檔案位於目前目錄或使用者的主目錄中（按此順序搜尋）。
解密先前使用 ct:encrypt_config_file/2,3 產生的 EncryptFileName。原始檔案內容會儲存在目標檔案中。金鑰必須與用於加密的金鑰具有相同的值。
使用 DES3 加密來源組態檔案，並將結果儲存在檔案 EncryptFileName 中。金鑰（一個字串）必須在名為 .ct_config.crypt 的文字檔案中提供，該檔案位於目前目錄或使用者的主目錄中（按此順序搜尋）。
使用 DES3 加密來源組態檔案，並將結果儲存在目標檔案 EncryptFileName 中。要使用的加密金鑰可以是 {key,Key} 中的值，也可以是儲存在 {file,File} 指定檔案中的值。
使用指定的錯誤 Reason 終止測試案例。
使用由格式字串和值列表指定的錯誤訊息終止測試案例（用作 io_lib:format/2 的引數）。
讀取組態資料值。
取得 Common Test 事件管理員的參考。此參考可用於例如在測試執行時新增使用者特定的事件處理常式。
傳回用於啟動此 Erlang 執行個體的命令。如果找不到此資訊，則會傳回字串 "no_prog_name"。
傳回正在進行的測試狀態。傳回的列表包含正在執行的測試案例的相關資訊（當平行測試案例群組正在執行時，會是案例列表），以及目前為止成功、失敗、跳過和總測試案例的計數器。
傳回指定連線所屬的目標名稱。
取得用於組態和執行此測試的所有測試規格術語列表。
從用於組態和執行此測試的測試規格中讀取一個或多個術語。Tag 是任何有效的測試規格標籤，例如 label、config 或 logdir。如果設定了選項 allow_user_terms，也可以讀取使用者特定的術語。
讀取為目前測試案例設定的計時陷阱相關資訊。Scaling 指示 Common Test 是否會嘗試自動補償因執行時間延遲而引入的計時陷阱，例如 cover 等工具。ScaleVal 是目前縮放乘數的值（如果停用縮放，則永遠為 1）。請注意，Time 不是縮放後的結果。
此函式傳回指定記錄類別的詳細程度。有關詳細資訊，請參閱使用者指南。使用值 default 讀取一般詳細程度。
安裝組態檔案和事件處理常式。
在指定的 Telnet 連線上執行命令 listenv，並將結果傳回為鍵值對列表。
從測試案例列印到記錄檔。
如果測試啟動時選項 create_priv_dir 設定為 manual_per_tc，則為了讓測試案例使用私有目錄，它必須先呼叫此函式來建立私有目錄。
將類型為 Name、資料為 Data 的非同步通知傳送到 Common Test 事件管理員。稍後可以由任何已安裝的事件管理員攔截此通知。
解析 SQL 表格的輸出，並傳回元組列表。
重新載入包含指定設定鍵的設定檔。
此函式將傳回在此呼叫時仍在執行的測試和群組領導程序的身分。TestProcs 是系統中以 Common Test IO 程序作為群組領導者的程序。SharedGL 是中央 Common Test IO 程序，負責列印到設定函式的記錄檔，並依序執行測試案例。OtherGLs 是 Common Test IO 程序，負責將並行測試案例群組中的測試案例列印到記錄檔。
移除使用指定的 callback 模組和設定字串載入的設定變數（及其別名）。
檢查所需的設定是否可用。可以將任意深度的元組指定為 Required。元組的最後一個元素只能是 SubKey 的列表。
檢查所需的設定是否可用，並給予一個名稱。 Required 的語意與 ct:require/1 中的相同，只是不能指定 SubKey 的列表。
執行指定目錄中所有套件中的所有測試案例。
執行指定套件中的所有測試案例。
執行指定的測試案例。
依照 Opts 中的選項組合指定的執行測試。選項與程式 ct_run 使用的選項相同，請參閱 ct_run 手冊頁中的從命令列執行測試。
執行由 TestSpec 指定的測試。使用的詞彙與測試規格檔案中的相同。
使用此函式設定或修改記錄類別的詳細程度。詳細資訊請參閱使用者指南。使用值 default 設定一般詳細程度。
此函式與 STDLIB 中的 timer:sleep/1 類似，會將測試案例暫停指定的時間。但是，如果設定了 multiply_timetraps 值，此函式也會將 Time 乘以該值，並且在某些情況下，如果將 scale_timetraps 設定為 true（預設為 false），也會自動縮放時間。
以互動模式啟動 Common Test。
使用偵錯工具逐步執行測試案例。
使用偵錯工具逐步執行測試案例。如果指定了選項 config，也會在 Suite 中的設定函式上設定中斷點。
結束互動模式。
將 Name 類型的同步通知與 Data 傳送至 Common Test 事件管理員。稍後可以由任何已安裝的事件管理員攔截。
傳回指定套件中的所有測試案例。
為正在執行的測試案例設定新的時間陷阱。
傳回從 suite/0 傳回的元組列表中，以標籤 userdata 指定的任何資料。
傳回從 Suite:group(GroupName) 或 Suite:Case() 傳回的元組列表中，以標籤 userdata 指定的任何資料。
類型
-type config_key() :: atom().
組態檔案中存在的組態鍵
-type conn_log_mod() :: ct_netconfc | ct_telnet.
-type conn_log_option() :: {log_type, conn_log_type()} | {hosts, [key_or_name()]}.
-type conn_log_options() :: [conn_log_option()].
可以給予 cth_conn_log 鉤子的選項，用於記錄 NETCONF 和 Telnet 連線。有關如何使用此鉤子的描述和範例，請參閱 ct_netconfc 或 ct_telnet。
-type conn_log_type() :: raw | pretty | html | silent.
-type handle() :: pid().
連線的識別 (handle)。
-type key_or_name() :: config_key() | target_name().
-type target_name() :: atom().
透過 require 語句或呼叫 ct:require/2 引入的名稱和與組態資料的關聯，例如 ct:require(mynodename,{node,[telnet]})。
函式
-spec abort_current_testcase(Reason) -> ok | {error, ErrorReason} when Reason :: term(), ErrorReason :: no_testcase_running | parallel_group.
中止目前正在執行的測試案例。使用者必須明確知道目前正在執行的測試案例。因此，此函式僅能從已由測試案例呼叫（或同步調用）的函式中安全呼叫。
Reason（中止測試案例的原因）會列印在測試案例記錄中。
-spec add_config(Callback, Config) -> ok | {error, Reason} when Callback :: atom(), Config :: string(), Reason :: term().
使用指定的回呼模組和組態字串載入組態變數。回呼模組必須已載入或存在於程式碼路徑中。載入的組態變數稍後可以使用函式 ct:remove_config/2 移除。
-spec break(Comment) -> ok | {error, Reason} when Comment :: string(), Reason :: {multiple_cases_running, TestCases} | 'enable break with release_shell option', TestCases :: [atom()].
取消任何活動的計時陷阱，並暫停目前測試案例的執行，直到使用者呼叫函式 continue/0。然後，使用者可以與執行測試的 Erlang 節點互動，例如用於除錯目的或手動執行測試案例的一部分。如果正在執行平行群組，則應改為呼叫 ct:break/2。
取消的時間陷阱不會在休息後自動重新啟動，而是必須使用 ct:timetrap/1 明確啟動。
為了使中斷/繼續功能正常運作，Common Test 必須釋放控制 stdin 的 shell 程序。這可以透過將啟動選項 release_shell 設定為 true 來完成。如需詳細資訊，請參閱使用者指南中的 從 Erlang Shell 或 Erlang 程式執行測試一節。
-spec break(TestCase, Comment) -> ok | {error, Reason} when TestCase :: atom(), Comment :: string(), Reason :: 'test case not running' | 'enable break with release_shell option'.
與 ct:break/1 的運作方式相同，只是參數 TestCase 可以暫停在平行群組中執行的測試案例。函式 ct:continue/1 用於繼續執行 TestCase。
如需詳細資訊，請參閱 ct:break/1。
-spec capture_get() -> ListOfStrings when ListOfStrings :: [string()].
-spec capture_get(ExclCategories) -> ListOfStrings when ExclCategories :: [atom()], ListOfStrings :: [string()].
傳回並清除在最新擷取列印到 stdout 的期間緩衝的文字字串列表。ExclCategories 可以指定在 ListOfStrings 中要忽略的記錄類別。如果 ExclCategories = []，則不會進行篩選。
-spec capture_start() -> ok.
開始擷取測試案例執行期間列印到 stdout 的所有文字字串。
-spec capture_stop() -> ok.
停止擷取文字字串（使用 capture_start/0 開始的工作階段）。
-spec comment(Comment) -> ok when Comment :: term().
在測試套件結果頁面的表格的註解欄位中列印指定的 Comment。
如果多次呼叫，則只會列印最後一個註解。測試案例傳回值 {comment,Comment} 會覆寫由此函式設定的字串。
在測試套件結果頁面的表格的註解欄位中列印格式化的字串。
參數 Format 和 Args 用於呼叫 io_lib:format/2 來建立註解字串。comment/2 的行為與函式 ct:comment/1 的行為相同。
-spec continue() -> ok.
在測試案例（不在平行群組中執行）呼叫函式 ct:break/1 後，必須呼叫此函式才能繼續執行。
-spec continue(TestCase) -> ok when TestCase :: atom().
在測試案例呼叫 ct:break/2 後，必須呼叫此函式才能繼續執行。如果暫停的測試案例 TestCase 在平行群組中執行，則必須使用此函式而不是 continue/0 來讓測試案例繼續執行。
-spec decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error, Reason} when EncryptFileName :: string(), TargetFileName :: string(), Reason :: term().
解密先前使用 ct:encrypt_config_file/2,3 產生的 EncryptFileName。原始檔案內容會儲存在目標檔案中。加密金鑰（一個字串）必須在名為 .ct_config.crypt 的文字檔案中提供，該檔案位於目前目錄或使用者的主目錄中（按此順序搜尋）。
-spec decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok | {error, Reason} when EncryptFileName :: string(), TargetFileName :: string(), KeyOrFile :: {key, string()} | {file, string()}, Reason :: term().
解密先前使用 ct:encrypt_config_file/2,3 產生的 EncryptFileName。原始檔案內容會儲存在目標檔案中。金鑰必須與用於加密的金鑰具有相同的值。
-spec encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Reason} when SrcFileName :: string(), EncryptFileName :: string(), Reason :: term().
使用 DES3 加密來源組態檔案，並將結果儲存在檔案 EncryptFileName 中。金鑰（一個字串）必須在名為 .ct_config.crypt 的文字檔案中提供，該檔案位於目前目錄或使用者的主目錄中（按此順序搜尋）。
如需有關在執行測試時使用加密設定檔的資訊，請參閱使用者指南中的加密設定檔一節。
如需有關 DES3 加密/解密的詳細資訊，請參閱應用程式 Crypto。
-spec encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ok | {error, Reason} when SrcFileName :: string(), EncryptFileName :: string(), KeyOrFile :: {key, string()} | {file, string()}, Reason :: term().
使用 DES3 加密來源組態檔案，並將結果儲存在目標檔案 EncryptFileName 中。要使用的加密金鑰可以是 {key,Key} 中的值，也可以是儲存在 {file,File} 指定檔案中的值。
如需有關在執行測試時使用加密設定檔的資訊，請參閱使用者指南中的加密設定檔一節。
如需有關 DES3 加密/解密的詳細資訊，請參閱應用程式 Crypto。
使用指定的錯誤 Reason 終止測試案例。
使用由格式字串和值列表指定的錯誤訊息終止測試案例（用作 io_lib:format/2 的引數）。
-spec get_config(Required) -> Value when Required :: KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}, KeyOrName :: key_or_name(), SubKey :: atom(), Value :: term().
-spec get_config(Required, Default) -> Value when Required :: KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}, KeyOrName :: key_or_name(), SubKey :: atom(), Default :: term(), Value :: term().
-spec get_config(Required, Default, Opts) -> ValueOrElement when Required :: KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}, KeyOrName :: key_or_name(), SubKey :: atom(), Default :: term(), Opts :: [Opt], Opt :: element | all, ValueOrElement :: term() | Default.
讀取組態資料值。
傳回符合的值或設定元素，前提是給定設定變數鍵或其相關聯的名稱（如果已使用 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。
-spec get_event_mgr_ref() -> EvMgrRef when EvMgrRef :: atom().
取得 Common Test 事件管理員的參考。此參考可用於例如在測試執行時新增使用者特定的事件處理常式。
範例
gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])-spec get_progname() -> string().
傳回用於啟動此 Erlang 執行個體的命令。如果找不到此資訊，則會傳回字串 "no_prog_name"。
-spec get_status() -> TestStatus | {error, Reason} | no_tests_running when TestStatus :: [StatusElem], StatusElem :: {current, TestCaseInfo} | {successful, Successful} | {failed, Failed} | {skipped, Skipped} | {total, Total}, TestCaseInfo :: {Suite, TestCase} | [{Suite, TestCase}], Suite :: atom(), TestCase :: atom(), Successful :: integer(), Failed :: integer(), Skipped :: {UserSkipped, AutoSkipped}, UserSkipped :: integer(), AutoSkipped :: integer(), Total :: integer(), Reason :: term().
傳回正在進行的測試狀態。傳回的列表包含正在執行的測試案例的相關資訊（當平行測試案例群組正在執行時，會是案例列表），以及目前為止成功、失敗、跳過和總測試案例的計數器。
-spec get_target_name(Handle) -> {ok, TargetName} | {error, Reason} when Handle :: handle(), TargetName :: target_name(), Reason :: term().
傳回指定連線所屬的目標名稱。
-spec get_testspec_terms() -> TestSpecTerms | undefined when TestSpecTerms :: [{Tag, Value}], Tag :: atom(), Value :: [term()].
取得用於組態和執行此測試的所有測試規格術語列表。
-spec get_testspec_terms(Tags) -> TestSpecTerms | undefined when Tags :: [Tag] | Tag, Tag :: atom(), TestSpecTerms :: [{Tag, Value}] | {Tag, Value}, Value :: [{Node, term()}] | [term()], Node :: atom().
從用於組態和執行此測試的測試規格中讀取一個或多個術語。Tag 是任何有效的測試規格標籤，例如 label、config 或 logdir。如果設定了選項 allow_user_terms，也可以讀取使用者特定的術語。
所有回傳的值組，除了使用者術語外，第一個元素都是節點名稱。
若要讀取測試術語，請使用 Tag = tests（而不是 suites、groups 或 cases）。Value 則會是 所有 測試的列表，形式為 [{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...]，其中 GroupsAndCases = [{Group,[Case]}] | [Case]。
-spec get_timetrap_info() -> {Time, {Scaling, ScaleVal}} when Time :: integer() | infinity, Scaling :: boolean(), ScaleVal :: integer().
讀取為目前測試案例設定的計時陷阱相關資訊。Scaling 指示 Common Test 是否會嘗試自動補償因執行時間延遲而引入的計時陷阱，例如 cover 等工具。ScaleVal 是目前縮放乘數的值（如果停用縮放，則永遠為 1）。請注意，Time 不是縮放後的結果。
-spec get_verbosity(Category) -> Level | undefined when Category :: default | atom(), Level :: integer().
此函式傳回指定記錄類別的詳細程度。有關詳細資訊，請參閱使用者指南。使用值 default 讀取一般詳細程度。
-spec install(Opts) -> ok | {error, Reason} when Opts :: [Opt], Opt :: {config, ConfigFiles} | {event_handler, Modules} | {decrypt, KeyOrFile}, ConfigFiles :: [ConfigFile], ConfigFile :: string(), Modules :: [atom()], KeyOrFile :: {key, Key} | {file, KeyFile}, Key :: string(), KeyFile :: string(), Reason :: term().
安裝組態檔案和事件處理常式。
在第一個測試之前執行此函數一次。
範例
install([{config,["config_node.ctc","config_user.ctc"]}])此函數會由程式 ct_run 自動執行。
-spec listenv(Telnet) -> {ok, [Env]} | {error, Reason} when Telnet :: ct_telnet:connection(), Env :: {Key, Value}, Key :: string(), Value :: string(), Reason :: term().
在指定的 Telnet 連線上執行命令 listenv，並將結果傳回為鍵值對列表。
-spec log(Format) -> ok when Format :: string().
-spec log(X1, X2, X3, X4) -> ok when X1 :: Category | Importance, X2 :: Importance | Format, X3 :: Format | FormatArgs, X4 :: FormatArgs | Opts, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()} | no_css | esc_chars.
-spec log(Category, Importance, Format, FormatArgs, Opts) -> ok when Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()} | no_css | esc_chars.
從測試案例列印到記錄檔。
此函數旨在將字串直接從測試案例列印到測試案例記錄檔。
預設的 Category 為 default，預設的 Importance 為 ?STD_IMPORTANCE，且 FormatArgs 的預設值為 []。
有關 Category、Importance 和 no_css 選項的詳細資訊，請參閱使用者指南中的「記錄 - 類別和詳細程度」章節。
除非使用 esc_chars 選項，否則 Common Test 不會逸出使用此函數列印的文字中的特殊 HTML 字元（<、> 和 &）。
-spec make_priv_dir() -> ok | {error, Reason} when Reason :: term().
如果測試啟動時選項 create_priv_dir 設定為 manual_per_tc，則為了讓測試案例使用私有目錄，它必須先呼叫此函式來建立私有目錄。
將類型為 Name、資料為 Data 的非同步通知傳送到 Common Test 事件管理員。稍後可以由任何已安裝的事件管理員攔截此通知。
另請參閱 gen_event。
-spec pal(Format) -> ok when Format :: string().
-spec pal(X1, X2, X3, X4) -> ok when X1 :: Category | Importance, X2 :: Importance | Format, X3 :: Format | FormatArgs, X4 :: FormatArgs | Opts, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()} | no_css.
-spec pal(Category, Importance, Format, FormatArgs, Opts) -> ok when Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()} | no_css.
從測試案例列印並記錄。
此函數旨在將字串從測試案例列印到測試案例記錄檔和主控台。
預設的 Category 為 default，預設的 Importance 為 ?STD_IMPORTANCE，且 FormatArgs 的預設值為 []。
有關 Category 和 Importance 的詳細資訊，請參閱使用者指南中的「記錄 - 類別和詳細程度」章節。
請注意，在將文字列印到記錄檔之前，Common Test 會逸出文字中的特殊字元（<、> 和 &）。
-spec parse_table(Data) -> {Heading, Table} when Data :: [string()], Heading :: tuple(), Table :: [tuple()].
解析 SQL 表格的輸出，並傳回元組列表。
要剖析的列印輸出通常是 SQL 中 select 命令的結果。回傳的 Table 是值組的列表，其中每個值組都是表格中的一列。
Heading 是一個字串值組，表示表格中每欄的標題。
-spec print(Format) -> ok when Format :: string().
-spec print(Category, Importance, Format, FormatArgs, Opts) -> ok when Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()}.
從測試案例列印到主控台。
此函數旨在將字串從測試案例列印到主控台。
預設的 Category 為 default，預設的 Importance 為 ?STD_IMPORTANCE，且 FormatArgs 的預設值為 []。
有關 Category 和 Importance 的詳細資訊，請參閱使用者指南中的「記錄 - 類別和詳細程度」章節。
-spec reload_config(Required) -> ValueOrElement | {error, Reason} when Required :: KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}, KeyOrName :: key_or_name(), SubKey :: atom(), ValueOrElement :: term(), Reason :: term().
重新載入包含指定設定鍵的設定檔。
此函數會更新讀取指定組態變數的組態資料，並回傳此變數（可能）的新值。
如果組態中存在某些變數，但未使用此函數載入，則會從組態表移除這些變數及其別名。
-spec remaining_test_procs() -> {TestProcs, SharedGL, OtherGLs} when TestProcs :: [{pid(), GL}], GL :: pid(), SharedGL :: pid(), OtherGLs :: [pid()].
此函式將傳回在此呼叫時仍在執行的測試和群組領導程序的身分。TestProcs 是系統中以 Common Test IO 程序作為群組領導者的程序。SharedGL 是中央 Common Test IO 程序，負責列印到設定函式的記錄檔，並依序執行測試案例。OtherGLs 是 Common Test IO 程序，負責將並行測試案例群組中的測試案例列印到記錄檔。
此函數回傳的程序資訊可用於在測試執行完成後找出並終止剩餘的程序。此函數通常會從 Common Test Hook 函數呼叫。
請注意，執行組態函數或測試案例的程序永遠不會包含在 TestProcs 中。因此，使用後組態 Hook 函數（例如 post_end_per_suite、post_end_per_group、post_end_per_testcase）來終止 TestProcs 中將目前群組領導程序作為其群組領導者的所有程序是安全的。
另請注意，使用者絕對不能終止共用群組領導者 (SharedGL)，只能由 Common Test 終止。但是，平行測試案例群組 (OtherGLs) 的群組領導程序可以在 post_end_per_group Hook 函數中終止。
移除使用指定的 callback 模組和設定字串載入的設定變數（及其別名）。
-spec require(Required) -> ok | {error, Reason} when Required :: Key | {Key, SubKeys} | {Key, SubKey, SubKeys}, Key :: atom(), SubKeys :: SubKey | [SubKey], SubKey :: atom(), Reason :: term().
檢查所需的設定是否可用。可以將任意深度的元組指定為 Required。元組的最後一個元素只能是 SubKey 的列表。
範例 1. 要求變數 myvar
ok = ct:require(myvar).在這種情況下，組態檔必須至少包含
{myvar,Value}.範例 2. 要求具有子索引鍵 sub1 和 sub2 的索引鍵 myvar
ok = ct:require({myvar,[sub1,sub2]}).在這種情況下，組態檔必須至少包含
{myvar,[{sub1,Value},{sub2,Value}]}.範例 3. 要求具有子索引鍵 sub1 且具有 subsub1 的索引鍵 myvar
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。
-spec require(Name, Required) -> ok | {error, Reason} when Name :: atom(), Required :: Key | {Key, SubKey} | {Key, SubKey, SubKey}, SubKey :: Key, Key :: atom(), Reason :: term().
檢查所需的設定是否可用，並給予一個名稱。 Required 的語意與 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。
-spec run(TestDirs) -> Result when TestDirs :: TestDir | [TestDir], TestDir :: string(), Result :: [TestResult] | {error, Reason}, TestResult :: term(), Reason :: term().
執行指定目錄中所有套件中的所有測試案例。
另請參閱 ct:run/3。
-spec run(TestDir, Suite) -> Result when TestDir :: string(), Suite :: atom(), Result :: [TestResult] | {error, Reason}, TestResult :: term(), Reason :: term().
執行指定套件中的所有測試案例。
另請參閱 ct:run/3。
-spec run(TestDir, Suite, Cases) -> Result when TestDir :: string(), Suite :: atom(), Cases :: atom() | [atom()], Result :: [TestResult] | {error, Reason}, TestResult :: term(), Reason :: term().
執行指定的測試案例。
要求先執行 ct:install/1。
套件 (*_SUITE.erl) 檔案必須儲存在 TestDir 或 TestDir/test 中。執行測試時，會編譯所有套件。
-spec run_test(Opts) -> Result when Opts :: [OptTuples], OptTuples :: {dir, TestDirs} | {suite, Suites} | {group, Groups} | {testcase, Cases} | {spec, TestSpecs} | {join_specs, boolean()} | {label, Label} | {config, CfgFiles} | {userconfig, UserConfig} | {allow_user_terms, boolean()} | {logdir, LogDir} | {silent_connections, Conns} | {stylesheet, CSSFile} | {cover, CoverSpecFile} | {cover_stop, boolean()} | {step, StepOpts} | {event_handler, EventHandlers} | {include, InclDirs} | {auto_compile, boolean()} | {abort_if_missing_suites, boolean()} | {create_priv_dir, CreatePrivDir} | {multiply_timetraps, M} | {scale_timetraps, boolean()} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, ForceStop} | {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} | {logopts, LogOpts} | {verbosity, VLevels} | {basic_html, boolean()} | {esc_chars, boolean()} | {keep_logs, KeepSpec} | {ct_hooks, CTHs} | {ct_hooks_order, CTHsOrder} | {enable_builtin_hooks, boolean()} | {release_shell, boolean()}, TestDirs :: [string()] | string(), Suites :: [string()] | [atom()] | string() | atom(), Cases :: [atom()] | atom(), Groups :: GroupNameOrPath | [GroupNameOrPath], GroupNameOrPath :: [atom()] | atom() | all, TestSpecs :: [string()] | string(), Label :: string() | atom(), CfgFiles :: [string()] | string(), UserConfig :: [{CallbackMod, CfgStrings}] | {CallbackMod, CfgStrings}, CallbackMod :: atom(), CfgStrings :: [string()] | string(), LogDir :: string(), Conns :: all | [atom()], CSSFile :: string(), CoverSpecFile :: string(), StepOpts :: [StepOpt], StepOpt :: config | keep_inactive, EventHandlers :: EH | [EH], EH :: atom() | {atom(), InitArgs} | {[atom()], InitArgs}, InitArgs :: [term()], InclDirs :: [string()] | string(), CreatePrivDir :: auto_per_run | auto_per_tc | manual_per_tc, M :: integer(), N :: integer(), DurTime :: HHMMSS, HHMMSS :: string(), StopTime :: YYMoMoDDHHMMSS | HHMMSS, YYMoMoDDHHMMSS :: string(), ForceStop :: skip_rest | boolean(), DecryptKeyOrFile :: {key, DecryptKey} | {file, DecryptFile}, DecryptKey :: string(), DecryptFile :: string(), LogOpts :: [LogOpt], LogOpt :: no_nl | no_src, VLevels :: VLevel | [{Category, VLevel}], VLevel :: integer(), Category :: atom(), KeepSpec :: all | pos_integer(), CTHs :: [CTHModule | {CTHModule, CTHInitArgs}], CTHsOrder :: atom(), CTHModule :: atom(), CTHInitArgs :: term(), Result :: {Ok, Failed, {UserSkipped, AutoSkipped}} | TestRunnerPid | {error, Reason}, Ok :: integer(), Failed :: integer(), UserSkipped :: integer(), AutoSkipped :: integer(), TestRunnerPid :: pid(), Reason :: term().
依照 Opts 中的選項組合指定的執行測試。選項與程式 ct_run 使用的選項相同，請參閱 ct_run 手冊頁中的從命令列執行測試。
在這裡，可以使用 TestDir 指出 Suite 的路徑。選項 testcase 對應於程式 ct_run 中的選項 -case。在 Opts 中指定的組態檔會在啟動時自動安裝。
如果 release_shell == true，則會回傳 TestRunnerPid。如需詳細資訊，請參閱 ct:break/1。
Reason 指示遇到的錯誤類型。
-spec run_testspec(TestSpec) -> Result when TestSpec :: [term()], Result :: {Ok, Failed, {UserSkipped, AutoSkipped}} | {error, Reason}, Ok :: integer(), Failed :: integer(), UserSkipped :: integer(), AutoSkipped :: integer(), Reason :: term().
執行由 TestSpec 指定的測試。使用的詞彙與測試規格檔案中的相同。
Reason 指示遇到的錯誤類型。
使用此函式設定或修改記錄類別的詳細程度。詳細資訊請參閱使用者指南。使用值 default 設定一般詳細程度。
-spec sleep(Time) -> ok when Time :: {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity, Hours :: integer(), Mins :: integer(), Secs :: integer(), Millisecs :: integer() | float().
此函式與 STDLIB 中的 timer:sleep/1 類似，會將測試案例暫停指定的時間。但是，如果設定了 multiply_timetraps 值，此函式也會將 Time 乘以該值，並且在某些情況下，如果將 scale_timetraps 設定為 true（預設為 false），也會自動縮放時間。
-spec start_interactive() -> ok.
以互動模式啟動 Common Test。
在此模式下，所有測試案例支援函數都可以直接從 Erlang Shell 執行。互動模式也可以從作業系統命令列使用 ct_run -shell [-config File...] 啟動。
如果要從 Erlang Shell 呼叫任何使用「所需組態資料」的函數（例如，Telnet 或 FTP），則必須先使用 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 ...",...]}-spec step(TestDir, Suite, Case) -> Result when TestDir :: string(), Suite :: atom(), Case :: atom(), Result :: term().
使用偵錯工具逐步執行測試案例。
另請參閱 ct:run/3。
-spec step(TestDir, Suite, Case, Opts) -> Result when TestDir :: string(), Suite :: atom(), Case :: atom(), Opts :: [Opt], Opt :: config | keep_inactive, Result :: term().
使用偵錯工具逐步執行測試案例。如果指定了選項 config，也會在 Suite 中的設定函式上設定中斷點。
另請參閱 ct:run/3。
-spec stop_interactive() -> ok.
結束互動模式。
另請參閱 ct:start_interactive/0。
將 Name 類型的同步通知與 Data 傳送至 Common Test 事件管理員。稍後可以由任何已安裝的事件管理員攔截。
另請參閱 gen_event。
-spec testcases(TestDir, Suite) -> Testcases | {error, Reason} when TestDir :: string(), Suite :: atom(), Testcases :: list(), Reason :: term().
傳回指定套件中的所有測試案例。
-spec timetrap(Time) -> infinity | pid() when Time :: {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity | Func, Hours :: integer(), Mins :: integer(), Secs :: integer(), Millisecs :: integer(), Func :: {M, F, A} | function(), M :: atom(), F :: atom(), A :: list().
為正在執行的測試案例設定新的時間陷阱。
如果引數為 Func，則當此函數回傳時會觸發時間陷阱。Func 也可以回傳新的 Time 值，在這種情況下，這個值是新時間陷阱的值。
-spec userdata(TestDir, Suite) -> SuiteUserData | {error, Reason} when TestDir :: string(), Suite :: atom(), SuiteUserData :: [term()], Reason :: term().
傳回從 suite/0 傳回的元組列表中，以標籤 userdata 指定的任何資料。
-spec userdata(TestDir, Suite, Case :: GroupOrCase) -> TCUserData | {error, Reason} when TestDir :: string(), Suite :: atom(), GroupOrCase :: {group, GroupName} | atom(), GroupName :: atom(), TCUserData :: [term()], Reason :: term().
傳回從 Suite:group(GroupName) 或 Suite:Case() 傳回的元組列表中，以標籤 userdata 指定的任何資料。