product: maestro audience: test-developer, operator, ai-assistant authority: normative

Maestro Core Concepts

This file defines the vocabulary used throughout Maestro. Every term used in the UI, YAML definitions, database schema, and SDK maps to a concept defined here.

What Is Maestro?

Accordion Maestro is a test automation platform for running, monitoring, and managing hardware test suites against physical devices on a factory floor.

It lets you:

• Write tests as human-readable YAML files and validate them before use
• Run tests against physical hardware and monitor every step in real time
• Store results with full numeric measurement data and query them later
• Manage test packages — versioned bundles of related test scripts

Maestro is not a software testing tool. It is designed specifically for the manufacturing test problem: physical hardware, multiple stations, factory operators, and permanent traceable records. See for-pytest-users.md for a detailed comparison with pytest and Robot Framework.

Station

A Station is one physical test bench — a computer, connected instruments, and a device under test (DUT) fixture. Each station runs its own local Maestro API instance. There is no central server; stations are fully autonomous.

Each station has a unique station_id (e.g. ST-01) stored in Station Config and stamped on every test execution record.

See for-pytest-users.md § 9 for the architectural rationale.

Station Config

Station Config is a two-tier (global + per-station) key-value store backed by PostgreSQL. Values are injected automatically into every test step as cfg.* variables.

# YAML uses cfg.* — identical on every station
parameters:
  address: "{{cfg.DMM_VISA}}"

Station ST-01 might have DMM_VISA = TCPIP::192.168.1.50::INSTR. Station ST-02 might have DMM_VISA = TCPIP::192.168.1.51::INSTR. The YAML never changes between stations.

Station Config is managed through the Maestro UI and API — never through docker-compose environment variables or .env files.

Every test execution stores a JSONB snapshot of the merged config at execution time, so the exact settings active during any historical run can be retrieved from the database.

Test Definition (YAML)

A test is described in a .yaml file. It specifies the sequence of steps, measurement limits, variables, and pass/fail logic. The file lives on the API server (inside a package or in the TestFiles/ directory).

For full YAML syntax, see ../yaml/schema.md and ../yaml/steps.md.

Test Package

A Test Package is a versioned directory of YAML test files, runner assemblies, and a package.json manifest. Packages are stored in a Git-backed central catalog registry and downloaded on demand by each station via the Package Manager.

Every test execution record stores the Git commit hash of the installed package — so the exact code version active during any historical run is always retrievable.

See ../getting-started/package-structure.md for package layout details.

Test Execution

When a test starts, the API loads the YAML file, runs each step against the connected hardware via a Runner, collects measurements, and emits live progress events over SignalR to every connected browser.

Each execution produces a permanent record in PostgreSQL with:

Verdict

Every step and every execution gets a Verdict:

Verdicts are colour-coded throughout the UI: green (PASS), red (FAIL), yellow (UNDETERMINED).

Measurement

A Measurement is a numeric value captured during a test step, stored with its name, actual value, lower limit, upper limit, unit, verdict, timestamp, station ID, and serial number as a structured relational row — not a log string.

This enables direct SQL queries for SPC, yield analysis, and drift detection without any log parsing or post-processing. See for-pytest-users.md § 3 for worked SQL examples.

Runner

A Runner is a process that executes the actual test code (Python or .NET) and communicates with the Maestro API via gRPC. A single test sequence can call a .NET runner in one step and a Python runner in the next — variables flow between them through Redis. The Runner model is described in ../sdk/design-principle.md.

SignalR Connection

The Maestro UI maintains a persistent SignalR WebSocket connection to the local API. A coloured dot in the UI shows the current state:

• 🟢 Connected — live step updates, measurements, and log output are streaming
• 🔴 Disconnected — connection was lost; the page reconnects automatically

If the dot stays red for more than a few seconds, verify the API is running at the configured address.

MES Integration

Maestro has a pluggable IMesService interface with three lifecycle hooks — routing, validation, and result reporting — wired into the execution model. The default AllowAllMesService implementation lets everything through (no MES required). See for-pytest-users.md § 6 for a full description of the MES integration model.