Expected Failures

An expected-failure marker keeps a known, understood failure visible in a suite without failing the run. The fields are available on runs in tests.yaml, fpv.yaml, synth.yaml, pnr.yaml, power.yaml, fpga.yaml, cdc.yaml and lint.yaml; see YAML Formats for each.

Choose strictness

Marker	Actual failure	Unexpected pass	Use when
xfail: true	XFAIL, counts as pass	XPASS, counts as pass	Either outcome is acceptable
xfail_strict: true	XFAIL, counts as pass	XPASS, counts as fail	A pass means the marker is stale

• If both are set, strict wins.
• SKIP and NA are unchanged. A marker does not cover an unknown NA, which still exits 1.
• Prefer xfail_strict: true for a known bug or an intentionally failing teaching case, so the regression reports when the behavior changes.

Name the expected failure

A negative control fails in two ways when the check it exists for regresses: the check stays silent, and something downstream, a watchdog or a data mismatch, fails instead. A bare marker grades both XFAIL. xfail_match names the failure the marker expects:

- name: guard_neg
  xfail_strict: true
  xfail_match: "ECP-1017"

• The regex is searched, not anchored, with Python re syntax. Quote it in YAML.
• It is searched in the first error/fatal line the grader recorded, then in the result desc. A matching FAIL becomes XFAIL.
• The first error/fatal line is the sim log's first ERR:/FAT: line; under uvm:, the first UVM_ERROR/UVM_FATAL report; for a failure from fired SVA assertions, the first Assertion failed line. The result carries it as first_error. Other flows and graders use the desc alone.
• A FAIL that does not match stays FAIL, with desc xfail: failed for a different reason (expected /ECP-1017/): <desc>, and the *_suite.xfail event reports excused: false with that reason.
• A pass is graded as without xfail_match: XPASS, a failure only under xfail_strict.
• It is accepted on every flow that takes a marker. Without xfail or xfail_strict, or with an invalid regex, configuration loading fails.

What the marker covers

A marker excuses only a verdict the flow's own tool reported at its end: a simulation that ran and printed FAIL, a property sby disproved, a violation count, a gate the tool evaluated. A failure that happened instead of a verdict is graded FAIL whatever the marker says, because the run never reached the behavior the marker is about.

Flow	Graded FAIL under a marker
test	preproc, sweep and filelist setup failures; compile failures; a sim killed at sim_timeout; a simulator that exited without a verdict; a dispatched job the scheduler lost
fpv	sby reporting UNKNOWN, a solver timeout, or an error instead of PASS/FAIL; a prove whose base case passed and induction step failed is a verdict, not a tool failure
cdc, lint	the analyzer failing before it produced a count
synth, pnr, power, fpga	setup failures: a missing tool, an unresolvable platform or PDK, a filelist or script-generation error

In synth, pnr, power and fpga, a failure the tool itself reports is that flow's verdict, so a marker still covers a synthesis the tool rejected.

Read a marker that was not applied

The summary table and result.json give the reason:

<suite>  <test>  FAIL  xfail not applied (sim timeout): Sim hit timeout

• The result carries fail_stage: setup, compile, sim_timeout, sim, dispatch or tool.
• The *_suite.xfail event carries excused: false with the same reason, for machine consumers.
• A negative control that stopped compiling, or was killed before reaching the mismatch it exists to catch, therefore fails the run instead of reporting green.