Skip to content
Tim Watson edited this page Jul 17, 2012 · 5 revisions

There are three primary types of configuration data in SysTest, each of which is supplied as using an Erlang Term based format that can be read by file:consult/1.

Terminology

We use the term configuration element (or just element) to describe a tagged tuple stored in a configuration file. Consider the following configuration:

{name, "Tom"}.
{age, 61}.
{roles, [{person, active}, {employee, inactive}]}.

In this configuration (above), the top level entries name, age, roles are all configuration elements, but the person, employee tuples are usually referred to as sub-elements for clarity.

Configuration Types

The following table outlines the various configuration options available to SysTest users.

Configuration Contains Default Search Path Required File Extension

Settings

Arbitrary user config data

configurable

.settings

Resources

Resource definitions (see below)

./resources/*.resource

None (supports glob pattern)

Profiles

Profile definitions

./profiles/*.profile

.profile

Settings

Settings are the most basic form of configuration that SysTest handles, and are simply a means to externalise certain data you wish to make use of in your tests. There is no special format for this data, nor are there any allowed (or disallowed) elements.

Settings are sourced from ./resources/default.settings initially, if it exists. Then the base directory is searched (recursively) for a file whose name matches the pattern ./%{USER}.settings, where USER contains the content of the USER environment variable. These two files are then merged, with the configuration elements from the latter file overwriting those from the default.

Settings can be extracted at runtime using the [[Configuration API|systest_config]], or accessed in and used in string-expressions by referencing the settings group. For example:

{web_auth_url, "${settings.base_url}/login.html"}.

Resource Configuration Files

These configuration files define the various Resources that can be made to participate in a test run. For more information about Resources in general, see the [[Concepts/Overview|concepts]] page.

Resources Configuration Files are sources from ./resources/*.resource by default, though like most config locations, this can be overridden by the current Profile (more on this later).

Each top level configuration element in a Resources Configuration File is accessible using the [[Configuration API|systest_config]]. SysTest uses these elements to resolve resources automatically and associate then with Test Scopes at runtime - see [[Concepts/Overview|concepts]] for more information about Test Scopes.

Each configuration element can describe either a Process or a SUT (see [[Concepts/Overview|concepts]]) - it may also contain trace hooks, but we’ll revisit those later on.

Process Configuration

The Process configuration contains quite a bit of nested data, so an example should serve best to explain how it’s put together:

{basic_node, [ {startup, [{handler, systest_slave}]} ]}.

In this basic configuration, we’ve given the Process a name basic_node, and provided the minimal information SysTest needs to start up an instance of this process when a test scope or SUT requires it. The handler element is mandatory, and specifies the kind of process handler we wish to use for instances of this type. See [[Concepts/Overview|concepts]] for more information about process handlers.

The [[systest_slave|systest_slave]] handler deals with starting slave (Erlang) nodes, and it can be configured to pass startup arguments to the erl program it is starting. For this we use the flags.start elements, which are provided as a string and can contain string-expressions:

{basic_node, [
    {startup, [{handler, systest_slave}]},
    {flags, [
        {start, "-boot start_sasl +W w "
                "+K true +A30 +P 1048576 "
                "-pa ebin "
                "-sasl sasl_error_logger ${settings.errlog_on_off}"}
    ]}
]}.

The [[systest_slave|systest_slave]] handler doesn’t use flags.stop elements, though it is not an error to supply them (they’re simply ignored).

Some handlers provide more complex startup options, the most common of which is [[systest_cli|systest_cli]]. As with the slave handler, we configure a Process resource to use this by settings the {handler, systest_cli} option sub element in the startup configuration section.

SUT Configuration

The SUT configuration can contain any of the sub elements outlined in the following table.

SUT Sub-Element Description Example Mandatory?

sut

List of process names (by host)

{sut, [{localhost, [a, b]}]}

Yes

processes

Process stereotypes

{processes, [{a, [my_proc]}]}

Yes (ALL)

Processes residing on localhost should always use the atom localhost, whilst other host names can be specified using a string. The Processes in a SUT configuration must specify their stereotypes - the Process definitions which should be applied to them.

Trace Debugging Configuration

Earlier on we said that each top level configuration element in a Resources Configuration File could describe either a Process or a SUT, or a set of trace hooks. These require a basic understand of the dbg module’s interface, and essentially tie test scopes to trace configurations, which set up a tracer process for the duration of the specified scope.

NB: Trace/Debug Support is EXPERIMENTAL

{debug, [
    {trace_setup, [
        %% {trace_method, [ct, pal, ["TRACE: ~p~n"]]},
        {trace_type, port}, %% port | process
        %% {port_kind, ip}, %% ip | file, ignored in trace_type process
        {port_kind, file},
        %% {trace_port, 4711} %% only used in 'ip' trace mode
        %% {trace_port, {"node1", 4711}}
        {filename, "/tmp/systest-test-trace.log"}
    ]},
    {test_cases, [{a_specific_test_case,      trace_config},
                  {systest_supervision_SUITE, trace_proc_start}]},
    {trace_targets, [
        {trace_config, [
            {mod, systest_config},
            {match_spec, [{'_',[],[{exception_trace},
                                   {message,{process_dump}}]}]},
            {function, '_'},
            {pflags, [c, return_to]}
        ]},
        {trace_proc_start, [
            {mod, systest_proc},
            {match_spec, [{'_', [], [{exception_trace},
                                     {message, {process_dump}}]}]},
            {pflags, [c, return_to]}
        ]}
    ]}
]}.

Profiles

Profiles, also called test profiles in this guide, provide a mechanism to control the SysTest runtime environment. Each element that the profile can contain is optional and unrecognised elements are ignored. When an element is not given in a profile, its default value is used instead.

Element Description Controls Default

framework

The testing framework (module) to use

Test Execution

systest_ct

output_dir

Directory for generated artefacts

Logging, coverage reports

see Temporary Files below

log_dir

Base directory for all log files

Logging

"{output_dir}/logs"

settings_base

Default/Base Settings file

Settings

"./resources/default.settings"

resources

List of paths or glob patterns used to find Resources.

Resources

[./resources/\*.resource]

targets

Paths to directories containing beam code, or module names

Test Execution

["ebin"]

specifications

Test Specification File

Common Test (only)

[]

hooks

Testing Framework Hooks

Testing Framework(s)

See Framework Configuration

You select a profile when running SysTest by passing -P <profile name> on the command line. For more details, see the [[Interfaces Documentation|interfaces]].

Clone this wiki locally