Linux Certif

Toute la documentation sur la certification Linux LPI

ct

MODULE

ct - Main user interface for the Common Test framework.

DESCRIPTION

Main user interface for the Common Test framework.

This module implements the command line interface for running tests and some basic functions for common test case issues such as configuration and logging.

Test Suite Support Macros

The config macro is defined in ct.hrl. This macro should be used to retrieve information from the Config variable sent to all test cases. It is used with two arguments, where the first is the name of the configuration variable you wish to retrieve, and the second is the Config variable supplied to the test case.

Possible configuration variables include:

*

data_dir - Data file directory.

*

priv_dir - Scratch file directory.

*

Whatever added by init_per_suite/1 or init_per_testcase/2 in the test suite.

DATA TYPES

handle() = handle() (see module ct_gen_conn) | term():

The identity of a specific connection.

target_name() = var_name():

The name of a target.

var_name() = atom():

A variable name which is specified when ct:require/2 is called, e.g. ct:require(mynodename, {node, [telnet]})

EXPORTS

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

Types

Reason = term()

When calling this function, the currently executing test case will be aborted. It is the user's responsibility to know for sure which test case is currently executing. The function is therefore only safe to call from a function which has been called (or synchronously invoked) by the test case.
Reason, the reason for aborting the test case, is printed in the test case log.

comment(Comment) -> void()

Types

Comment = term()

Print the given Comment in the comment field of the table on the test suite result page.
If called several times, only the last comment is printed. comment/1 is also overwritten by the return value {comment, Comment} or by the function fail/1 (which prints Reason as a comment).

fail(Reason) -> void()

Types

Reason = term()

Terminate a test case with the given error Reason.

get_config(Required) -> Value

Equivalent to get_config(Required, undefined).

get_config(Required, Default) -> Value

Types

Required = KeyOrName | {KeyOrName, SubKey}
KeyOrName = atom()
SubKey = atom()
Default = term()
Value = term() | Default

Get the value of config data.
This function returns the value of the requested config element.
Example, given the following config file:

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

get_config(unix, Default) -> [{telnet, IpAddr}, {username, Username}, {password, Password}]

 get_config({unix, telnet}, Default) -> IpAddr

 get_config({unix, ftp}, Default) -> Default

 get_config(unknownkey, Default) -> Default

If you want to access a config variable which has been given a name by require/2, the name must be used instead of the key when reading the value:

require(myhost, unix) -> ok

 get_config(myhost, Default) -> [{telnet, IpAddr}, {username, Username}, {password, Password}]

See also: get_config/1, require/1, require/2.

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

Types

TestDir = term()
Reason = term()

Returns status of ongoing tests.

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

Types

Handle = handle()
TargetName = target_name()

Return the name of the target that the given connection belongs to.

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

Types

Opts = [Opt]
Opt = {config, ConfigFiles} | {event_handler, Modules}
ConfigFiles = [ConfigFile]
ConfigFile = string()
Modules = [atom()]

Install config files and event handlers.
Run this function once before first test.
Example:

 install([{config, ["config_node.ctc", "config_user.ctc"]}]).
Note that this function is automatically run by the run_test script.

listenv(Telnet) -> [Env]

Types

Telnet = term()
Env = {Key, Value}
Key = string()
Value = string()

Performs the listenv command on the given telnet connection and returns the result as a list of Key-Value pairs.

log(Format) -> ok

Equivalent to log(default, Format, []).

log(X1, X2) -> ok

Types

X1 = Category | Format
X2 = Format | Args

Equivalent to log(Category, Format, Args).

log(Category, Format, Args) -> ok

Types

Category = atom()
Format = string()
Args = list()

Printout from a testcase to the log.
This function is meant for printing stuff directly from a testcase (i.e. not from within the CT framework) in the test log.
Default Category is default and default Args is [].

pal(Format) -> ok

Equivalent to pal(default, Format, []).

pal(X1, X2) -> ok

Types

X1 = Category | Format
X2 = Format | Args

Equivalent to pal(Category, Format, Args).

pal(Category, Format, Args) -> ok

Types

Category = atom()
Format = string()
Args = list()

Print and log from a testcase.
This function is meant for printing stuff from a testcase both in the log and on the console.
Default Category is default and default Args is [].

parse_table(Data) -> {Heading, Table}

Types

Data = [string()]
Heading = tuple()
Table = [tuple()]

Parse the printout from an SQL table and return a list of tuples.
The printout to parse would typically be the result of a select command in SQL. The returned Table is a list of tuples, where each tuple is a row in the table.
Heading is a tuple of strings representing the headings of each column in the table.

