Introduction

Moler is a Python library that provides building blocks for automated tests of networked systems and devices.

Moler is an open-source Python library developed by Nokia for building automated tests. It provides well-defined, composable “bricks” — each with a clearly scoped responsibility and consistent API — that you assemble into test scripts for terminals, networked devices, and distributed systems.

Core building blocks

Every Moler component follows the same construction pattern, so adding new ones is straightforward.

Commands as self-reliant objects A command encapsulates both triggering an action on a device and parsing the resulting output. The caller does not need to know how the command is sent, how output is received, or how it is parsed — only how to start it and retrieve its result.

Event observers and callbacks Event observers watch a connection for asynchronous data (alarms, unexpected reboots, prompts) and fire callbacks when that data appears. This enables online reaction rather than offline post-processing of logs.

Background execution Commands and observers can run in the background while other work proceeds in the foreground. This makes it straightforward to run multiple operations in parallel and handle unexpected system behavior without blocking.

State machine devices Devices are modeled as state machines. State transitions — such as opening an SSH connection to reach a remote shell — are defined in configuration, not in test code. The test script says goto_state("UNIX_REMOTE"); the configuration describes how to get there. This separates test logic from infrastructure topology.

Automatic connection logging Moler automatically logs all data flowing through every device connection. A high-level moler.log records command activity across all devices. Per-device logs (e.g., moler.RebexTestMachine.log) record the raw bytes sent and received. Logs can be rotated by size or time and compressed automatically.

Command as future

Moler’s central design idea is the Command as Future. A command object is both:

• A function-like object that actively triggers an action on a device by sending a command string over a connection, then parses the output.
• A future-like object that stores the result of that parsing and exposes APIs to check completion, retrieve results, and handle errors.

This is different from concurrent.futures and asyncio, where an external executor or event loop starts the callable. In Moler, the command is self-executable:

# Run synchronously — behaves like a function call
result = command()

# Run in the background — behaves like a future
command.start()
# ... do other work ...
result = command.await_done(timeout=30)

The timeout parameter on await_done is required. Commands are not expected to run forever — the caller must specify the worst-case wait time.

A motivating example

Find all Python processes running on a local machine:

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

load_config(config='my_devices.yml')                    # load device definitions
my_unix = DeviceFactory.get_device(name='MyMachine')    # get a device by name
ps_cmd = my_unix.get_cmd(cmd_name="ps",                 # get a command from the device
                         cmd_params={"options": "-ef"})

processes_info = ps_cmd()                               # run it; returns parsed result
for proc_info in processes_info:
    if 'python' in proc_info['CMD']:
        print("PID: {info[PID]} CMD: {info[CMD]}".format(info=proc_info))

PID: 1817 CMD: /usr/bin/python /usr/share/system-config-printer/applet.py
PID: 21825 CMD: /usr/bin/python /home/gl/moler/examples/command/unix_ps.py

The command returns a list of dicts — no string parsing in your test code.

Reuse freedom

Moler is designed for incremental adoption. You can use as much or as little as you need:

• Use YAML configuration files, or configure entirely from Python dicts.
• Use high-level DeviceFactory, or create command objects directly with a connection.
• Use the provided connection types, or supply your own.

Quickstart

Get a working script running in minutes.

Installation

Install Moler and review system requirements.