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

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

# 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

# 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