ct_master(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💅 <pink>ct_master</pink> — Erlang Module Definition, section 3 🎀

okay so bestie, welcome to ct_master(3) from the Erlang Module Definition manuals. this is the whole page, no cap, every last flag and type kept safe and sound. grab a 🍓 bubbly water and let's go.

✨ NAME ✨

ct_master — Distributed test execution control for Common Test. 🌈

🌸 DESCRIPTION 🌸

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

(translation: it's the girl who coordinates the whole group chat across several hosts at once, all in parallel, no drama. 💅)

🦋 DATA TYPES 🦋

💜 test_spec()

test_spec() :: file:name_all().

Filename of test spec to be executed. literally just the name of the test spec file you wanna run. 🎀

🔥 FUNCTIONS 🔥

💖 abort()

abort() -> ok.

Stops all running tests. all of them. every single one. she said we're done here. 💀

💖 abort(Nodes)

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

Stops tests on specified nodes. just the ones you name — one node, or a whole list of them. choose your fighters bestie. 💅

💖 basic_html(Bool)

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.

(it's giving no makeup, no filter — just raw HTML, none of that CSS glow-up. 🧚)

💖 get_event_mgr_ref()

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, [])

you can slide into the event manager's DMs mid-test and add your own handler. iconic. 🫶

💖 progress()

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.

(so if you see ongoing, she's still cooking — do not disturb. 🔥)

💖 run(TestSpecs)

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.

the chill shortcut version. hand her the specs, she handles the rest. ✨

💖 run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes)

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.

so: each spec does its own thing unless you hand over a list of specs to be merged into one before anything runs — and any test that doesn't say which node it wants still goes out to everything in InclNodes. whatever's in ExclNodes gets left on read. 🙈

💖 run_on_node(TestSpecs, AllowUserTerms, Node)

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.

(one node. one mission. main character energy. 👑)

💖 run_test(Node, Opts)

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

the whole entire options buffet, right there in one OptTuples list. everything above is verbatim, so don't let anyone tell you a flag got lost in the group chat. 💅 she's passing it all straight through to ct:run_test/1. 🦋

bestie reminder: everything literal here is exact. don't retype atoms from memory, copy them, fr fr. 😭

mwah 💖 this little masterpiece was served to you by Ericsson AB, common_test version 1.31.1 ct_master(3). that's the source, that's the version, that's the whole vibe. slay, go spawn some nodes 🎀✨🦋💜

📦 where this page comes from