integration-test

Full SDK integration test that runs actual queries through the Claude SDK sandbox. Use after making changes to SDK client code, session management, skill loading, network proxy, voice/TTS, or image generation. Runs real prompts through the SDK to verify the complete path works.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive integration testing framework designed to validate the end-to-end functionality of the Claude SDK sandbox. It automates the verification of critical components including session management, network proxy configurations, and media processing (Voice/TTS and Image generation), ensuring that code changes do not break core agent capabilities or platform-specific compliance rules.

Use Cases

  • Regression Testing: Run a full suite of automated tests after modifying SDK client code or session management to ensure core communication paths remain intact.
  • Environment & Network Validation: Verify that network proxies, DNS resolution, and environment variable injections (like API keys) are correctly configured within the sandbox environment.
  • Media Workflow Compliance: Automatically validate that Voice/TTS outputs adhere to specific technical requirements, such as .ogg formatting and correct directory structures for Telegram integration.
  • Third-Party API Integration: Test the connectivity and functional execution of external services like OpenAI's image generation from within the agent's restricted sandbox.
  • CI/CD Automation: Incorporate these tests into deployment pipelines to catch common failure modes in voice message handling or skill loading before they reach production.
nameintegration-test
descriptionFull SDK integration test that runs actual queries through the Claude SDK sandbox. Use after making changes to SDK client code, session management, skill loading, network proxy, voice/TTS, or image generation. Runs real prompts through the SDK to verify the complete path works.

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

Issue Cause Fix
Echo timeout SDK sandbox not starting Check bubblewrap/seatbelt installed
Env var not set Key not injected Verify OPENAI_API_KEY in environment
Network failure Proxy misconfigured Check firewall rules, allowed domains
Image skipped No API key Run telclaude setup-openai
Voice wrong format Skill not loaded Verify ~/.claude/skills/text-to-speech/ exists
Voice extra text Old skill cached Restart container, check skill content

Running in Docker

# On Docker host
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