configuration

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. Where complex nested structures are used, we also tend to refer to sub-elements as configuration sections, reflecting their use as containers for other sub-elements.

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

Configurations are normally grouped by the [[SysTest Config Server|systest_config]] and we refer to these groupings as a configuration set. This name reflects the fact that each configuration element’s key can occur only once.

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, or accessed in and used in string-expressions by referencing the settings group. For example:

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

The Settings configuration set also hosts a number of elements which are added by the testing framework dynamically. See the System Values section below for more details.

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 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 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 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. 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.