tsikol 0.1.0

data/docs/guides/testing.md

@@ -0,0 +1,863 @@
+# Testing Guide
+
+Comprehensive testing ensures your MCP server works correctly and reliably. Tsikol provides test helpers and patterns for testing tools, resources, prompts, and complete server interactions.
+
+## Table of Contents
+
+1. [Test Setup](#test-setup)
+2. [Testing Tools](#testing-tools)
+3. [Testing Resources](#testing-resources)
+4. [Testing Prompts](#testing-prompts)
+5. [Testing Middleware](#testing-middleware)
+6. [Integration Testing](#integration-testing)
+7. [Test Helpers](#test-helpers)
+8. [Best Practices](#best-practices)
+
+## Test Setup
+
+### Basic Test Structure
+
+```ruby
+# test/test_helper.rb
+require 'minitest/autorun'
+require 'tsikol'
+require 'tsikol/test_helpers'
+
+# Load your server components
+Dir.glob('app/**/*.rb').each { |file| require_relative "../#{file}" }
+
+class TsikolTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = Tsikol::Server.new(name: "test-server")
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+  end
+  
+  def teardown
+    # Clean up resources if needed
+  end
+end
+```
+
+### Test Directory Structure
+
+```
+test/
+├── test_helper.rb
+├── tools/
+│   ├── file_manager_test.rb
+│   └── database_query_test.rb
+├── resources/
+│   ├── system_status_test.rb
+│   └── config_test.rb
+├── prompts/
+│   └── assistant_test.rb
+├── middleware/
+│   └── auth_middleware_test.rb
+└── integration/
+    └── server_test.rb
+```
+
+## Testing Tools
+
+### Basic Tool Test
+
+```ruby
+# test/tools/calculator_test.rb
+require_relative '../test_helper'
+
+class CalculatorTest < TsikolTest
+  def setup
+    super
+    @server.register_tool_instance(Calculator.new)
+    @client.initialize_connection
+  end
+  
+  def test_addition
+    response = @client.call_tool("calculator", {
+      "operation" => "add",
+      "a" => 5,
+      "b" => 3
+    })
+    
+    assert_successful_response(response)
+    assert_equal 8, response.dig(:result, :content, 0, :text).to_i
+  end
+  
+  def test_division_by_zero
+    response = @client.call_tool("calculator", {
+      "operation" => "divide",
+      "a" => 10,
+      "b" => 0
+    })
+    
+    assert_error_response(response)
+    assert_match /division by zero/i, response[:error][:message]
+  end
+  
+  def test_invalid_operation
+    response = @client.call_tool("calculator", {
+      "operation" => "invalid",
+      "a" => 1,
+      "b" => 2
+    })
+    
+    assert_error_response(response)
+  end
+end
+```
+
+### Testing Tool Parameters
+
+```ruby
+class FileManagerTest < TsikolTest
+  def test_required_parameters
+    # Missing required parameter
+    response = @client.call_tool("file_manager", {
+      "operation" => "read"
+      # Missing "path" parameter
+    })
+    
+    assert_error_response(response, -32602)
+    assert_match /path.*required/i, response[:error][:message]
+  end
+  
+  def test_parameter_types
+    # Wrong parameter type
+    response = @client.call_tool("file_manager", {
+      "path" => 123,  # Should be string
+      "operation" => "read"
+    })
+    
+    assert_error_response(response, -32602)
+    assert_match /must be.*string/i, response[:error][:message]
+  end
+  
+  def test_enum_validation
+    response = @client.call_tool("file_manager", {
+      "path" => "test.txt",
+      "operation" => "invalid_op"
+    })
+    
+    assert_error_response(response, -32602)
+    assert_match /must be one of/i, response[:error][:message]
+  end
+end
+```
+
+### Testing Tool Completions
+
+```ruby
+class CompletionTest < TsikolTest
+  def setup
+    super
+    @server.completion true
+    @server.register_tool_instance(GitTool.new)
+    @client.initialize_connection
+  end
+  
+  def test_branch_completion
+    response = @client.complete(
+      { type: "ref/tool", name: "git_tool" },
+      { name: "branch", value: "fea" }
+    )
+    
+    assert_successful_response(response)
+    
+    values = response.dig(:result, :completion, :values)
+    assert values.include?("feature")
+    assert values.include?("feature/new-ui")
+    refute values.include?("main")  # Doesn't start with "fea"
+  end
+  
+  def test_context_aware_completion
+    response = @client.complete(
+      { type: "ref/tool", name: "database_query" },
+      { name: "column", value: "u" },
+      { table: "users" }  # Context from other parameter
+    )
+    
+    assert_successful_response(response)
+    
+    values = response.dig(:result, :completion, :values)
+    assert values.include?("user_id")
+    assert values.include?("username")
+    refute values.include?("post_id")  # From different table
+  end
+end
+```
+
+### Testing Async Tools
+
+```ruby
+class AsyncToolTest < TsikolTest
+  def test_async_execution
+    response = @client.call_tool("async_processor", {
+      "data" => "test data",
+      "callback_url" => "http://example.com/callback"
+    })
+    
+    assert_successful_response(response)
+    
+    result = JSON.parse(response.dig(:result, :content, 0, :text))
+    assert result["job_id"]
+    assert_equal "processing", result["status"]
+    
+    # Wait for async processing
+    sleep(0.1)
+    
+    # Verify callback was made (mock or check logs)
+  end
+end
+```
+
+## Testing Resources
+
+### Basic Resource Test
+
+```ruby
+# test/resources/system_status_test.rb
+class SystemStatusTest < TsikolTest
+  def setup
+    super
+    @server.register_resource_instance(SystemStatus.new)
+    @client.initialize_connection
+  end
+  
+  def test_read_status
+    response = @client.read_resource("system/status")
+    
+    assert_successful_response(response)
+    
+    content = response.dig(:result, :contents, 0, :text)
+    data = JSON.parse(content)
+    
+    assert data["status"]
+    assert data["uptime"]
+    assert data["version"]
+    assert data["timestamp"]
+  end
+  
+  def test_resource_not_found
+    response = @client.read_resource("nonexistent/resource")
+    
+    assert_error_response(response, -32002)
+    assert_match /resource not found/i, response[:error][:message]
+  end
+end
+```
+
+### Testing Dynamic Resources
+
+```ruby
+class DynamicResourceTest < TsikolTest
+  def test_real_time_updates
+    # Read resource twice
+    response1 = @client.read_resource("metrics/live")
+    sleep(0.1)
+    response2 = @client.read_resource("metrics/live")
+    
+    data1 = JSON.parse(response1.dig(:result, :contents, 0, :text))
+    data2 = JSON.parse(response2.dig(:result, :contents, 0, :text))
+    
+    # Timestamps should differ
+    refute_equal data1["timestamp"], data2["timestamp"]
+    
+    # Some metrics might change
+    refute_equal data1["requests_count"], data2["requests_count"]
+  end
+end
+```
+
+### Testing Cached Resources
+
+```ruby
+class CachedResourceTest < TsikolTest
+  def test_caching_behavior
+    # Measure first call (cache miss)
+    start = Time.now
+    response1 = @client.read_resource("expensive/data")
+    duration1 = Time.now - start
+    
+    # Measure second call (cache hit)
+    start = Time.now
+    response2 = @client.read_resource("expensive/data")
+    duration2 = Time.now - start
+    
+    # Cache hit should be much faster
+    assert duration2 < duration1 / 10
+    
+    # Content should be identical
+    assert_equal(
+      response1.dig(:result, :contents, 0, :text),
+      response2.dig(:result, :contents, 0, :text)
+    )
+  end
+  
+  def test_cache_expiration
+    response1 = @client.read_resource("cached/data")
+    
+    # Wait for cache to expire
+    sleep(cache_ttl + 0.1)
+    
+    response2 = @client.read_resource("cached/data")
+    
+    # Should have new timestamp
+    data1 = JSON.parse(response1.dig(:result, :contents, 0, :text))
+    data2 = JSON.parse(response2.dig(:result, :contents, 0, :text))
+    
+    refute_equal data1["generated_at"], data2["generated_at"]
+  end
+end
+```
+
+## Testing Prompts
+
+### Basic Prompt Test
+
+```ruby
+# test/prompts/code_assistant_test.rb
+class CodeAssistantTest < TsikolTest
+  def setup
+    super
+    @server.register_prompt_instance(CodeAssistant.new)
+    @client.initialize_connection
+  end
+  
+  def test_get_prompt
+    response = @client.get_prompt("code_assistant", {
+      "language" => "ruby",
+      "task" => "write unit tests"
+    })
+    
+    assert_successful_response(response)
+    
+    messages = response.dig(:result, :messages)
+    assert messages.is_a?(Array)
+    assert messages.length >= 2
+    
+    # Check system message
+    system_msg = messages.find { |m| m[:role] == "system" }
+    assert system_msg
+    assert_match /ruby/i, system_msg[:content][:text]
+    
+    # Check user message
+    user_msg = messages.find { |m| m[:role] == "user" }
+    assert user_msg
+    assert_match /unit tests/i, user_msg[:content][:text]
+  end
+  
+  def test_optional_arguments
+    response = @client.get_prompt("code_assistant", {
+      "language" => "python",
+      "task" => "parse JSON"
+      # Omitting optional arguments
+    })
+    
+    assert_successful_response(response)
+  end
+  
+  def test_invalid_enum_value
+    response = @client.get_prompt("code_assistant", {
+      "language" => "cobol",  # Not in enum
+      "task" => "write code"
+    })
+    
+    assert_error_response(response)
+    assert_match /must be one of/i, response[:error][:message]
+  end
+end
+```
+
+### Testing Dynamic Prompts
+
+```ruby
+class DynamicPromptTest < TsikolTest
+  def test_includes_current_context
+    # Mock current data
+    prompt = DataAnalysisPrompt.new
+    prompt.define_singleton_method(:fetch_current_metrics) do
+      { users: 100, revenue: 50000 }
+    end
+    
+    @server.register_prompt_instance(prompt)
+    @client.initialize_connection
+    
+    response = @client.get_prompt("data_analysis", {
+      "query" => "analyze user growth"
+    })
+    
+    messages = response.dig(:result, :messages)
+    
+    # Should include metrics in context
+    context_msg = messages.find { |m| 
+      m[:content][:text].include?("users") && 
+      m[:content][:text].include?("100")
+    }
+    
+    assert context_msg, "Should include current metrics in prompt"
+  end
+end
+```
+
+## Testing Middleware
+
+### Testing Custom Middleware
+
+```ruby
+# test/middleware/auth_middleware_test.rb
+class AuthMiddlewareTest < Minitest::Test
+  def setup
+    @app = MockApp.new
+    @middleware = AuthenticationMiddleware.new(@app, secret_key: "test_secret")
+  end
+  
+  def test_passes_authenticated_requests
+    token = generate_valid_token
+    request = {
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => "tools/call",
+      "params" => { "_token" => token }
+    }
+    
+    response = @middleware.call(request)
+    
+    assert_equal :success, response[:result]
+    assert @app.called?
+    assert_equal "user123", request["authenticated_user"]["user_id"]
+  end
+  
+  def test_rejects_invalid_token
+    request = {
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => "tools/call",
+      "params" => { "_token" => "invalid_token" }
+    }
+    
+    response = @middleware.call(request)
+    
+    assert_equal -32001, response[:error][:code]
+    refute @app.called?
+  end
+  
+  private
+  
+  def generate_valid_token
+    payload = {
+      user_id: "user123",
+      exp: Time.now.to_i + 3600
+    }
+    JWT.encode(payload, "test_secret", 'HS256')
+  end
+end
+
+class MockApp
+  attr_reader :called
+  
+  def call(_request)
+    @called = true
+    { jsonrpc: "2.0", id: 1, result: :success }
+  end
+  
+  def called?
+    @called
+  end
+end
+```
+
+### Testing Middleware Chain
+
+```ruby
+class MiddlewareChainTest < TsikolTest
+  def setup
+    super
+    
+    # Build server with middleware chain
+    @server.use LoggingMiddleware
+    @server.use AuthenticationMiddleware, secret_key: "secret"
+    @server.use RateLimitMiddleware, max_requests: 5
+    
+    @server.register_tool_instance(TestTool.new)
+    @client.initialize_connection
+  end
+  
+  def test_middleware_order
+    # Make authenticated request
+    token = generate_valid_token
+    
+    response = @client.call_tool("test_tool", {
+      "_token" => token,
+      "param" => "value"
+    })
+    
+    assert_successful_response(response)
+    
+    # Verify middleware executed in order
+    # (Check logs, metrics, or other side effects)
+  end
+  
+  def test_middleware_short_circuit
+    # Make request without auth token
+    response = @client.call_tool("test_tool", {
+      "param" => "value"
+    })
+    
+    # Auth middleware should reject before rate limiting
+    assert_error_response(response, -32001)
+  end
+end
+```
+
+## Integration Testing
+
+### Full Server Test
+
+```ruby
+# test/integration/server_test.rb
+class ServerIntegrationTest < TsikolTest
+  def setup
+    # Build complete server
+    @server = Tsikol::Server.new(name: "integration-test")
+    
+    # Add middleware
+    @server.use Tsikol::LoggingMiddleware
+    @server.use Tsikol::ErrorHandlingMiddleware
+    
+    # Register components
+    @server.register_tool_instance(FileManager.new)
+    @server.register_resource_instance(SystemStatus.new)
+    @server.register_prompt_instance(Assistant.new)
+    
+    # Enable features
+    @server.completion true
+    @server.sampling true
+    
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    @client.initialize_connection
+  end
+  
+  def test_full_workflow
+    # 1. Initialize connection
+    response = @client.initialize_connection
+    assert_successful_response(response)
+    
+    capabilities = response.dig(:result, :capabilities)
+    assert capabilities[:tools]
+    assert capabilities[:resources]
+    assert capabilities[:prompts]
+    assert capabilities[:completion]
+    assert capabilities[:sampling]
+    
+    # 2. List tools
+    response = @client.list_tools
+    assert_successful_response(response)
+    
+    tools = response.dig(:result, :tools)
+    assert tools.any? { |t| t[:name] == "file_manager" }
+    
+    # 3. Call a tool
+    response = @client.call_tool("file_manager", {
+      "operation" => "list",
+      "path" => "."
+    })
+    assert_successful_response(response)
+    
+    # 4. Read a resource
+    response = @client.read_resource("system/status")
+    assert_successful_response(response)
+    
+    # 5. Get a prompt
+    response = @client.get_prompt("assistant", {
+      "task" => "help with testing"
+    })
+    assert_successful_response(response)
+  end
+end
+```
+
+### Error Handling Test
+
+```ruby
+class ErrorHandlingTest < TsikolTest
+  def test_handles_tool_errors_gracefully
+    @server.register_tool_instance(FaultyTool.new)
+    @client.initialize_connection
+    
+    response = @client.call_tool("faulty_tool", {
+      "trigger_error" => true
+    })
+    
+    assert_error_response(response)
+    assert response[:error][:message]
+    assert response[:error][:data]  # Should include error details
+  end
+  
+  def test_handles_malformed_requests
+    # Send malformed JSON-RPC request
+    response = @server.handle_request({
+      "id" => 1,
+      "method" => "test"
+      # Missing jsonrpc version
+    })
+    
+    assert_error_response(response, -32600)  # Invalid Request
+  end
+end
+
+class FaultyTool < Tsikol::Tool
+  def execute(trigger_error:)
+    raise "Intentional error" if trigger_error
+    "success"
+  end
+end
+```
+
+## Test Helpers
+
+### Custom Assertions
+
+```ruby
+module CustomAssertions
+  def assert_json_equal(expected, actual)
+    expected_parsed = expected.is_a?(String) ? JSON.parse(expected) : expected
+    actual_parsed = actual.is_a?(String) ? JSON.parse(actual) : actual
+    
+    assert_equal expected_parsed, actual_parsed
+  end
+  
+  def assert_includes_all(collection, items)
+    items.each do |item|
+      assert_includes collection, item
+    end
+  end
+  
+  def assert_response_time(max_ms)
+    start = Time.now
+    yield
+    duration = (Time.now - start) * 1000
+    
+    assert duration < max_ms, 
+           "Response took #{duration.round}ms (max: #{max_ms}ms)"
+  end
+end
+
+class TsikolTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  include CustomAssertions
+end
+```
+
+### Test Fixtures
+
+```ruby
+module TestFixtures
+  def sample_file_content
+    <<~CONTENT
+      This is a test file.
+      It has multiple lines.
+      Used for testing file operations.
+    CONTENT
+  end
+  
+  def sample_json_data
+    {
+      "users" => [
+        { "id" => 1, "name" => "Alice" },
+        { "id" => 2, "name" => "Bob" }
+      ],
+      "metadata" => {
+        "version" => "1.0",
+        "generated_at" => Time.now.iso8601
+      }
+    }
+  end
+  
+  def create_test_file(name, content = sample_file_content)
+    File.write(name, content)
+    
+    # Ensure cleanup after test
+    @files_to_cleanup ||= []
+    @files_to_cleanup << name
+  end
+  
+  def teardown
+    super
+    @files_to_cleanup&.each { |f| File.delete(f) if File.exist?(f) }
+  end
+end
+```
+
+### Mock Helpers
+
+```ruby
+class MockServer < Tsikol::Server
+  attr_accessor :sampling_responses
+  
+  def initialize(name:)
+    super
+    @sampling_responses = []
+  end
+  
+  def sample_text(**params)
+    # Return predefined responses for testing
+    @sampling_responses.shift || { text: "Mock response" }
+  end
+end
+
+# Usage in tests
+def test_tool_with_sampling
+  mock_server = MockServer.new(name: "test")
+  mock_server.sampling_responses = [
+    { text: "Generated code" },
+    { error: "Rate limited" }
+  ]
+  
+  # Test tool behavior with mocked sampling
+end
+```
+
+## Best Practices
+
+### 1. Test Organization
+
+```ruby
+# Group related tests
+class FileManagerTest < TsikolTest
+  # Test successful operations
+  def test_read_existing_file
+  end
+  
+  def test_write_new_file
+  end
+  
+  # Test error cases
+  def test_read_nonexistent_file
+  end
+  
+  def test_write_protected_directory
+  end
+  
+  # Test edge cases
+  def test_empty_file
+  end
+  
+  def test_large_file
+  end
+end
+```
+
+### 2. Setup and Teardown
+
+```ruby
+class DatabaseToolTest < TsikolTest
+  def setup
+    super
+    @test_db = create_test_database
+    @tool = DatabaseTool.new(database: @test_db)
+    @server.register_tool_instance(@tool)
+  end
+  
+  def teardown
+    @test_db.close
+    cleanup_test_database
+    super
+  end
+end
+```
+
+### 3. Descriptive Test Names
+
+```ruby
+# Good test names
+def test_returns_error_when_file_not_found
+def test_completes_branch_names_starting_with_prefix
+def test_rate_limits_after_exceeding_threshold
+
+# Poor test names
+def test_1
+def test_error
+def test_completion
+```
+
+### 4. Test Data Isolation
+
+```ruby
+def test_concurrent_requests
+  # Each test uses unique data
+  file1 = "test_#{SecureRandom.hex(8)}.txt"
+  file2 = "test_#{SecureRandom.hex(8)}.txt"
+  
+  # Test concurrent operations
+ensure
+  [file1, file2].each { |f| File.delete(f) if File.exist?(f) }
+end
+```
+
+### 5. Performance Testing
+
+```ruby
+def test_handles_high_load
+  assert_response_time(1000) do  # Max 1 second
+    100.times do
+      @client.read_resource("system/status")
+    end
+  end
+end
+
+def test_large_file_processing
+  large_file = create_test_file("large.txt", "x" * 10_000_000)  # 10MB
+  
+  assert_response_time(5000) do  # Max 5 seconds
+    @client.call_tool("file_processor", {
+      "path" => large_file,
+      "operation" => "analyze"
+    })
+  end
+end
+```
+
+## Running Tests
+
+### Run All Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run with verbose output
+bundle exec rake test TESTOPTS="--verbose"
+
+# Run specific test file
+ruby -Ilib:test test/tools/file_manager_test.rb
+
+# Run specific test method
+ruby -Ilib:test test/tools/file_manager_test.rb -n test_read_file
+```
+
+### Test Coverage
+
+```ruby
+# Gemfile
+group :test do
+  gem 'simplecov'
+end
+
+# test/test_helper.rb
+require 'simplecov'
+SimpleCov.start do
+  add_filter '/test/'
+  add_group 'Tools', 'app/tools'
+  add_group 'Resources', 'app/resources'
+  add_group 'Prompts', 'app/prompts'
+end
+```
+
+## Next Steps
+
+- Review [Test Helpers API](../api/test-helpers.md)
+- Learn about [Error Handling](../cookbook/error-handling.md)
+- Explore [Logging](../cookbook/logging.md) for debugging
+- Check [Examples](../examples/) for more test patterns