---
name: pytest-setup
description: Set up pytest in the dev container and run a test suite. Use when the user asks to add tests, run pytest, set up TDD, or verify code with unit tests.
---

# pytest Setup

## 1. Install pytest

```bash
pip install --quiet pytest pytest-asyncio
```

## 2. Create the test layout

The convention used in `/app` is a top-level `tests/` directory:

```text
/app/
├── <module>.py
└── tests/
    └── test_<module>.py
```

Use `ToolUpsertFile` to create `/app/tests/__init__.py` (empty) and a test
file like `/app/tests/test_example.py`:

```python
import pytest


def test_smoke():
    assert 1 + 1 == 2


@pytest.mark.asyncio
async def test_async_smoke():
    assert True
```

## 3. Configure pytest

Create `/app/pyproject.toml` (or extend an existing one) with:

```toml
[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
```

## 4. Run the suite

```bash
cd /app && pytest -q
```

For a single test: `pytest -q tests/test_example.py::test_smoke`.
For verbose failure output: add `-vv --tb=short`.

## Notes

- Do NOT mock the dev container's filesystem in tests — write real files to a
  temp dir via `tmp_path` fixture instead.
- If a test hangs, it is almost always an unawaited coroutine; check that
  async tests are marked or that `asyncio_mode = "auto"` is set.