Configuration file

Structure and usage of Moler’s YAML configuration file, including devices, connections, and logger sections.

Moler can be configured via a YAML file or an inline Python dictionary. The configuration file defines the devices available to your test code, the connections used to reach them, and logging settings.

Loading configuration

Use load_config from moler.config to apply your configuration before accessing any devices.

YAML file

from moler.config import load_config

load_config(config='/absolute/path/to/my_devices.yml')

load_config requires an absolute path when loading from a file. Relative paths raise a MolerException.

Inline dict

from moler.config import load_config

load_config(config={
    'DEVICES': {
        'MyMachine': {
            'DEVICE_CLASS': 'moler.device.unixlocal.UnixLocal'
        }
    }
})

Environment variable

import os
from moler.config import load_config

# Set MOLER_CONFIG=/absolute/path/to/my_devices.yml in your environment
load_config(from_env_var='MOLER_CONFIG')

load_config accepts either config or from_env_var, but not both. Passing both causes config to take precedence.

Full configuration structure

A complete YAML configuration file has three top-level sections:

LOGGER:
  PATH: ./logs
  DATE_FORMAT: "%H:%M:%S"

DEVICES:
  DEFAULT_CONNECTION:
    CONNECTION_DESC:
      io_type: terminal
      variant: threaded

  MyMachine:
    DEVICE_CLASS: moler.device.unixlocal.UnixLocal

  RebexTestMachine:
    DEVICE_CLASS: moler.device.unixremote.UnixRemote
    CONNECTION_HOPS:
      UNIX_LOCAL:
        UNIX_REMOTE:
          execute_command: ssh
          command_params:
            expected_prompt: demo@
            host: test.rebex.net
            login: demo
            password: password
            set_timeout: False

NAMED_CONNECTIONS:
  net_1:
    io_type: tcp
    host: localhost
    port: 5671

IO_TYPES:
  default_variant:
    tcp: threaded

DEVICES section

Each key under DEVICES becomes the name used to retrieve a device via DeviceFactory.get_device(name=...). The only required field per device is DEVICE_CLASS.

DEVICE_CLASS

Fully qualified Python class path for the device implementation.

DEVICES:
  MyMachine:
    DEVICE_CLASS: moler.device.unixlocal.UnixLocal

Common built-in device classes:

Class	Description
moler.device.unixlocal.UnixLocal	Local Unix shell (opens a terminal)
moler.device.unixremote.UnixRemote	Remote Unix shell reached via SSH hops

CONNECTION_HOPS

CONNECTION_HOPS describes the state machine transitions that move a device between states. Each entry maps FROM_STATE → TO_STATE → command + params.

DEVICES:
  RebexTestMachine:
    DEVICE_CLASS: moler.device.unixremote.UnixRemote
    CONNECTION_HOPS:
      UNIX_LOCAL:              # from state
        UNIX_REMOTE:           # to state
          execute_command: ssh # command used to transition
          command_params:
              expected_prompt: demo@
            host: test.rebex.net
            login: demo
            password: password
            set_timeout: None       # remote doesn't support: export TMOUT

The client code never needs to know which command achieves a transition — it just calls device.goto_state(state="UNIX_REMOTE").

DEFAULT_CONNECTION

Sets the connection type and variant used for all devices that do not specify their own CONNECTION_DESC. If omitted, the default is terminal/threaded.

DEVICES:
  DEFAULT_CONNECTION:
    CONNECTION_DESC:
      io_type: terminal
      variant: threaded

Optional device fields

INITIAL_STATE

Sets the state the device enters after creation. If not specified the device starts in its class default initial state.

DEVICES:
  MyMachine:
    DEVICE_CLASS: moler.device.unixlocal.UnixLocal
    INITIAL_STATE: UNIX_LOCAL

LAZY_CMDS_EVENTS

When True, commands and events are loaded on first use rather than at device creation time. Useful for large test suites to reduce startup overhead.

DEVICES:
  MyMachine:
    DEVICE_CLASS: moler.device.unixlocal.UnixLocal
    LAZY_CMDS_EVENTS: True

CLONED_FROM

Creates a device that is a copy of another already-defined device. The cloned device shares the same class and connection hops.

DEVICES:
  MyMachineCopy:
    CLONED_FROM: MyMachine

LOGICAL_TOPOLOGY

Defines which devices are neighbours of each other. Moler uses this to route multi-hop state transitions automatically.

DEVICES:
  LOGICAL_TOPOLOGY:
    MyMachine:
      - RebexTestMachine

CREATE_AT_STARTUP

When True, all defined devices are instantiated and connected immediately when load_config is called, rather than lazily on first access.

DEVICES:
  CREATE_AT_STARTUP: True
  MyMachine:
    DEVICE_CLASS: moler.device.unixlocal.UnixLocal

Using devices after loading config

from moler.config import load_config
from moler.device import DeviceFactory

load_config(config='/absolute/path/to/my_devices.yml')

# Retrieve a device by the name defined in DEVICES
my_unix = DeviceFactory.get_device(name='MyMachine')

# Retrieve a remote device and transition to the remote state
remote = DeviceFactory.get_device(name='RebexTestMachine')
remote.goto_state(state='UNIX_REMOTE')

# Run a command
ls_cmd = remote.get_cmd(cmd_name='ls', cmd_params={'options': '-l'})
result = ls_cmd()

load_config API

from moler.config import load_config

load_config(
    config=None,         # str (absolute path) or dict — mutually exclusive with from_env_var
    from_env_var=None,   # str — name of env var containing the absolute file path
)

Behaviour:

• Calling load_config more than once with the same config is a no-op unless devices were deleted in between.
• Calling it with a new config adds devices from the new config on top of the existing ones.
• Calling moler.config.clear() resets all loaded configuration.