Skip to content

Latest commit

 

History

History
355 lines (256 loc) · 7.46 KB

TESTING_TELEGRAM.md

File metadata and controls

355 lines (256 loc) · 7.46 KB

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
    • Regression check (group non-text): verify group media without mention does not trigger bot reply
    • Regression command: cargo test -q telegram_mention_only_group_photo_without_caption_is_ignored

  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: [self-hosted, aws-india]
    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