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

# cowboy test

> Run the project's pytest suites through the locked environment

## Synopsis

```bash theme={null}
cowboy test [<target>] [--json]
```

## Behavior

1. Discover the project from the current directory.
2. Select the suites to run. With no target, every existing suite directory in order: `tests/` (the actor, through the SDK's simulated host) and `offchain/tests/` (ordinary Python). With a target, exactly `tests/test_<target>.py`.
3. Locate the project's `uv` and run `uv run --no-config --no-sync pytest <paths>` from the project root with `UV_PROJECT_ENVIRONMENT` set to `.venv`. `VIRTUAL_ENV`, `PYTHONHOME`, and `PYTHONPATH` are removed from the child's environment.
4. Print pytest's report on stdout and its diagnostics on stderr, then exit with pytest's own exit code so CI can use it.

Under `--json`, pytest's report goes to stderr and stdout carries one envelope whose result has `paths`, `target` (when given), `passed`, `failed`, `errors`, `skipped`, `exit_code`, and `ok`. The counts are read from pytest's final summary line; the exit code, not the counts, decides the verdict.

## Flags

| Flag | Default | Description |
| - | - | - |
| `<target>` | None (run every suite) | Actor target whose suite to run |
| `--json` | `false` | Emit one versioned JSON summary |

## Example

```bash theme={null}
$ cowboy test
============================= test session starts ==============================
collected 3 items

tests/test_demo.py ...                                                   [100%]

============================== 3 passed in 0.42s ===============================
```

```bash theme={null}
$ cowboy test demo --json
{"schema":"...","command":"test","ok":true,"result":{"paths":["tests/test_demo.py"],"target":"demo","passed":3,"failed":0,"errors":0,"skipped":0,"exit_code":0,"ok":true},"diagnostics":[]}
```

## Edge Cases

* A project with no suite at all fails with exit code 1 and the `tests_not_found` diagnostic; a deleted suite is not a passing one.
* Naming a target whose `tests/test_<target>.py` does not exist fails with `tests_not_scoped`; run `cowboy test` with no target to run everything.
* Naming a target the project does not declare fails with `target_not_found`.
* `cowboy test` needs `uv`; it fails before running anything if it cannot be found.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.