> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testorim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging a failed run

> Read the cause first, then the evidence. A method that stops you from debugging a working site.

## Start with the cause, not the prose

Every failed step is labelled `app`, `test`, `unsupported` or `internal`. That
label is set where the failure was raised, not guessed afterwards from its
wording. It tells you where to look before you read a word of the report.

<Steps>
  <Step title="Cause is `app`">
    The site misbehaved. Open the failure screenshot and the assertion's actual
    value. They are the bug report.

    Typical: an HTTP 5xx from a navigation, an element that should have
    disappeared and did not, a control that stayed disabled, a submit that
    changed nothing on the page.
  </Step>

  <Step title="Cause is `test`">
    The step does not match the page. The message names what is actually
    there. Go to the section below that matches it.
  </Step>

  <Step title="Cause is `unsupported`">
    The check is outside what a browser can observe: an email that was sent,
    an SMS, a server log. Verify it somewhere else, or use a
    [database assertion](/test-creation/steps-and-outcomes#extra-checks-bolted-onto-a-step)
    if the evidence lands in a table you can read.
  </Step>

  <Step title="Cause is `internal`">
    Our runner broke, and the report says so rather than blaming your site.
    Please [send us the run id](/resources/support).
  </Step>
</Steps>

## Common `test` failures

<AccordionGroup>
  <Accordion title="Could not find an element matching …" icon="search-x">
    The message lists what the page *does* show. Read that first. Usually the
    target is named differently than you assumed, or the flow never reached
    that screen.

    Fixes, in order of preference:

    * Use the wording actually on the page.
    * Name the row for a row-scoped control: *"Delete in the Blue Top row"*.
    * Use a selector target: `#order-total`, `[data-testid="cart"]`.
  </Accordion>

  <Accordion title="Ambiguous target, N candidates" icon="copy">
    More than one element matches and guessing would be worse than failing.
    The message lists the candidates.

    Add an ordinal (*"the first product"*), name the containing row, or use a
    selector that matches exactly one element.
  </Accordion>

  <Accordion title="The typed value did not persist" icon="type">
    Testorim types, waits for the page to re-render, and reads the field back.
    If what came back is not what was sent, the step fails. A green step on a
    field that silently cleared is worse than a red one.

    Usually the app cleared it: a validator, an autosave, an autocomplete that
    committed something else, or a related toggle re-rendering the form. The
    warning at the end of a run (*"typed value X is no longer present in any
    visible input"*) catches the delayed version of the same thing.
  </Accordion>

  <Accordion title="Unsupported assertion condition" icon="ban">
    The condition is not in the grammar, and the message lists what is. See
    [Assertion conditions](/test-creation/steps-and-outcomes#assertion-conditions).
  </Accordion>

  <Accordion title="A state condition on something with no such state" icon="triangle-alert">
    `disabled`, `checked`, `value:` and friends are only meaningful on a
    control. If the target bound to a paragraph, the step refuses rather than
    reporting the paragraph's imaginary state as an app defect.

    Point the target at the control, by name, by control noun, or by
    selector.
  </Accordion>

  <Accordion title="Absence could not be certified" icon="eye-off">
    A `hidden` or `absent` check needs evidence that the thing was ever there,
    on this page, and that the page is still alive. When one of those is
    missing the step fails and names which.

    Fix: assert the element is visible *before* the action that removes it.
    That single extra step gives the absence check its provenance.
  </Accordion>
</AccordionGroup>

## When the report and your eyes disagree

Trust the screenshot and the `actual` value. Both are recorded, neither is
generated.

If a report describes something the screenshot contradicts, that is a bug in
Testorim and we want the run id.

## Warnings worth reading on a passing run

| Warning                                 | What it is telling you                                                                                               |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| The address changed mid-step            | The app redirected while the step was resolving. It acted on the page the app was showing, and names both addresses. |
| An inert Enter was recovered by a click | The field's form does not submit on Enter. A real keyboard-accessibility gap.                                        |
| A resolution had to guess               | The target was matched by an inference, and the warning names what it picked. Tighten the target.                    |
| Completion inferred                     | A long-polling assertion never saw its exact phrase, but the page showed a completion state. Reword the check.       |
| Typed value no longer present           | Something cleared the field after it was typed.                                                                      |

## Making a flaky test honest

See [Reliability](/troubleshooting/reliability). In short: prefer stable
targets, set the right auth mode, let the flakiness dashboard tell you which
test is drifting, and use retry-on-fail only for genuine animation flake.


## Related topics

- [Run and inspect a test](/getting-started/run-and-inspect.md)
- [Support](/resources/support.md)
- [Run status](/test-execution/run-status.md)
- [Get one run with all artifacts](/api-reference/runs/get-one-run-with-all-artifacts.md)
- [Screenshots, logs and evidence](/test-execution/evidence.md)