---
description: Rules for writing and running tests
globs:
  - tests/**
  - webapp-next/src/**/*.test.{ts,tsx}
---

# Testing

## Python tests (pytest)

### Configuration

- Config in `pyproject.toml` under `[tool.pytest.ini_options]`.
- `asyncio_mode = "auto"` — async test functions are detected automatically, no decorator needed.
- Coverage: `--cov=duty_teller --cov-fail-under=80`.
- Run: `pytest tests/ -v` from project root.

### File layout

```
tests/
├── conftest.py       # Shared fixtures (in-memory DB, sessions, bot app)
├── helpers.py        # Test helper functions
└── test_*.py         # Test modules
```

### Key fixtures (conftest.py)

- `conftest.py` sets `BOT_TOKEN=test-token-for-pytest` if the env var is missing,
  so tests run without a real token.
- Database fixtures use in-memory SQLite for isolation.

### Writing Python tests

- File naming: `tests/test_<module>.py` (e.g. `tests/test_import_service.py`).
- Function naming: `test_<what>_<scenario>` or `test_<what>_<expected_result>`.
- Use `session_scope` with the test database URL for DB tests.
- Async tests: just use `async def test_...` — `asyncio_mode = "auto"` handles it.
- Mock external dependencies (Telegram API, HTTP calls) with `unittest.mock` or `pytest-mock`.

### Example structure

```python
import pytest
from duty_teller.db.session import session_scope

def test_get_or_create_user_creates_new(test_db_url):
    with session_scope(test_db_url) as session:
        user = get_or_create_user(session, telegram_user_id=123, full_name="Test")
        assert user.telegram_user_id == 123
```

## Frontend tests (Vitest + React Testing Library)

### Configuration

- Config: `webapp-next/vitest.config.ts`.
- Environment: jsdom; React Testing Library for components.
- Test files: `webapp-next/src/**/*.test.{ts,tsx}` (co-located or in test files).
- Setup: `webapp-next/src/test/setup.ts`.
- Run: `cd webapp-next && npm test` (or `npm run test`).

### Writing frontend tests

- Pure lib modules: unit test with Vitest (`describe` / `it` / `expect`).
- React components: use `@testing-library/react` (render, screen, userEvent); wrap with required providers (e.g. TelegramProvider, store) via `src/test/test-utils.tsx` where needed.
- Mock Telegram SDK and API fetch where necessary.
- File naming: `<module>.test.ts` or `<Component>.test.tsx`.

### Example structure

```ts
import { describe, it, expect } from "vitest";
import { localDateString } from "./date-utils";

describe("localDateString", () => {
  it("formats date as YYYY-MM-DD", () => {
    const d = new Date(2025, 0, 15);
    expect(localDateString(d)).toBe("2025-01-15");
  });
});
```