tests/unit/README.md

# Unit Tests for Feature 001: Refine Memory Producer Logic

## Overview

This directory contains unit tests for the producer ID generation and contact name normalization functionality.

## Test Files

### `test_contact_utils.py` (T021)
Tests for the `normalize_contact_name()` function that handles:
- Basic lowercase conversion
- Special character removal (apostrophes, hyphens, dots)
- Unicode character handling
- Collision scenarios (names that normalize to the same value)
- Edge cases (empty strings, only special chars, whitespace variations)

**Total: 22 test cases**

### `test_storage_service.py` (T022)
Tests for producer ID generation in storage service:
- `get_next_sequence_number()` - atomic sequence allocation
- `create_contact_session()` - producer_id generation with collisions
- `create_contact_session_with_id()` - backend-initiated contacts
- Multi-user scenarios (independent sequences per user)
- Concurrent collision handling

**Total: 18 test cases across 4 test classes**

## Running Tests

### Setup Virtual Environment

```bash
cd /Users/christian.kniep/src/gitlab.com/qnib-memverge/streamlit/prepmate/webapp

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### Run All Unit Tests

```bash
# Run all unit tests
pytest tests/unit/ -v

# Run with coverage
pytest tests/unit/ --cov=src --cov-report=html

# Run specific test file
pytest tests/unit/test_contact_utils.py -v
pytest tests/unit/test_storage_service.py -v
```

### Run Specific Test Cases

```bash
# Test normalization with collisions
pytest tests/unit/test_contact_utils.py::TestNormalizeContactName::test_collision_scenarios -v

# Test sequence number generation
pytest tests/unit/test_storage_service.py::TestGetNextSequenceNumber::test_incremental_sequence -v

# Test concurrent collision handling
pytest tests/unit/test_storage_service.py::TestCreateContactSession::test_collision_handling -v
```

## Expected Results

All tests should pass when run in a properly configured environment:

```
tests/unit/test_contact_utils.py::TestNormalizeContactName PASSED [ 50%]
tests/unit/test_storage_service.py::TestGetNextSequenceNumber PASSED [ 75%]
tests/unit/test_storage_service.py::TestCreateContactSession PASSED [ 87%]
tests/unit/test_storage_service.py::TestCreateContactSessionWithId PASSED [ 93%]
tests/unit/test_storage_service.py::TestProducerIdRetrieval PASSED [100%]

======================== 40 passed in 0.5s ========================
```

## Test Scenarios Covered

### Collision Detection (Critical Path)

The tests validate the collision handling requirement from User Story 2:

1. **Same user, same normalized name** → Sequential producer IDs
   - "O'Brien" → `testuser_obrien_1`
   - "OBrien" → `testuser_obrien_2`
   - "O Brien" → `testuser_obrien_3`

2. **Different users, same normalized name** → Independent sequences
   - User1's "Jane Doe" → `user1_janedoe_1`
   - User2's "Jane Doe" → `user2_janedoe_1`

3. **Same user, different names** → Separate sequences
   - "John Doe" → `testuser_johndoe_1`
   - "Jane Smith" → `testuser_janesmith_1`

### Atomicity Testing

The `test_concurrent_collision_scenario` validates that the `COALESCE(MAX(sequence_number), 0) + 1` query prevents race conditions when multiple contacts are created rapidly.

## Troubleshooting

### Import Errors

If you see `Import "pytest" could not be resolved`:
- This is expected when pytest is not installed
- Activate virtual environment and install dependencies

### Database Errors

If you see SQLite errors:
- Tests use temporary databases created per test
- No cleanup required - temp files are auto-deleted

### Path Issues

Tests assume the following structure:
```
webapp/
├── src/
│   ├── utils/contact_utils.py
│   ├── services/storage_service.py
│   └── models/__init__.py
└── tests/
    └── unit/
        ├── test_contact_utils.py
        └── test_storage_service.py
```

## Feature Documentation

See parent directory: `/specs/001-refine-memory-producer-logic/`
- `tasks.md` - Implementation checklist (T021, T022)
- `plan.md` - Technical implementation details
- `spec.md` - User stories and acceptance criteria