product: maestro audience: test-developer, ai-assistant authority: normative
Maestro Test Package Documentation — Index
This documentation IS the authoritative source for how Accordion Maestro test packages work. Every question about YAML syntax, step behaviour, measurement limits, variables, runners, and SDK patterns MUST be answered from these files.
Pre-Commit Rules — MANDATORY GATE
DO NOT push without completing every item below.
| Trigger | Action required |
|---|---|
| Any file modified | Bump version in package.json. The runner silently ignores packages whose version has not changed. |
Any .yaml file created or modified |
Run py validate.py and confirm zero errors before staging. Do NOT stage YAML that has not passed validation. |
Any .NET runner code changed |
Run dotnet publish <YourProject>.csproj -c Release -o assemblies/ --no-self-contained and commit assemblies/. The runner DOES NOT build your project — if assemblies/ is stale the wrong code runs silently. |
If your package uses Accordion hardware, read this first
If any test code references AccordionQ2Client, accordionq2, AccordionPilot,
AccordionShell, or any ESH1* hardware module, you MUST read the Accordion docs
before writing any test code or YAML.
Start here: Accordion/README.md
The Maestro integration pattern (connect/disconnect wiring, Station Config key,
{{cfg.AGENT_HOST}} convention) IS documented in getting-started/accordion-q2-client.md.
Use this documentation to answer
| Question | File |
|---|---|
| What is Maestro? How does it compare to TestStand / pytest? | overview.md |
| How do I connect to an Accordion instrument from test code? | getting-started/accordion-q2-client.md |
| What is the end-to-end development workflow? | getting-started/workflow.md |
What does a package directory look like? What goes in package.json? |
getting-started/package-structure.md |
What are the top-level YAML fields (test:, steps:, setup:, teardown:)? |
yaml/schema.md |
| What step types exist and how do I write them? | yaml/steps.md |
| How do measurements, limits, and operators work? | yaml/measurements.md |
How do enabled, precondition, retry, repeat, timeout_ms, run_on_abort work? |
yaml/runtime-control.md |
How do variables, cfg.*, exec.*, mes.*, and {{templates}} work? |
yaml/variables.md |
| How do I compose tests with sequences, patterns, and cross-package references? | yaml/composition.md |
| How do I write sub-sequences that work both standalone and as part of a full suite? | yaml/standalone-composite-pattern.md |
| What errors does the YAML validator report and how do I fix them? | reference/validation-rules.md |
| What are the naming conventions for packages, steps, measurements, and variables? | reference/naming-conventions.md |
| What are the common anti-patterns and what should I do instead? | reference/anti-patterns.md |
| What are the local development CLI commands? | reference/local-dev-commands.md |
| What is the checklist for creating a new package? | reference/checklist.md |
| Why should each YAML step map to one method/function? | sdk/design-principle.md |
| How do I write .NET runner methods? Parameters, return types, measurement points? | sdk/dotnet-sdk.md |
| How do I write Python runner functions? Parameters, returns, measurements in YAML? | sdk/python-sdk.md |
| How do I vendor pip wheels for air-gapped production stations? | sdk/python-dependencies.md |
| How do I debug .NET test code locally with MSTest? | sdk/mstest-debugging.md |
| How do I debug Python test code locally without a running stack? | sdk/python-debugging.md |
| How do operator prompt steps work, including value input modes? | ui/prompt-input.md |
| How do I let an AI assistant control a Maestro station via MCP? | mcp/index.md |
| How do I configure and connect the MCP server? | mcp/setup.md |
| What MCP tools exist and what parameters do they take? | mcp/tools-reference.md |
| MCP system tools — health, version, logs, Docker events | mcp/tools-system.md |
| MCP test execution tools — start, abort, wait, validate | mcp/tools-test-execution.md |
| MCP package management tools | mcp/tools-packages.md |
| MCP config tools — station config, registry settings | mcp/tools-config.md |
| MCP statistics tools — yield, Cp/Cpk, worst steps, unit history | mcp/tools-statistics.md |
| MCP live event tools — SignalR connect and poll | mcp/tools-live-events.md |
| MCP report tools — search history, steps, logs, artifacts | mcp/tools-reports.md |
| What is unattended mode — how do prompt steps behave in automated runs? | mcp/unattended-mode.md |
| How do I connect multiple stations to the same AI assistant? | mcp/multi-station.md |
Accordion Hardware Platform
If the user's test code interacts with an Accordion device — including references to
AccordionQ2Client, accordionq2, AccordionQ2.WebApiClient, AccordionPilot,
AccordionShell, ESH1* hardware modules, or any instrument connected via the Accordion
platform — full documentation IS available in the Accordion/ folder.
Start here: Accordion/README.md
| Topic | Path |
|---|---|
| Architecture and core concepts | Accordion/01-overview/architecture.md |
| Hardware modules (ESH1* series) | Accordion/02-hardware/index.md |
| Network / mDNS discovery | Accordion/03-connectivity/network.md |
| AccordionPilot (GUI client) | Accordion/04-client-tools/accordionpilot.md |
| AccordionShell (CLI tool) | Accordion/04-client-tools/accordionshell.md |
.NET API (AccordionQ2.WebApiClient) — overview |
Accordion/05-api-dotnet/ |
| .NET API — Comm (I2C, UART, SPI, Socket) | Accordion/05-api-dotnet/webapiclient-docs/api/comm.md |
| .NET API — Enumerations (ModuleStatus, BusActions, UartBusTypes …) | Accordion/05-api-dotnet/webapiclient-docs/reference/enums.md |
Python API (accordionq2) — overview |
Accordion/05-api-python/ |
| Python API — Comm (I2C, UART, SPI, Socket) | Accordion/05-api-python/webapiclient-python-docs/api/comm.md |
| Python API — Enumerations | Accordion/05-api-python/webapiclient-python-docs/reference/enums.md |
| Python API — Models (response/request DTOs) | Accordion/05-api-python/webapiclient-python-docs/reference/models.md |
For the Maestro-specific integration pattern (wiring AccordionQ2Client as YAML
setup/teardown steps with cfg.AGENT_HOST) see getting-started/accordion-q2-client.md.
Maestro Application
For questions about the Maestro application itself — its UI, concepts (Station, Verdict, Station Config, SignalR, MES integration, Production Dashboard), how it compares to pytest/Robot Framework, or how an operator/developer uses it — see the Maestro docs:
Start here: maestro/index.md
| Topic | Path |
|---|---|
| Core concepts and vocabulary | maestro/concepts.md |
| UI workflows (Test Monitor, Test Results, Packages, YAML Validator) | maestro/ui-workflows.md |
| Comparison with pytest / Robot Framework | maestro/for-pytest-users.md |
Boundaries
If information is not found in these files, it is NOT specified. The AI assistant MUST say this explicitly and MUST NOT guess.
Guarantees
- Files are version-controlled in this package repository.
- Each file covers one closed topic.
- Normative language is used throughout: MUST / MUST NOT / DOES / DOES NOT / IS.