Integration Test Skill

Run comprehensive integration tests for telclaude without manual Telegram interaction.

When to Use

Invoke this skill after modifying:

• SDK client code (src/sdk/)
• Session management (src/sdk/session-manager.ts)
• Skill loading or any SKILL.md files
• Network proxy configuration
• Voice/TTS functionality (src/services/tts.ts)
• Image generation (src/services/image-generation.ts)
• Telegram media handling (src/telegram/media-detection.ts)

Quick Start

# Run all integration tests
telclaude integration-test --all

# Specific tests
telclaude integration-test --echo      # Basic SDK communication
telclaude integration-test --env       # Environment variable passing
telclaude integration-test --network   # Network proxy verification
telclaude integration-test --image     # Image generation (needs OPENAI_API_KEY)
telclaude integration-test --voice     # Voice message response (needs OPENAI_API_KEY)

# Verbose output for debugging
telclaude integration-test --all -v

# Custom timeout (default 120s)
telclaude integration-test --timeout 180000

Test Descriptions

Echo Test (--echo)

Verifies basic SDK sandbox communication:

• Sends a simple bash command through the SDK
• Confirms output is returned correctly
• Tests: sandbox initialization, tool execution
• Expected: Output contains INTEGRATION_TEST_OK

Environment Test (--env)

Verifies environment variables pass into sandbox:

• Checks if OPENAI_API_KEY is accessible inside sandbox
• Falls back to checking HOME if no API key
• Tests: env injection, security boundaries

Network Test (--network)

Verifies network proxy configuration:

• Tests HTTP_PROXY environment in sandbox
• Makes actual HTTPS request through proxy to api.openai.com
• Tests: proxy chain, DNS resolution, firewall rules
• Passes even with 401 (means network worked)

Image Test (--image)

Verifies image generation end-to-end:

• Calls OpenAI image API from within sandbox
• Saves generated image to disk
• Tests: API connectivity, file I/O, skill execution
• Skips if OPENAI_API_KEY not configured

Voice Test (--voice)

Critical test for voice message compliance:

Simulates receiving a voice message and validates Claude follows TTS skill rules:

1. Uses --voice-message flag - Required for Telegram waveform display
2. Output in /voice/ directory - Not /tts/
3. Format is .ogg - Not .mp3
4. Minimal text output - Path only, no "I've generated..."

This catches the common failure mode where Claude ignores skill instructions and outputs verbose text with wrong format.

Interpreting Results

Success

── Echo Test ──
  ✓ Echo via SDK (1234ms)

── Voice Message Response Test ──
  ✓ Voice message response (12345ms)

── Summary ──
✓ All 5 tests passed

Voice Test Failures

Wrong format (common issue):

⚠ Voice message response: Generated audio but with issues
  • Missing --voice-message flag
  • Wrong directory: used /tts/ instead of /voice/
  • Wrong format: used .mp3 instead of .ogg
  • Excessive text in response (should be path only)

This means Claude generated audio but didn't follow the skill instructions. Check that:

1. Skills are loaded from ~/.claude/skills/ (user level)
2. No conflicting skills in workspace .claude/skills/
3. Session was reset after skill update

Common Issues

Running in Docker

# On Docker host (e.g., raspi4)
docker exec telclaude telclaude integration-test --all -v

# Just voice test
docker exec telclaude telclaude integration-test --voice -v

# Check what skills are loaded
docker exec telclaude ls -la ~/.claude/skills/

Debugging Tips

1. Run with -v to see streaming output from SDK
2. Check logs: docker logs telclaude --tail 50
3. Verify skills: docker exec telclaude cat ~/.claude/skills/text-to-speech/SKILL.md | head -30
4. Run doctor: telclaude doctor --network --secrets

Files Involved

• src/commands/integration-test.ts - Test implementation
• src/sdk/client.ts - SDK query execution
• .claude/skills/text-to-speech/SKILL.md - TTS skill rules (voice test validates these)
• .claude/skills/integration-test/SKILL.md - This skill