Skip to content

Assert ​

evidence.assert checks evidence collected by another step against an expected value or pattern. Point it at a collect-evidence step, pick one of that step's outputs, and the step passes only when the collected content satisfies the chosen operator — for example, that a software version line contains 17.9 or that every OSPF neighbor row reads Full.

Using It ​

Evidence Step selects the collect-evidence step to read from, and the Evidence Output picker chooses which of its outputs to assert: a target plus the command that produced the output. Every device bound to that target is asserted separately against its own collected artifact, so one assert step can validate a whole role at once. The artifact is found by the device and the full command text, ignoring spaces at either end, so two long or multi-line commands with similar artifact names are never mixed up. When the collect step ran more than once (loops, retries), the newest artifact per device is the one asserted.

The Operator (default Contains) compares the content with the Expected Value / Pattern. The regex operators treat the expected value as a regular expression. The ordering operators compare numbers only: the expected value and the compared content (the whole output, or each selected line) must each be a number such as 42 or 17.9, and the assertion fails when either is not. A version string such as 17.09.04a, or a line that holds more than the number, is not a number. Very large artifacts are truncated to their first million characters - by the regex operators in whole-output scope, and by every operator in line scope.

Match Scope decides what one comparison covers. Whole output (the default) asserts once against the entire artifact. Every line applies the operator to each selected line and requires all of them to pass. In line scope, Line Filter is a regex choosing which lines count (empty selects every non-empty line), and Minimum Lines (default 1) fails the step when fewer lines are selected - so under the default, a filter that matches nothing cannot pass vacuously. Setting Minimum Lines to 0 removes that floor and lets an empty selection pass.

Custom Message, when set, replaces the generated pass summary and the generated failure error with your own wording.

Output ​

Later steps read the outcome from steps.NODE_ID.output: passed, checked (the artifact names it looked at, as <device name>:<command> for a target role) and failed (those that did not pass, including any it could not fetch). The step records no metrics; the details are evidence. Each fetched artifact produces one assertion_result evidence record — named assertion for a single artifact, or assertion:<artifact name> when several devices were checked — capturing the operator, the expected and actual values (actual truncated to 500 characters), whether it passed, and in line scope the line filter, how many lines were selected and passed, and the first failing line. For a failed capture it records the capture's error instead of the line details. An artifact it could not fetch has no record; the step's error names it.

When It Fails ​

The step succeeds only when every checked artifact satisfies the assertion. It fails when the chosen target is not bound to any device, when no artifact names can be resolved from the configuration, or when any artifact fails the comparison; the error lists each failing artifact unless a Custom Message replaces it. An ordering operator fails when the expected value or the compared content is not a number, and the error says which. An artifact whose capture failed - the device could not be reached or the command returned an error - fails without being compared, and the error names the device, the command and the capture's error: its output is empty or an error message, which would otherwise pass Does Not Contain, Does Not Match and Not Equals. An artifact that cannot be fetched from the run (the fetch uses a 30-second API timeout) counts as a failure for that artifact while the remaining artifacts are still checked. In line scope the step also fails when the artifact is not text, when the Line Filter regex is invalid, or when fewer than Minimum Lines lines are selected. Evidence records are written for the artifacts that were compared even when the step fails.

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].