# Reading a check's verdict

> `osy check` validates, lints and tests your app, and its exit code says which of three things happened: the app passed, the app failed, or the check could not run on this computer. `--json` prints the same verdict for a program.

<!-- id: local-reading-a-checks-verdict · area: local · stability: stable · html: https://osysharp.com/reference/local/reading-a-checks-verdict/ -->

## Summary        {#summary}

`osy check` runs three legs (validate, lint, test) and ends with one verdict. A script or an agent that acts on that
verdict needs to tell "the app is wrong" apart from "this computer could not run the tests". The second is not a reason
to change the app, so it gets an exit code of its own.

## Signature      {#signature}

```console
osy check [path] [--strict] [--changed] [--json]
```

## Description    {#description}

| Exit code | Verdict | What it means |
|---|---|---|
| `0` | `passed` | Validate, lint and every test passed. |
| `1` | `failed` | The app failed: a validate error, a MUST-tier lint finding (or a SHOULD one with `--strict`), or a test that failed. |
| `3` | `could-not-run` | Validate and lint passed, but the tests could not run here. Nothing is known about the app. |

A check could not run when the local test platform did not start, when the connection to it was lost, or when its
database refused the run. It is `could-not-run` only if every test that went red went red for one of those reasons, and
validate and lint passed. If validate or lint failed, the verdict is `failed`: those failures are about the app,
whatever happened to the tests.

Act on a `3` by running the check again, not by changing the app. Osyrin Studio does exactly that: it tries again by
itself, then shows "Check again" and never asks the builder for a fix.

`--json` prints the verdict on standard output and sends progress to standard error:

```json syntax
{
  "verdict": "could-not-run",
  "exitCode": 3,
  "failed": ["test"],
  "couldNotRun": { "reason": "database-unavailable", "detail": "57P01: terminating connection due to administrator command" },
  "tests": { "passed": 41, "failed": 0, "errored": 3, "skipped": 0 }
}
```

- `verdict` is `passed`, `failed` or `could-not-run`, and `exitCode` is the process's exit code.
- `failed` names the legs that failed: any of `validate`, `lint` and `test`.
- `couldNotRun` is set only for `could-not-run`. Its `reason` is one of `platform-did-not-start`, `connection-lost`
  and `database-unavailable`, which are stable values to branch on. Its `detail` is the message, written for a person.
- `tests` holds the test counts, or `null` when the test leg did not run.

With `--access`, `--json` prints the access report instead ([Checking access](https://osysharp.com/reference/local/checking-access/)).

## Examples       {#examples}

```console
osy check                   # validate, lint, test; exit 0, 1 or 3
osy check --json            # the same verdict, as JSON on standard output
```

```console
osy check --json | jq -r '.couldNotRun.reason // .verdict'
```

## See also       {#see-also}

[Checking your app](https://osysharp.com/reference/local/checking-your-app/) covers the lint leg and what its findings mean.

[What a clean check means](https://osysharp.com/reference/local/what-a-clean-check-means/) covers what validate cannot check without a compile.

[Checking every project at once — osy validate --all / --affected](https://osysharp.com/reference/local/checking-every-project/) checks every project in a repository.

[Checking access](https://osysharp.com/reference/local/checking-access/) checks the running app against its access model.
