> ## 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.

# How it works

> What happens between the sentence you type and the report you read.

<Steps>
  <Step title="You describe the workflow">
    You type one instruction into the project's chat, against the project's
    base address. Optionally you mark it **Should fail** (a negative test) or
    raise the time limit for a slow flow.

    If the instruction needs values Testorim cannot invent, such as a real email
    and password, it stops and shows you a small form instead of guessing.
  </Step>

  <Step title="A plan is written">
    The planner turns your sentence into an ordered list of steps: navigate,
    click, type, assert, select, press, and so on. Each step names its target
    in plain language and, for an assertion, a condition from a
    [closed grammar](/test-creation/steps-and-outcomes#assertion-conditions).

    Two passes run over the plan before anything executes. A critic drops
    assertions too vague to mean anything. A coverage judge then lists any
    check you asked for that no step performs; the planner gets one chance to
    write the missing check, and anything still uncovered is recorded as a
    visible gap rather than silently dropped.
  </Step>

  <Step title="A browser starts">
    A Chromium browser launches at your project's base address, with any
    environment overrides applied: a different base URL, extra headers,
    cookies, a timezone, a locale.

    If the project has a saved login state from a login-setup procedure, it is
    loaded here, so the run starts signed in.
  </Step>

  <Step title="Steps execute, one at a time">
    For each step, Testorim finds the element, acts on it, waits for the page
    to settle, and captures a before/after snapshot.

    Finding the element has two tiers. **Exact** matching comes first: a
    control whose accessible name *is* the target, a `<label>`, a placeholder,
    a test id, a CSS selector you wrote, an explicit ordinal. Anything looser
    goes to a **grounding** model, which is shown the page's real controls (role,
    accessible name, state, the row it sits in) and asked which one the
    step means, with your original request as context. If it says none of them,
    the step fails and tells you what *is* on the page.

    Screenshots stream to your browser throughout.
  </Step>

  <Step title="The run settles and is measured">
    After the last step, the page is allowed to settle, a final screenshot is
    taken, an accessibility scan runs, and performance metrics are collected.
    Any visual baselines for the procedure are diffed here.
  </Step>

  <Step title="A report is written">
    The report quotes what was observed: the element's real state, the text
    that was actually on the page, the network calls that fired. Never an
    attribute nobody looked at. It ends with a structured verdict.

    The run's status is decided by the steps, not by the prose: a run passes
    only when every executed step passed, no coverage gap was left, and the
    verdict agrees.
  </Step>

  <Step title="You save it, or you do not">
    A run you are happy with can be saved as a **procedure**, a fixed list of
    steps that replays without planning it again. Replays are deterministic,
    cost less, and are what schedules, the CLI, and the GitHub PR bot run.
  </Step>
</Steps>

## Why the two-tier resolver matters

The honest answer to "which element did you click?" is the difference between a
test suite you trust and one you argue with.

Exact strategies are accepted as-is, because there is nothing to infer: if the
button's accessible name is *Add to cart* and the step says *Add to cart*, that
is the button. Everything else (a loose text match, a partial name, a miss)
goes to the model with the page's actual elements in front of it, rather than
being guessed at by a cascade of heuristics.

The practical consequence: when a step fails, it fails with a description of
what the page really showed. *"No 'Provision Worker' button or link is visible
The page shows a Users list with an 'Invite user' button and various user
row controls."* That is a finding you can act on.

## Why a failure is attributed

Every failure carries a cause, decided where the failure was raised:

| Cause           | Meaning                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| **app**         | The site under test misbehaved. A real defect.                                                          |
| **test**        | The step does not match the page: target not found, ambiguous, typed value did not stick. Fix the step. |
| **unsupported** | The check is outside what a browser can observe at all.                                                 |
| **internal**    | Testorim's own runner broke. Never described to you as a fault of your site.                            |

A report that suggests you check your selectors when the browser actually threw
is worse than no report. The attribution is set at the throw so that cannot
happen.


## Related topics

- [What is Testorim](/index.md)
- [GitHub](/integrations/github.md)
- [FAQ](/resources/faq.md)
- [Test data](/test-creation/test-data.md)
- [Writing tests in plain English](/test-creation/writing-tests.md)