Skip to content

testing.md

Latest commit

 

History

History
310 lines (243 loc) · 7.64 KB

testing.md

File metadata and controls

310 lines (243 loc) · 7.64 KB

Testing Documentation

This document provides comprehensive information about testing the Lunar MCP Server, including test scripts, coverage, and methodologies.

Overview

The Lunar MCP Server includes a comprehensive test suite that validates:

  • MCP protocol compliance and STDIO communication
  • All 15 available tools across multiple categories
  • Error handling and edge cases
  • Multi-cultural support (Chinese, Islamic, Hindu, Western)
  • Real-world usage scenarios

Test Scripts

All test scripts are located in the ./scripts/ directory and are designed to test the MCP server in STDIO mode without requiring external dependencies.

Main Test Scripts

test_mcp_final.sh (Recommended)

Comprehensive test suite with full coverage

./scripts/test_mcp_final.sh

Features:

  • ✅ Server startup and STDIO handling verification
  • ✅ MCP protocol initialization testing
  • ✅ Complete tool listing with categorization
  • ✅ All 15 tools tested with realistic parameters
  • ✅ Error handling validation (invalid tools, missing parameters)
  • ✅ Multi-cultural context testing
  • ✅ Detailed reporting with color-coded output

Test Categories:

  1. Auspicious/Fortune Tools (4 tools)

    • check_auspicious_date - Wedding date validation
    • find_good_dates - Business opening date search
    • get_daily_fortune - Daily fortune information
    • check_zodiac_compatibility - Zodiac compatibility analysis

  2. Festival Tools (4 tools)

    • get_lunar_festivals - Festival lookup for specific dates
    • get_next_festival - Upcoming festival discovery
    • get_festival_details - Detailed festival information
    • get_annual_festivals - Complete yearly festival calendar

  3. Moon/Lunar Tools (4 tools)

    • get_moon_phase - Current moon phase calculation
    • get_moon_calendar - Monthly moon phase calendar
    • get_moon_influence - Moon's influence on activities
    • predict_moon_phases - Future moon phase predictions

  4. Calendar Conversion Tools (3 tools)

    • solar_to_lunar - Solar to lunar date conversion
    • lunar_to_solar - Lunar to solar date conversion
    • get_zodiac_info - Zodiac information retrieval

test_mcp_simple.sh

Basic functionality test

./scripts/test_mcp_simple.sh

Features:

  • Quick server startup verification
  • Basic tool execution testing
  • Minimal dependency validation
  • Fast execution (< 30 seconds)

test_mcp_server.sh

Advanced FIFO-based testing

./scripts/test_mcp_server.sh

Features:

  • FIFO-based server communication
  • Background server process management
  • Concurrent request handling
  • Advanced cleanup mechanisms

test_mcp_comprehensive.py

Python-based test implementation

uv run python ./scripts/test_mcp_comprehensive.py

Features:

  • Native Python MCP client implementation
  • Asynchronous server communication
  • Detailed response validation
  • Object-oriented test structure

Test Output Interpretation

Success Indicators

✅ Server handles STDIO correctly
✅ Server responds to initialization
✅ Server can list tools
✅ All comprehensive tests passed!

Test Categories Summary

=== Comprehensive Test Summary ===
Total comprehensive tests: 15/15
Cultural contexts tested: 4/4

Category breakdown:
  - Auspicious/Fortune: 4/4
  - Festival: 4/4
  - Moon/Lunar: 4/4
  - Calendar Conversion: 3/3

Error Handling Validation

✅ Server correctly handles invalid tool name
✅ Server correctly handles missing parameters
✅ chinese culture works
✅ islamic culture works
✅ hindu culture works
✅ western culture works

Common Test Scenarios

1. Tool Parameter Validation

The test suite validates tools with realistic parameters:

// Auspicious date checking
{
  "date": "2024-01-01",
  "activity": "wedding",
  "culture": "chinese"
}

// Moon phase analysis
{
  "date": "2024-01-01",
  "location": "0,0"
}

// Festival lookup
{
  "date": "2024-02-10",
  "culture": "chinese"
}

2. Error Condition Testing

Tests verify proper error handling for:

  • Invalid tool names: Returns structured error with tool name
  • Missing required parameters: Validates input schema
  • Malformed requests: Proper JSON-RPC error responses

3. Cultural Context Validation

Each cultural tradition is tested:

  • Chinese: Traditional lunar calendar and zodiac
  • Islamic: Hijri calendar system
  • Hindu: Panchang calendar system
  • Western: Modern astrological system

Performance Considerations

Test Execution Times

  • Complete suite: ~2-3 minutes
  • Simple test: ~30 seconds
  • Individual tool: ~5-10 seconds per tool

Resource Usage

  • Memory: Minimal (< 50MB during testing)
  • CPU: Light (server startup and JSON processing)
  • Network: None (local STDIO communication)

Troubleshooting

Common Issues

Server Startup Failures

❌ Server failed to start (exit code: 1)

Solutions:

  • Verify uv installation: uv --version
  • Check dependencies: uv sync --dev
  • Validate environment: uv run python --version

Tool Execution Errors

❌ tool_name failed
Response: {"error": "...", "tool": "tool_name"}

Solutions:

  • Check parameter format and required fields
  • Validate date formats (YYYY-MM-DD)
  • Ensure cultural context is supported

Timeout Issues

❌ No response received

Solutions:

  • Increase timeout values in test script
  • Check system resources
  • Verify server process isn't hanging

Debug Mode

For detailed debugging, modify test scripts to show full responses:

# Add debug output to test scripts
echo "Full response: $RESPONSE"

Or run individual tools manually:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_moon_phase","arguments":{"date":"2024-01-01"}}}' | uv run lunar-mcp-server

Contributing to Tests

Adding New Test Cases

  1. Identify test category (Auspicious, Festival, Moon, Conversion)
  2. Define realistic parameters based on tool schema
  3. Add to appropriate test section in test_mcp_final.sh
  4. Verify with manual testing before committing

Test Script Structure

# Test function template
test_single_tool() {
    local tool_name="$1"
    local args="$2"
    local desc="$3"

    # Create MCP request
    cat > test.json << EOF
    {"jsonrpc":"2.0","id":1,"method":"initialize",...}
    {"jsonrpc":"2.0","method":"notifications/initialized"}
    {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"$tool_name","arguments":$args}}
EOF

    # Execute and validate
    response=$(cat test.json | timeout 15s uv run lunar-mcp-server 2>/dev/null | tail -1)

    if echo "$response" | grep -q '"result"'; then
        echo "✅ $tool_name works"
        return 0
    else
        echo "❌ $tool_name failed"
        return 1
    fi
}

Integration with CI/CD

GitHub Actions Example

name: MCP Server Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v2
      - name: Install dependencies
        run: uv sync --dev
      - name: Run MCP tests
        run: ./scripts/test_mcp_final.sh

Test Automation

For automated testing environments:

# Run tests with machine-readable output
./scripts/test_mcp_final.sh 2>&1 | tee test_results.log

# Parse results
if grep -q "All comprehensive tests passed" test_results.log; then
    echo "Tests passed"
    exit 0
else
    echo "Tests failed"
    exit 1
fi

This comprehensive testing approach ensures the Lunar MCP Server maintains high quality and reliability across all supported features and cultural contexts.