zeroclaw/TESTING_TELEGRAM.md

Telegram Integration Testing Guide

This guide covers testing the Telegram channel integration for ZeroClaw.

🚀 Quick Start

Automated Tests

# Full test suite (20+ tests, ~2 minutes)
./test_telegram_integration.sh

# Quick smoke test (~10 seconds)
./quick_test.sh

# Just unit tests
cargo test telegram --lib

📋 Test Coverage

Automated Tests (20 tests)

The test_telegram_integration.sh script runs:

Phase 1: Code Quality (5 tests)

• ✅ Test compilation
• ✅ Unit tests (24 tests)
• ✅ Message splitting tests (8 tests)
• ✅ Clippy linting
• ✅ Code formatting

Phase 2: Build Tests (3 tests)

• ✅ Debug build
• ✅ Release build
• ✅ Binary size verification (<10MB)

Phase 3: Configuration Tests (4 tests)

• ✅ Config file exists
• ✅ Telegram section configured
• ✅ Bot token set
• ✅ User allowlist configured

Phase 4: Health Check Tests (2 tests)

• ✅ Health check timeout (<5s)
• ✅ Telegram API connectivity

Phase 5: Feature Validation (6 tests)

• ✅ Message splitting function
• ✅ Message length constant (4096)
• ✅ Timeout implementation
• ✅ chat_id validation
• ✅ Duration import
• ✅ Continuation markers

Manual Tests (6 tests)

After running automated tests, perform these manual checks:

1. Basic messaging

   zeroclaw channel start
   

   • Send "Hello bot!" in Telegram
   • Verify response within 3 seconds

2. Long message splitting

   # Generate 5000+ char message
   python3 -c 'print("test " * 1000)'
   

   • Paste into Telegram
   • Verify: Message split into chunks
   • Verify: Markers show (continues...) and (continued)
   • Verify: All chunks arrive in order

3. Unauthorized user blocking

   # Edit ~/.zeroclaw/config.toml
   allowed_users = ["999999999"]
   

   • Send message to bot
   • Verify: Warning in logs
   • Verify: Message ignored
   • Restore correct user ID

4. Rate limiting

   • Send 10 messages rapidly
   • Verify: All processed
   • Verify: No "Too Many Requests" errors
   • Verify: Responses have delays

5. Mention-only mode (group chats)

   # Edit ~/.zeroclaw/config.toml
   [channels.telegram]
   mention_only = true
   

   • Add bot to a group chat
   • Send message without @botname mention
   • Verify: Bot does not respond
   • Send message with @botname mention
   • Verify: Bot responds and mention is stripped
   • DM/private chat should always work regardless of mention_only

6. Error logging

   RUST_LOG=debug zeroclaw channel start
   

   • Check for unexpected errors
   • Verify proper error handling

7. Health check timeout

   time zeroclaw channel doctor
   

   • Verify: Completes in <5 seconds

🔍 Test Results Interpretation

Success Criteria

• All 20 automated tests pass ✅
• Health check completes in <5s ✅
• Binary size <10MB ✅
• No clippy warnings ✅
• All manual tests pass ✅

Common Issues

Issue: Health check times out

Solution: Check bot token is valid
  curl "https://api.telegram.org/bot<TOKEN>/getMe"

Issue: Bot doesn't respond

Solution: Check user allowlist
  1. Send message to bot
  2. Check logs for user_id
  3. Update config: allowed_users = ["YOUR_ID"]
  4. Run: zeroclaw onboard --channels-only

Issue: Message splitting not working

Solution: Verify code changes
  grep -n "split_message_for_telegram" src/channels/telegram.rs
  grep -n "TELEGRAM_MAX_MESSAGE_LENGTH" src/channels/telegram.rs

🧪 Test Scenarios

Scenario 1: First-Time Setup

# 1. Run automated tests
./test_telegram_integration.sh

# 2. Configure Telegram
zeroclaw onboard --interactive
# Select Telegram channel
# Enter bot token (from @BotFather)
# Enter your user ID

# 3. Verify health
zeroclaw channel doctor

# 4. Start channel
zeroclaw channel start

# 5. Send test message in Telegram

Scenario 2: After Code Changes

# 1. Quick validation
./quick_test.sh

# 2. Full test suite
./test_telegram_integration.sh

# 3. Manual smoke test
zeroclaw channel start
# Send message in Telegram

Scenario 3: Production Deployment

# 1. Full test suite
./test_telegram_integration.sh

# 2. Load test (optional)
# Send 100 messages rapidly
for i in {1..100}; do
  echo "Test message $i" | \
    curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
         -d "chat_id=<CHAT_ID>" \
         -d "text=Message $i"
done

# 3. Monitor logs
RUST_LOG=info zeroclaw daemon

# 4. Check metrics
zeroclaw status

📊 Performance Benchmarks

Expected values after all fixes:

Metric	Expected	How to Measure
Health check time	<5s	time zeroclaw channel doctor
First response time	<3s	Time from sending to receiving
Message split overhead	<50ms	Check logs for timing
Memory usage	<10MB	ps aux | grep zeroclaw
Binary size	~3-4MB	ls -lh target/release/zeroclaw
Unit test coverage	61/61 pass	cargo test telegram --lib

🐛 Debugging Failed Tests

Debug Unit Tests

# Verbose output
cargo test telegram --lib -- --nocapture

# Specific test
cargo test telegram_split_over_limit -- --nocapture

# Show ignored tests
cargo test telegram --lib -- --ignored

Debug Integration Issues

# Maximum logging
RUST_LOG=trace zeroclaw channel start

# Check Telegram API directly
curl "https://api.telegram.org/bot<TOKEN>/getMe"
curl "https://api.telegram.org/bot<TOKEN>/getUpdates"

# Validate config
cat ~/.zeroclaw/config.toml | grep -A 3 "\[channels_config.telegram\]"

Debug Build Issues

# Clean build
cargo clean
cargo build --release

# Check dependencies
cargo tree | grep telegram

# Update dependencies
cargo update

🎯 CI/CD Integration

Add to your CI pipeline:

# .github/workflows/test.yml
name: Test Telegram Integration

on: [push, pull_request]

jobs:
  test:
    runs-on: blacksmith-2vcpu-ubuntu-2404
    steps:
      - uses: actions/checkout@v3
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - name: Run tests
        run: |
          cargo test telegram --lib
          cargo clippy --all-targets -- -D warnings
      - name: Check formatting
        run: cargo fmt --check

📝 Test Checklist

Before merging code:

• ./quick_test.sh passes
• ./test_telegram_integration.sh passes
• Manual tests completed
• No new clippy warnings
• Code is formatted (cargo fmt)
• Documentation updated
• CHANGELOG.md updated

🚨 Emergency Rollback

If tests fail in production:

# 1. Check git history
git log --oneline src/channels/telegram.rs

# 2. Rollback to previous version
git revert <commit-hash>

# 3. Rebuild
cargo build --release

# 4. Restart service
zeroclaw service restart

# 5. Verify
zeroclaw channel doctor

📚 Additional Resources

• Telegram Bot API Documentation
• ZeroClaw Main README
• Contributing Guide
• Issue Tracker