TDD — Test-Driven Development (Enforced)

This is not a suggestion. This is the workflow.

When adding features or fixing bugs in claude-code-discord-bridge, you MUST write tests before writing implementation code. No exceptions.

When to Activate

• Adding any new feature or functionality
• Fixing a bug (write a test that reproduces the bug FIRST)
• Refactoring code (ensure existing tests pass, add missing ones)
• Adding a new Cog, parser rule, UI component, or database operation

The Cycle: RED → GREEN → REFACTOR

Step 1: RED — Write Failing Tests

Write tests that describe the desired behavior. Run them. They must fail.

uv run pytest tests/test_new_feature.py -v
# Expected: FAILED (because the code doesn't exist yet)

If tests pass before you write any implementation, your tests are wrong.

Step 2: GREEN — Write Minimal Implementation

Write the minimum code to make the tests pass. No more.

uv run pytest tests/test_new_feature.py -v
# Expected: PASSED

Step 3: REFACTOR — Clean Up

Improve the implementation while keeping all tests green. Then run the full suite:

uv run pytest tests/ -v --cov=claude_discord --cov-report=term-missing

Step 4: VERIFY — Lint + Format + Full Suite

uv run ruff check claude_discord/
uv run ruff format claude_discord/
uv run pytest tests/ -v --cov=claude_discord

What to Test First (by module type)

New Parser Rule

# tests/test_parser.py — Write THIS first
def test_parse_new_event_type():
    line = '{"type":"new_type","data":"value"}'
    event = parse_line(line)
    assert event is not None
    assert event.message_type == MessageType.ASSISTANT

def test_parse_new_event_type_missing_data():
    line = '{"type":"new_type"}'
    event = parse_line(line)
    assert event is not None  # Should handle gracefully

# THEN implement in claude_discord/claude/parser.py

New Cog Command

# tests/test_new_cog.py — Write THIS first
from unittest.mock import AsyncMock, MagicMock

def test_rejects_unauthorized_user():
    cog = MyCog(bot=MagicMock(), allowed_user_ids={111})
    assert cog._is_authorized(999) is False

def test_accepts_authorized_user():
    cog = MyCog(bot=MagicMock(), allowed_user_ids={111})
    assert cog._is_authorized(111) is True

def test_validates_input_format():
    # Test that invalid input is rejected before reaching CLI
    assert not re.match(r"^[\w-]+$", "invalid; rm -rf /")

# THEN implement in claude_discord/cogs/my_cog.py

New Chunker Behavior

# tests/test_chunker.py — Write THIS first
def test_chunk_with_nested_code_blocks():
    text = "```python\n```nested```\n```"
    chunks = chunk_message(text)
    # Verify code blocks are not broken
    for chunk in chunks:
        assert chunk.count("```") % 2 == 0  # Even number = balanced

def test_chunk_unicode_content():
    text = "日本語テスト 🎉" * 500
    chunks = chunk_message(text)
    assert all(len(c.encode("utf-8")) <= 8000 for c in chunks)

# THEN implement the fix in claude_discord/discord_ui/chunker.py

Bug Fix

# tests/test_bug_123.py — Write THIS first
def test_session_id_with_uppercase_rejected():
    """Bug #123: Session IDs with uppercase hex were accepted."""
    runner = ClaudeRunner()
    with pytest.raises(ValueError):
        runner._build_args("hello", session_id="ABC-DEF")

# Confirm the test FAILS with current code
# THEN fix the regex in runner.py
# THEN confirm the test PASSES

Database Operation

# tests/test_repository.py — Write THIS first
async def test_save_overwrites_existing(repo):
    await repo.save(thread_id=123, session_id="old-id")
    await repo.save(thread_id=123, session_id="new-id")
    result = await repo.get_session_id(thread_id=123)
    assert result == "new-id"

async def test_concurrent_saves(repo):
    import asyncio
    tasks = [
        repo.save(thread_id=i, session_id=f"session-{i}")
        for i in range(100)
    ]
    await asyncio.gather(*tasks)
    # All should succeed without errors

# THEN implement or verify in claude_discord/database/repository.py

Coverage Requirements

Anti-Patterns (Don't Do This)

Writing implementation first, tests later

❌ "I'll write the code first and add tests after"
✅ "I'll write the test first, watch it fail, then implement"

Testing implementation details

# ❌ Bad: Testing internal state
assert runner._process is not None

# ✅ Good: Testing observable behavior
args = runner._build_args("hello", None)
assert args[-1] == "hello"

Skipping the RED step

❌ Writing a test that passes immediately
✅ Writing a test, running it, confirming it FAILS, then implementing

Over-mocking

# ❌ Bad: Mocking everything
mock_everything = MagicMock()
result = function_under_test(mock_everything)
# What are you even testing?

# ✅ Good: Mock only external boundaries
real_runner = ClaudeRunner(command="claude")
args = real_runner._build_args("test prompt", None)
assert "--" in args

Quick Reference

# Run specific test file
uv run pytest tests/test_parser.py -v

# Run specific test
uv run pytest tests/test_parser.py::test_parse_system_message -v

# Run with coverage
uv run pytest tests/ -v --cov=claude_discord --cov-report=term-missing

# Stop on first failure
uv run pytest tests/ -x

# Show local variables on failure
uv run pytest tests/ -v --tb=short -l