print(Format) -> ok

Equivalent to print(default, Format, []).

print(X1, X2) -> term()

Equivalent to print(Category, Format, Args).

print(Category, Format, Args) -> ok

Types

Category = atom()
Format = string()
Args = list()

Printout from a testcase to the console.
This function is meant for printing stuff from a testcase on the console.
Default Category is default and default Args is [].

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

Types

Required = Key | {Key, SubKeys}
Key = atom()
SubKeys = SubKey | [SubKey]
SubKey = atom()

Check if the required configuration is available.
Example: require the variable myvar:

 ok = ct:require(myvar)
In this case the config file must at least contain:

    {myvar,Value}.
 

Example: require the variable myvar with subvariable sub1:

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

In this case the config file must at least contain:

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

See also: get_config/1, get_config/2, require/2.

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

Types

Name = atom()
Required = Key | {Key, SubKeys}
Key = atom()
SubKeys = SubKey | [SubKey]
SubKey = atom()

Check if the required configuration is available, and give it a name.
If the requested data is available, the main entry will be marked as allocated. An allocated element can only be used if the correct name is given. This means that to read the value of the element with get_config/1, 2, you need to provide the Name instead of the Key.
Example: Require one node with a telnet connection and an ftp connection. Name the node a:

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

 All references to this node must then use the node name. E.g. you can fetch a file over ftp like this:

 ok = ct:ftp_get(a, RemoteFile, LocalFile).
For this to work, the config file must at least contain:

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

See also: get_config/1, get_config/2, require/1.

run(TestDirs) -> Result

Types

TestDirs = TestDir | [TestDir]

Run all testcases in all suites in the given directories.
See also: run/3.

run(TestDir, Suite) -> Result

Run all testcases in the given suite.
See also: run/3.

run(TestDir, Suite, Cases) -> Result

Types

TestDir = string()
Suite = atom()
Cases = atom() | [atom()]
Result = [TestResult] | {error, Reason}

Run the given testcase(s).
Requires that ct:install/1 has been run first.
Suites (*_SUITE.erl) files must be stored in TestDir or TestDir/test. All suites will be compiled when test is run.

run_test(Opts) -> Result

Types

Opts = [OptTuples]
OptTuples = {config, CfgFiles} | {dir, TestDirs} | {suite, Suites} | {testcase, Cases} | {'spec', TestSpecs} | {allow_user_terms, Bool} | {logdir, LogDir} | {silent_connections, Conns} | {cover, CoverSpecFile} | {event_handler, EventHandlers} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, Bool}
CfgFiles = [string()] | string()
TestDirs = [string()] | string()
Suites = [string()] | string()
Cases = [atom()] | atom()
TestSpecs = [string()] | string()
LogDir = string()
EventHandlers = EH | [EH]
EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
InitArgs = [term()]
Conns = all | [atom()]
CoverSpecFile = string()
N = integer()
DurTime = string(HHMMSS)
StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)
Result = [TestResult] | {error, Reason}

Run tests as specified by the combination of options in Opts. The options are the same as those used with the run_test script. Note that here a TestDir can be used to point out the path to a Suite. Note also that the option testcase corresponds to the -case option in the run_test script. Configuration files specified in Opts will be installed automatically at startup.

run_testspec(TestSpec) -> Result

Types

TestSpec = [term()]

Run test specified by TestSpec. The terms are the same as those used in test specification files.

start_interactive() -> ok

Start CT in interactive mode.
From this mode all test case support functions can be executed directly from the erlang shell. The interactive mode can also be started from the unix command line with run_test -shell [-config File...].
If any functions using "required config data" (e.g. telnet or ftp functions) are to be called from the erlang shell, config data must first be required with ct:require/2.
Example:

 > ct:require(a, {unix, [telnet]}).
ok

 > ct:cmd(a, "ls").

 {ok, ["ls", "file1 ...", ...]}

step(TestDir, Suite, Case) -> Result

Types

Case = atom()

Step through a test case with the debugger.
See also: run/3.

stop_interactive() -> ok

Exit the interactive mode.
See also: start_interactive/0.

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

Types

TestDir = string()
Suite = atom()
Testcases = list()
Reason = term()

Returns all testcases in the specified suite.

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

Types

TestDir = string()
Suite = atom()
SuiteUserData = [term()]
Reason = term()

Returns any data specified with the tag userdata in the list of tuples returned from Suite:suite/0.

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

Types

TestDir = string()
Suite = atom()
Case = atom()
TCUserData = [term()]
Reason = term()

Returns any data specified with the tag userdata in the list of tuples returned from Suite:Case/0.