Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nokia/moler/llms.txt

Use this file to discover all available pages before exploring further.

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. 
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.
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:
ClassDescription
moler.device.unixlocal.UnixLocalLocal Unix shell (opens a terminal)
moler.device.unixremote.UnixRemoteRemote 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

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
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
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
Defines which devices are neighbours of each other. Moler uses this to route multi-hop state transitions automatically.
DEVICES:
  LOGICAL_TOPOLOGY:
    MyMachine:
      - RebexTestMachine
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us