path: root/.agents/testing-and-justfile.md

# Unit Tests and Justfile Implementation

## Summary

Added comprehensive pytest-based unit tests and created a Justfile for development workflow automation.

## Changes Made

### 1. Unit Tests

Created comprehensive pytest test suite covering all major functionality:

#### Test Files Created

**`tests/conftest.py`**
- Pytest fixtures for sample data
- `sample_items`: Standard test items
- `custom_key_items`: Items with custom field names
- `single_line_items`: Items for single-line display

**`tests/test_models.py`** (52 tests)
- `TestSelectItemCreation`: Basic Pydantic model creation
- `TestSelectItemValidation`: Field validation tests
- `TestSelectItemToDict`: Dictionary conversion
- `TestSelectItemFromDict`: JSON/dict to SelectItem conversion
- `TestSelectItemRoundTrip`: Round-trip conversions

**`tests/test_selectui.py`** (27 tests)
- `TestSelectUIInitialization`: Initialization with various configs
- `TestSelectUIFiltering`: Filtering logic tests
- `TestSelectUINormalization`: Item normalization
- `TestSelectUIState`: State management
- `TestSelectUIEdgeCases`: Edge cases and error handling
- `TestSelectUICustomKeys`: Custom key configuration

**`tests/test_filtering.py`** (24 tests)
- `TestExactFiltering`: Exact string matching
- `TestCaseSensitiveFiltering`: Case-sensitive search
- `TestFuzzyFiltering`: Fuzzy search with typos
- `TestFilteringWithCustomKeys`: Custom key filtering
- `TestEmptyQueryFiltering`: Empty query handling
- `TestFilteringEdgeCases`: Edge cases

**`tests/test_integration.py`** (17 tests)
- `TestPydanticIntegration`: Pydantic + SelectUI integration
- `TestDictToPydanticConversion`: Conversion pipeline
- `TestCustomKeyMappings`: Key mapping integration
- `TestRealWorldScenarios`: GitHub API, DB queries, file listings
- `TestEdgeCasesIntegration`: Unicode, special chars, large datasets
- `TestBackwardCompatibility`: Plain dict compatibility

**`tests/test_basic.py`** (existing, 4 tests)
- Basic filtering and fuzzy search logic
- UI initialization tests

### 2. Justfile

Created comprehensive `justfile` with development commands:

#### Core Commands

- `just install` - Install all dependencies including dev
- `just check` - Run all checks (ruff + mypy)
- `just test` - Run all tests with pytest
- `just fix` - Auto-fix linting issues
- `just ci` - Run all checks and tests (for CI)

#### Detailed Commands

- `just check-ruff` - Run ruff linter only
- `just check-mypy` - Run mypy type checker only
- `just fix-ruff` - Auto-fix with ruff
- `just fmt` - Format code with ruff
- `just test-cov` - Run tests with coverage report

#### Utility Commands

- `just demo` - Run interactive demo
- `just example NUM` - Run specific example
- `just clean` - Clean build artifacts
- `just info` - Show project info
- `just watch-test` - Watch and auto-run tests (requires entr)
- `just lint` - Alias for check
- `just pre-commit` - Run pre-commit checks

### 3. Configuration

**`pyproject.toml`** updates:
- Added dev dependencies: pytest, pytest-cov, ruff, mypy
- Added `[tool.mypy]` configuration
- Added `[tool.pytest.ini_options]` configuration
- Added `[tool.ruff]` and `[tool.ruff.lint]` configuration

**Dependencies Added:**
```toml
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "ruff>=0.1.0",
    "mypy>=1.7.0",
]
```

**Tool Configuration:**
```toml
[tool.mypy]
python_version = "3.12"
warn_return_any = false
warn_unused_configs = true
disallow_untyped_defs = false
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = "-v --tb=short"

[tool.ruff]
line-length = 100
target-version = "py38"

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N"]
ignore = ["E501"]
```

### 4. Code Fixes

**Type Annotations:**
- Added type guards with assertions for mypy
- Fixed unused imports flagged by ruff
- Fixed import sorting
- Fixed boolean comparisons (`== True` → truthiness checks)

**Pydantic Updates:**
- Fixed deprecation warning: `Config` class → `ConfigDict`

### 5. Test Coverage

**Total Tests:** 84 tests
- test_basic.py: 4 tests
- test_filtering.py: 24 tests
- test_integration.py: 17 tests
- test_models.py: 12 tests
- test_selectui.py: 27 tests

**All tests passing:** ✅

## Usage

### Run Tests

```bash
# Run all tests
just test

# Run tests with coverage
just test-cov

# Watch tests (auto-run on changes)
just watch-test
```

### Run Checks

```bash
# Run all checks (ruff + mypy)
just check

# Run only ruff
just check-ruff

# Run only mypy
just check-mypy
```

### Fix Issues

```bash
# Auto-fix linting issues
just fix

# Format code
just fmt
```

### CI/CD

```bash
# Run all checks and tests (for CI)
just ci

# Pre-commit hook
just pre-commit
```

### Examples

```bash
# Run interactive demo
just demo

# Run specific example
just example 1

# Show project info
just info
```

## Test Results

```
Running pytest...
============================= test session starts ==============================
collected 84 items

tests/test_basic.py::test_filtering_logic PASSED                         [  1%]
tests/test_basic.py::test_fuzzy_search_logic PASSED                      [  2%]
tests/test_basic.py::test_ui_initialization PASSED                       [  3%]
tests/test_basic.py::test_ui_initialization_empty PASSED                 [  4%]
...
============================== 84 passed in 0.86s ==============================
```

## Linting Results

```
Running ruff...
All checks passed!

Running mypy...
Success: no issues found in 15 source files
```

## Benefits

1. **Comprehensive Testing**: 84 tests covering all major functionality
2. **Type Safety**: Full mypy type checking
3. **Code Quality**: Ruff linting with auto-fix
4. **Easy Workflow**: Simple commands for all dev tasks
5. **CI Ready**: Single command for CI/CD pipelines
6. **Fast Feedback**: Quick test execution (~0.86s)

## Files Modified

- `pyproject.toml` - Added dev dependencies and tool configs
- `src/selectui/__init__.py` - Type annotations and fixes
- `src/selectui/models.py` - Pydantic ConfigDict update
- `tests/test_basic.py` - Boolean comparison fixes
- `examples/test_library.py` - Boolean comparison fixes
- `examples/test_pydantic.py` - Unused variable fixes

## Files Created

- `justfile` - Development task automation
- `tests/conftest.py` - Pytest fixtures
- `tests/test_models.py` - Pydantic model tests
- `tests/test_selectui.py` - SelectUI class tests
- `tests/test_filtering.py` - Filtering logic tests
- `tests/test_integration.py` - Integration tests
- `.agents/testing-and-justfile.md` - This file

## Replaced

- `demo.sh` → `just demo` (Justfile command)

The old `demo.sh` functionality is now available as `just demo`.