Running tests

The Tests sub-tab runs the configuration against sample data and lists past runs.

Sample input files

A test needs an input file of sample telemetry. When you start a run, choose the source:

• My Files. Files you have uploaded.
• Templates. Sample telemetry provided by Telflo, filtered by Receiver Type and Signal Type, with View contents and Download actions per template.
• Paste Text. Paste a sample of up to 1 MB directly. Enter a Name and select Use Sample; the paste is saved to My Files as a reusable file. For a logs pipeline fed by a filelog or syslog receiver, paste raw log lines; otherwise paste OTLP/JSON matching the pipeline's signal type.
• Upload. Add a new file from the My Files view.

The Paste Text panel can also generate a sample: describe it in the Generate with AI field, in up to 500 characters, such as the signal type and the shape of the data, and select Generate. A test pipeline must be selected first, because generation is signal-specific.

Run a test

1. Open the Testing tab and select Tests.
2. Select Configure and run to open the Select Test File dialog.
3. Select an input file.
4. Select the Test Pipeline to run it through. The run exercises only this pipeline; other pipelines in the configuration do not run. The pipeline also selects which validation rules are evaluated.
5. Set the Run duration (seconds): 1 to 60. The field starts at 5 and afterwards remembers the value you last used. Increase the duration for pipelines with longer windows, such as batch with a long timeout or tail_sampling, which would otherwise produce no output in time.
6. Select Run.

Configure and run is disabled while another run is in progress or no configuration version is loaded. To repeat a past run, select Re-run test on its row in the history. It replays that run's input file, pipeline, and duration against the YAML currently in the editor, sent as written: a re-run does not substitute $orgvar: references, so for a configuration that uses organization variables, start a new run instead.

If the sample does not match the selected pipeline, Telflo shows a Fixture may not match the receiver warning before running. It fires when the sample is raw log lines or NDJSON but the pipeline uses an OTLP receiver, when the sample is OTLP/JSON but the pipeline is fed by a filelog or syslog receiver, or when the sample's signal does not match the pipeline's signal type. A mismatched sample decodes to zero records, so the run would likely produce no output. Select Run Anyway to proceed, or Cancel.

Run a test from the CLI or API

telflo test --spec <file> --config <id> runs a stored version from the terminal, and telflo test --spec <file> -f <yaml> runs a local YAML file. The spec names the pipeline, a sample of up to 1 MB, a duration of 1 to 60 seconds, and the rules. The CLI polls the run until it finishes and prints each rule as PASS, FAIL, or not evaluated; it exits 4 when a rule fails and 1 when the collector could not run. A wrong pipeline name is refused before the run starts, with the pipelines the configuration does have. The Fixture may not match the receiver check is not applied: a sample of the wrong shape decodes to zero records and the run produces no output.

A run that targets a stored version appears in that version's history on this sub-tab with cli-sample.json as its input file. A run the sandbox never picked up is marked Error, and its log begins with The test was never executed: followed by the reason. See Pipeline tests for the spec format and API endpoints for POST /testing/runs.

Run status

Each run in the history shows a status: Queued, Running, then Success, Validation Failed when the run completed but at least one validation rule failed, or Error when the collector could not run. The CLI and the API report Validation Failed as Fail; the other statuses use the same names. A run that cannot start, because the testing service is unavailable, rate-limited, or offline, is marked Error rather than left queued, and its collector log carries the reason the testing service gave, for example that the selected collector version is not installed on the test runner. Select a run to view its captured output. When a run's window was shorter than a pipeline's decision window, such as tail_sampling, the results show the duration to use on the next run. Runs started by the AI assistant appear in the history like your own and can be re-run the same way. The assistant runs tests on OpenTelemetry Collector Contrib only, so a run it starts for a ClickStack configuration ends in Error.

A run that captured collector diagnostics shows a Logs link. Open it to read the collector's stderr, which is useful when a run produced no output or fewer records than expected. The input, output, and log viewers each have a Download action.

A run's details also show the configuration the run executed:

• Original YAML. The configuration exactly as it appeared in the editor when the run was triggered.
• Test YAML. The YAML the sandbox collector executed. Receivers and exporters are swapped for sandbox stand-ins so the run is isolated from your real sources and destinations.
• Mutations. The list of sandbox rewrites that were applied, each with a stable identifier, a severity, and an explanation.

Requirements

• A configuration version must be loaded. The run tests the configuration as it currently appears in the editor.
• A run from the Testing tab uses the collector version selected in the toolbar, within the configuration's collector distribution. A run started from the CLI or the API uses the version and distribution named in the request; otherwise the pin of the version it targets, or the server default for a local file. Both are recorded on the run when it starts, except a local file that falls back to the server default, which records neither. A ClickStack configuration, available in private preview, runs on the OpenTelemetry Collector Contrib build its ClickStack version is based on. The API accepts only otelcol-contrib when a distribution is named, but a configuration already locked to ClickStack stays testable on its own pin.
• For a run started from the Testing tab, $orgvar: references are replaced with their org-default values; variable-group overrides do not apply to test runs. See Vault. A run started from the CLI or the API does not substitute $orgvar: references, and the sandbox collector rejects them: test a copy with the values written in, or run the test from the Testing tab.

Next steps

• Define pass/fail checks for output. See Validating output.
• Group reusable tests. See Test suites.