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

Maestro UI Workflows

This file documents every page in the Maestro web application and the workflows an operator or developer follows to use them.

Navigation

SignalR Connection Indicator

The UI maintains a persistent SignalR WebSocket connection to the local API. A coloured dot on each page shows the state:

• 🟢 Connected — live updates are flowing
• 🔴 Disconnected — the 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.

Test Monitor (/test-monitor)

The Test Monitor page lets you start a test execution, track its progress in real time, and review measurements as they arrive.

Starting a Test

Fill in the form at the top of the page and click Start Test.

★ Composite file indicator — files that contain at least one type: sequence step (i.e. they call sub-sequences) are prefixed with ★ in the dropdown. This is a convenience marker to help you identify top-level orchestrator files at a glance. Sub-sequence files that are meant to be called by a composite file — but are also valid standalone tests — have no prefix. See yaml/standalone-composite-pattern.md for details on the composite pattern.

File Validation

As you type in the Test File Path box, the UI automatically checks whether that file exists on the server:

• ✅ Green border + "File found on server" — path is valid and the test can be started
• ❌ Red border + "File not found on server" — check the path and try again

Start Button

The Start Test button is enabled only when:

• The SignalR connection is active (green dot)
• Serial Number is filled in
• The test file exists on the server

Execution Status Banner

While a test is running, a banner below the form shows the current state.

The banner colour matches the verdict: green for PASS, red for FAIL, yellow for UNDETERMINED.

Aborting a Test

Click Abort in the status banner to send a stop signal to the runner. The current step is allowed to finish before the execution halts. Results up to that point are still saved.

The Steps Panel

The Test Steps panel on the left shows every step in the test in execution order.

Each row shows:

Click any row with a measurement count badge to expand it. Expanded rows show each individual measurement with its actual value, lower limit, upper limit, and pass/fail state.

If a step fails with an exception, the error message is shown inline in red beneath the step name.

The Variables Panel

The Variables panel on the right shows all runtime variables defined in the test, updated live as steps produce values. This includes {{variable}} substitution placeholders, computed values, and dynamic limits.

The Logs Panel

The Logs panel shows log entries captured from test code stdout/stderr — useful for debugging or understanding exactly what happened at each point.

See ../../DEVELOPERS_GUIDE.md for how to emit log entries from test code.

After the Test

When execution finishes, the result is automatically saved. You can find it in Test Results by searching for the serial number or test name.

The Test Monitor page retains the last execution state until you start a new test or reload the page.

Test Results (/test-results)

The Test Results page lets you search the historical archive of test executions and open detailed reports for any individual run.

Searching

Fill in one or more search fields and click Search. All fields are optional — leaving everything blank returns the most recent results.

Click Clear to reset all fields.

Results Table

The table shows one row per test execution.

If more than one page of results is available, navigation buttons appear below the table.

Viewing a Detailed Report

Click View to open the full test report.

Header

• Test name and YAML definition used
• Serial number, operator, and station ID
• Start time, end time, and total duration
• Overall verdict (large colour-coded badge)

Step Results Table

Every step in the execution with:

Click any step row with measurements to expand it and see:

• Measured value
• Lower and upper limits
• Pass/Fail for each point

Inline Image Artifacts

If a test step emits image files (PNG, JPEG, SVG) via emit_artifact() or EmitArtifact(), they are displayed inline in the step row — not just as download links. Each image is shown as a clickable thumbnail; clicking it opens the full-size image in a lightbox.

Images are grouped in an Inline Images section that appears below the step results table for the step that produced them.

Non-image artifacts (e.g. CSV files, log files) continue to appear as download links.

Interactive Plotly Charts

If a test step emits a Plotly figure via emit_plotly() / EmitPlotly() (content type application/vnd.plotly.v1+json), the chart is rendered as a fully interactive Plotly chart in the report — you can zoom, pan, hover for values, and export to PNG.

Plotly charts are grouped in an Interactive Charts section below the step results table. Both the UI app and the Dashboard app support this.

Plotly charts are hidden when printing. Use the Plotly toolbar's PNG export button instead to include a chart snapshot in a printed report.

Nested Executions

If the test used nested script steps, each nested execution appears as a collapsible section beneath the main step table, with its own step list and verdict.

Permanent Report URL

Each detail report has a permanent URL: /test-results/{id}. You can bookmark it or share it with colleagues.

Printing / Exporting

Use your browser's Print function (Ctrl+P) to print a report or save it as PDF. The report page hides the navigation sidebar and toolbar when printing.

YAML Validator (/yaml-validator)

Paste or upload a YAML test definition and click Validate to check it for syntax and schema errors before committing it to a package.

The validator runs the same validation rules as the engine. See ../reference/validation-rules.md for the full list of errors it can report and how to fix them.

Packages (/packages)

The Packages page lets you browse the central package catalog, download packages to the local station, and manage installed versions.

See ../../PACKAGE_MANAGER_GUIDE.md for detailed package management workflows including lifecycle status (NotReleased, Evaluation, Released, Obsolete) and Git commit tracking.

Getting Help

• Use the sidebar on the in-app Help page to browse topics
• For YAML syntax questions, see ../yaml/index.md
• For package management, see ../../PACKAGE_MANAGER_GUIDE.md
• For API endpoint details, open Swagger at http://<api-host>/swagger