Search documentation of common_test

# ct_master (common_test v1.30)

Copy Markdown View Source

Distributed test execution control for `Common Test`.

This module exports functions for running `Common Test` nodes on multiple hosts in parallel.

## Summary

### Types

test_spec()

Filename of test spec to be executed.

### Functions

abort()

Stops all running tests.

abort(Nodes)

Stops tests on specified nodes.

basic_html(Bool)

If set to `true`, the `ct_master logs` are written on a primitive HTML format, not using the `Common Test` CSS style sheet.

get_event_mgr_ref()

Gets a reference to the `Common Test` master event manager. The reference can be used to, for example, add a user-specific event handler while tests are running.

progress()

Returns test progress. If `Status` is `ongoing`, tests are running on the node and are not yet finished.

run(TestSpecs)

Run tests on spawned nodes as specified in `TestSpecs` (see `run/4`).

run(TestSpecs, InclNodes, ExclNodes)

Equivalent to `run(TestSpecs, false, InclNodes, ExclNodes)`.

run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes)

Tests are spawned on the nodes as specified in `TestSpecs`. Each specification in `TestSpec` is handled separately. However, it is also possible to specify a list of specifications to be merged into one specification before the tests are executed. Any test without a particular node specification is also executed on the nodes in `InclNodes`. Nodes in the `ExclNodes` list are excluded from the test.

run_on_node(TestSpecs, Node)

Equivalent to `run_on_node(TestSpecs, false, Node)`.

run_on_node(TestSpecs, AllowUserTerms, Node)

Tests are spawned on `Node` according to `TestSpecs`.

run_test(Node, Opts)

Tests are spawned on `Node` using `ct:run_test/1`

## Types

# test_spec()

    -type test_spec() :: file:name_all().

Filename of test spec to be executed.

## Functions

# abort()

    -spec abort() -> ok.

Stops all running tests.

# abort(Nodes)

    -spec abort(Nodes) -> ok when Nodes :: Node | [Node], Node :: node().

Stops tests on specified nodes.

# basic_html(Bool)

(since OTP R15B01)

    -spec basic_html(Bool) -> ok when Bool :: boolean().

If set to `true`, the `ct_master logs` are written on a primitive HTML format, not using the `Common Test` CSS style sheet.

# get_event_mgr_ref()

(since OTP 17.5)

    -spec get_event_mgr_ref() -> atom().

Gets a reference to the `Common Test` master event manager. The reference can be used to, for example, add a user-specific event handler while tests are running.

Example:

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

# progress()

    -spec progress() -> [{Node, Status}] when Node :: node(), Status :: atom().

Returns test progress. If `Status` is `ongoing`, tests are running on the node and are not yet finished.

# run(TestSpecs)

    -spec run(TestSpecs) -> [{Specs, ok} | {error, Reason}]
                 when
                     TestSpecs :: TestSpec | [TestSpec] | [[TestSpec]],
                     TestSpec :: test_spec(),
                     Specs :: [file:filename_all()],
                     Reason :: term().

Run tests on spawned nodes as specified in `TestSpecs` (see `run/4`).

Equivalent to `run(TestSpecs, false, [], [])` if called with TestSpecs being list of strings;

Equivalent to `run([TS], false, [], [])` if called with TS being string.

# run(TestSpecs, InclNodes, ExclNodes)

    -spec run(TestSpecs, InclNodes, ExclNodes) -> [{Specs, ok} | {error, Reason}]
                 when
                     TestSpecs :: TestSpec | [TestSpec] | [[TestSpec]],
                     TestSpec :: test_spec(),
                     InclNodes :: [node()],
                     ExclNodes :: [node()],
                     Specs :: [file:filename_all()],
                     Reason :: term().

Equivalent to `run(TestSpecs, false, InclNodes, ExclNodes)`.

# run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes)

    -spec run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes) -> [{Specs, ok} | {error, Reason}]
                 when
                     TestSpecs :: TestSpec | [TestSpec] | [[TestSpec]],
                     TestSpec :: test_spec(),
                     AllowUserTerms :: boolean(),
                     InclNodes :: [node()],
                     ExclNodes :: [node()],
                     Specs :: [file:filename_all()],
                     Reason :: term().

Tests are spawned on the nodes as specified in `TestSpecs`. Each specification in `TestSpec` is handled separately. However, it is also possible to specify a list of specifications to be merged into one specification before the tests are executed. Any test without a particular node specification is also executed on the nodes in `InclNodes`. Nodes in the `ExclNodes` list are excluded from the test.

# run_on_node(TestSpecs, Node)

    -spec run_on_node(TestSpecs, Node) -> [{Specs, ok} | {error, Reason}]
                         when
                             TestSpecs :: TestSpec | [TestSpec] | [[TestSpec]],
                             TestSpec :: test_spec(),
                             Node :: node(),
                             Specs :: [file:filename_all()],
                             Reason :: term().

Equivalent to `run_on_node(TestSpecs, false, Node)`.

# run_on_node(TestSpecs, AllowUserTerms, Node)

    -spec run_on_node(TestSpecs, AllowUserTerms, Node) -> [{Specs, ok} | {error, Reason}]
                         when
                             TestSpecs :: TestSpec | [TestSpec] | [[TestSpec]],
                             TestSpec :: test_spec(),
                             AllowUserTerms :: boolean(),
                             Node :: node(),
                             Specs :: [file:filename_all()],
                             Reason :: term().

Tests are spawned on `Node` according to `TestSpecs`.

# run_test(Node, Opts)

    -spec run_test(Node, Opts) -> ok
                      when
                          Node :: node(),
                          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().

Tests are spawned on `Node` using `ct:run_test/1`