beads/tests/integration/README.md

Integration Tests

This directory contains integration tests for bd (beads) that test end-to-end functionality.

Tests

test_agent_race.py

Multi-agent race condition test that validates collision prevention with Agent Mail.

What it tests:

• Multiple agents simultaneously attempting to claim the same issue
• WITH Agent Mail: Only one agent succeeds (via reservation)
• WITHOUT Agent Mail: Multiple agents may succeed (collision)
• Verification via JSONL that no duplicate claims occur

test_mail_failures.py

Agent Mail server failure scenarios test that validates graceful degradation.

What it tests:

• Server never started (connection refused)
• Server crashes during operation
• Network partition (timeout)
• Server returns 500 errors
• Invalid bearer token (401)
• Malformed JSON responses
• JSONL consistency under multiple failures

Performance:

• Uses --no-daemon flag for fast tests (~33s total)
• 1s HTTP timeouts for quick failure detection
• Mock HTTP server avoids real network calls

test_reservation_ttl.py

Reservation TTL and expiration test that validates time-based reservation behavior.

What it tests:

• Short TTL reservations (30s)
• Reservation blocking verification (agent2 cannot claim while agent1 holds reservation)
• Auto-release after expiration (expired reservations become available)
• Renewal/heartbeat mechanism (re-reserving extends expiration)

Performance:

• Uses --no-daemon flag for fast tests
• 30s TTL for expiration tests (includes wait time)
• Total test time: ~57s (includes 30s+ waiting for expiration)
• Mock HTTP server with full TTL management

Prerequisites

• bd installed: go install github.com/steveyegge/beads/cmd/bd@latest
• Agent Mail server running (optional, for full test suite):

  cd ~/src/mcp_agent_mail
  source .venv/bin/activate
  uv run python -m mcp_agent_mail.cli serve-http
  

Running Tests

Run test_agent_race.py:

python3 tests/integration/test_agent_race.py

Run test_mail_failures.py:

python3 tests/integration/test_mail_failures.py

Run test_reservation_ttl.py:

python3 tests/integration/test_reservation_ttl.py

Run all integration tests:

python3 tests/integration/test_agent_race.py
python3 tests/integration/test_mail_failures.py
python3 tests/integration/test_reservation_ttl.py

Expected Results

test_agent_race.py

• WITH Agent Mail running: Test 1 passes (only 1 claim), Test 2 shows collision, Test 3 passes
• WITHOUT Agent Mail running: All tests demonstrate collision (expected behavior without reservation system)

test_mail_failures.py

• All 7 tests should pass in ~30-35 seconds
• Each test validates graceful degradation to Beads-only mode
• JSONL remains consistent across all failure scenarios

test_reservation_ttl.py

• All 4 tests should pass in ~57 seconds
• Tests verify TTL-based reservation expiration and renewal
• Includes 30s+ wait time to validate actual expiration behavior

Adding New Tests

Integration tests should:

1. Use temporary workspaces (cleaned up automatically)
2. Test real bd CLI commands, not just internal APIs
3. Use --no-daemon flag for fast execution
4. Verify behavior in .beads/issues.jsonl when relevant
5. Clean up resources in finally blocks
6. Provide clear output showing what's being tested