tsikol 0.1.0

data/docs/api/test-helpers.md

@@ -0,0 +1,591 @@
+# Test Helpers API Reference
+
+Tsikol provides comprehensive test helpers for testing MCP servers, tools, resources, and prompts.
+
+## Module: Tsikol::TestHelpers
+
+### Including Test Helpers
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class MyTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+  end
+end
+```
+
+## Class: Tsikol::TestHelpers::TestClient
+
+A test client that simulates MCP protocol interactions without network communication.
+
+### Constructor
+
+```ruby
+client = Tsikol::TestHelpers::TestClient.new(server, options = {})
+```
+
+#### Parameters
+
+- `server`: The Tsikol::Server instance to test
+- `options` (Hash): Configuration options
+  - `:client_id` - Client identifier for the session
+  - `:strict_mode` - Enable strict protocol validation
+
+### Connection Methods
+
+#### `#initialize_connection`
+
+Initialize the MCP connection and retrieve capabilities.
+
+```ruby
+response = @client.initialize_connection
+
+# Response includes server capabilities
+response[:result][:capabilities]
+# => {
+#   tools: { listChanged: true },
+#   resources: { subscribe: true, listChanged: true },
+#   prompts: { listChanged: true },
+#   completion: { providers: [...] },
+#   sampling: {}
+# }
+```
+
+### Tool Methods
+
+#### `#list_tools`
+
+List all available tools.
+
+```ruby
+response = @client.list_tools
+
+response[:result][:tools]
+# => [
+#   {
+#     name: "file_manager",
+#     description: "Manage files",
+#     inputSchema: { ... }
+#   }
+# ]
+```
+
+#### `#call_tool(name, arguments)`
+
+Call a tool with arguments.
+
+```ruby
+response = @client.call_tool("calculator", {
+  "operation" => "add",
+  "a" => 5,
+  "b" => 3
+})
+
+response[:result][:content]
+# => [{ type: "text", text: "8" }]
+```
+
+### Resource Methods
+
+#### `#list_resources`
+
+List all available resources.
+
+```ruby
+response = @client.list_resources
+
+response[:result][:resources]
+# => [
+#   {
+#     uri: "system/status",
+#     name: "System Status",
+#     description: "Current system status",
+#     mimeType: "application/json"
+#   }
+# ]
+```
+
+#### `#read_resource(uri)`
+
+Read a resource by URI.
+
+```ruby
+response = @client.read_resource("system/status")
+
+response[:result][:contents]
+# => [
+#   {
+#     uri: "system/status",
+#     mimeType: "application/json",
+#     text: '{"status":"healthy"}'
+#   }
+# ]
+```
+
+### Prompt Methods
+
+#### `#list_prompts`
+
+List all available prompts.
+
+```ruby
+response = @client.list_prompts
+
+response[:result][:prompts]
+# => [
+#   {
+#     name: "code_assistant",
+#     description: "AI code assistant",
+#     arguments: [...]
+#   }
+# ]
+```
+
+#### `#get_prompt(name, arguments)`
+
+Get a prompt with arguments.
+
+```ruby
+response = @client.get_prompt("translator", {
+  "text" => "Hello",
+  "target_language" => "spanish"
+})
+
+response[:result][:messages]
+# => [
+#   { role: "system", content: { type: "text", text: "..." } },
+#   { role: "user", content: { type: "text", text: "..." } }
+# ]
+```
+
+### Completion Methods
+
+#### `#complete(ref, argument)`
+
+Get completion suggestions.
+
+```ruby
+# Tool parameter completion
+response = @client.complete(
+  { type: "ref/tool", name: "file_manager" },
+  { name: "path", value: "/usr/lo" }
+)
+
+response[:result][:completion][:values]
+# => ["/usr/local", "/usr/local/bin", "/usr/local/lib"]
+
+# Prompt argument completion
+response = @client.complete(
+  { type: "ref/prompt", name: "code_review" },
+  { name: "language", value: "jav" }
+)
+
+response[:result][:completion][:values]
+# => ["java", "javascript"]
+```
+
+### Sampling Methods
+
+#### `#sample_text(messages, options = {})`
+
+Request text generation (if server has sampling enabled).
+
+```ruby
+response = @client.sample_text(
+  [
+    { role: "user", content: { type: "text", text: "Hello!" } }
+  ],
+  temperature: 0.7,
+  max_tokens: 100
+)
+
+response[:result][:text]
+# => "Hello! How can I help you today?"
+```
+
+### Notification Methods
+
+#### `#send_notification(method, params = {})`
+
+Send a notification (no response expected).
+
+```ruby
+@client.send_notification("notifications/cancelled", {
+  requestId: "123",
+  reason: "User cancelled"
+})
+```
+
+### Logging Methods
+
+#### `#send_log(level, message, data = nil)`
+
+Send a log message (if server has logging enabled).
+
+```ruby
+@client.send_log(:info, "Test started", { test_name: "example" })
+@client.send_log(:error, "Test failed", { error: "Timeout" })
+```
+
+## Module: Tsikol::TestHelpers::Assertions
+
+Custom assertions for testing MCP responses.
+
+### Response Assertions
+
+#### `assert_successful_response(response)`
+
+Assert that a response succeeded.
+
+```ruby
+response = @client.call_tool("echo", { "message" => "Hello" })
+assert_successful_response(response)
+```
+
+#### `assert_error_response(response, expected_code = nil)`
+
+Assert that a response contains an error.
+
+```ruby
+response = @client.call_tool("invalid_tool", {})
+assert_error_response(response, -32601)  # Method not found
+```
+
+#### `assert_response_contains(response, expected)`
+
+Assert that response contains expected content.
+
+```ruby
+response = @client.read_resource("config")
+assert_response_contains(response, "database_url")
+```
+
+### Content Assertions
+
+#### `assert_tool_result(response, expected)`
+
+Assert tool result matches expected value.
+
+```ruby
+response = @client.call_tool("calculator", {
+  "operation" => "multiply",
+  "a" => 6,
+  "b" => 7
+})
+assert_tool_result(response, "42")
+```
+
+#### `assert_resource_content(response, expected)`
+
+Assert resource content matches expected value.
+
+```ruby
+response = @client.read_resource("version")
+assert_resource_content(response, "1.0.0")
+```
+
+#### `assert_prompt_messages(response, expected_count)`
+
+Assert prompt returns expected number of messages.
+
+```ruby
+response = @client.get_prompt("assistant", { "task" => "help" })
+assert_prompt_messages(response, 2)  # System + user message
+```
+
+### Validation Assertions
+
+#### `assert_valid_tool_schema(tool)`
+
+Assert tool has valid parameter schema.
+
+```ruby
+response = @client.list_tools
+tool = response[:result][:tools].first
+assert_valid_tool_schema(tool)
+```
+
+#### `assert_valid_prompt_arguments(prompt)`
+
+Assert prompt has valid argument definitions.
+
+```ruby
+response = @client.list_prompts
+prompt = response[:result][:prompts].first
+assert_valid_prompt_arguments(prompt)
+```
+
+## Test Helpers Utilities
+
+### Mock Server
+
+Create a mock server for testing:
+
+```ruby
+class MockServer < Tsikol::TestHelpers::MockServer
+  def initialize
+    super(name: "mock-server")
+    
+    # Configure mock responses
+    mock_tool_response("echo", ->(args) { args["message"] })
+    mock_resource_response("time", -> { Time.now.iso8601 })
+    mock_prompt_response("simple", ->(args) {
+      [{ role: "user", content: { type: "text", text: args["text"] } }]
+    })
+  end
+end
+```
+
+### Test Data Generators
+
+Generate test data for various scenarios:
+
+```ruby
+module TestData
+  extend Tsikol::TestHelpers::Generators
+  
+  # Generate valid JSON-RPC request
+  def self.request(method, params = {})
+    {
+      jsonrpc: "2.0",
+      id: random_id,
+      method: method,
+      params: params
+    }
+  end
+  
+  # Generate tool parameters
+  def self.tool_params
+    {
+      "string_param" => random_string,
+      "number_param" => random_number,
+      "boolean_param" => random_boolean,
+      "array_param" => random_array,
+      "object_param" => random_object
+    }
+  end
+end
+```
+
+### Performance Testing
+
+Test performance and response times:
+
+```ruby
+class PerformanceTest < Minitest::Test
+  include Tsikol::TestHelpers::Performance
+  
+  def test_tool_performance
+    assert_response_time(max_ms: 100) do
+      @client.call_tool("quick_tool", { "data" => "test" })
+    end
+  end
+  
+  def test_resource_caching
+    # First call
+    time1 = measure_time do
+      @client.read_resource("expensive/data")
+    end
+    
+    # Cached call should be faster
+    time2 = measure_time do
+      @client.read_resource("expensive/data")
+    end
+    
+    assert time2 < time1 / 10, "Cache should improve performance"
+  end
+  
+  def test_concurrent_requests
+    assert_handles_concurrent_requests(count: 100) do |i|
+      @client.call_tool("echo", { "message" => "Request #{i}" })
+    end
+  end
+end
+```
+
+## Complete Test Example
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class ComprehensiveTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    # Create server with all features
+    @server = Tsikol::Server.new(name: "test-server")
+    @server.logging true
+    @server.completion true
+    @server.sampling true
+    
+    # Add middleware
+    @server.use Tsikol::LoggingMiddleware, level: :debug
+    @server.use Tsikol::ErrorHandlingMiddleware
+    
+    # Register components
+    register_test_components
+    
+    # Create test client
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    @client.initialize_connection
+  end
+  
+  def teardown
+    # Cleanup
+    cleanup_test_files
+  end
+  
+  def test_complete_workflow
+    # 1. List available tools
+    response = @client.list_tools
+    assert_successful_response(response)
+    
+    tools = response[:result][:tools]
+    assert tools.any? { |t| t[:name] == "file_manager" }
+    
+    # 2. Create a test file using tool
+    response = @client.call_tool("file_manager", {
+      "operation" => "write",
+      "path" => "test.txt",
+      "content" => "Hello, World!"
+    })
+    assert_successful_response(response)
+    
+    # 3. Read the file back
+    response = @client.call_tool("file_manager", {
+      "operation" => "read",
+      "path" => "test.txt"
+    })
+    assert_tool_result(response, "Hello, World!")
+    
+    # 4. Check system status resource
+    response = @client.read_resource("system/status")
+    assert_successful_response(response)
+    
+    status = JSON.parse(response[:result][:contents][0][:text])
+    assert_equal "healthy", status["status"]
+    
+    # 5. Get AI prompt
+    response = @client.get_prompt("assistant", {
+      "task" => "Review the file test.txt"
+    })
+    assert_successful_response(response)
+    assert_prompt_messages(response, 2)
+    
+    # 6. Test completion
+    response = @client.complete(
+      { type: "ref/tool", name: "file_manager" },
+      { name: "operation", value: "rea" }
+    )
+    assert_successful_response(response)
+    assert response[:result][:completion][:values].include?("read")
+    
+    # 7. Test error handling
+    response = @client.call_tool("file_manager", {
+      "operation" => "read",
+      "path" => "nonexistent.txt"
+    })
+    assert_error_response(response)
+    assert_match /not found/i, response[:error][:message]
+  end
+  
+  def test_concurrent_operations
+    threads = 10.times.map do |i|
+      Thread.new do
+        # Each thread performs operations
+        response = @client.call_tool("echo", {
+          "message" => "Thread #{i}"
+        })
+        assert_successful_response(response)
+        assert_tool_result(response, "Thread #{i}")
+      end
+    end
+    
+    threads.each(&:join)
+  end
+  
+  private
+  
+  def register_test_components
+    # Register test tool
+    @server.tool "echo" do |message:|
+      message
+    end
+    
+    # Register file manager tool
+    @server.register_tool_instance(TestFileManager.new)
+    
+    # Register test resource
+    @server.resource "system/status" do
+      { status: "healthy", timestamp: Time.now.iso8601 }.to_json
+    end
+    
+    # Register test prompt
+    @server.prompt "assistant" do |task:|
+      [
+        { role: "system", content: { type: "text", text: "You are helpful." } },
+        { role: "user", content: { type: "text", text: task } }
+      ]
+    end
+  end
+  
+  def cleanup_test_files
+    File.delete("test.txt") if File.exist?("test.txt")
+  end
+end
+
+class TestFileManager < Tsikol::Tool
+  description "Test file manager"
+  
+  parameter :operation do
+    type :string
+    required
+    enum ["read", "write"]
+  end
+  
+  parameter :path do
+    type :string
+    required
+  end
+  
+  parameter :content do
+    type :string
+    optional
+  end
+  
+  def execute(operation:, path:, content: nil)
+    case operation
+    when "read"
+      raise Tsikol::ValidationError, "File not found" unless File.exist?(path)
+      File.read(path)
+    when "write"
+      File.write(path, content)
+      "File written successfully"
+    end
+  end
+end
+```
+
+## Testing Best Practices
+
+1. **Isolation**: Test components in isolation before integration
+2. **Coverage**: Test success cases, error cases, and edge cases
+3. **Assertions**: Use specific assertions for better error messages
+4. **Cleanup**: Always clean up test data and resources
+5. **Concurrency**: Test thread safety with concurrent requests
+6. **Performance**: Set reasonable performance expectations
+7. **Mocking**: Mock external dependencies for reliable tests
+
+## See Also
+
+- [Testing Guide](../guides/testing.md)
+- [Server API](server.md)
+- [Tool API](tool.md)
+- [Error Handling](../cookbook/error-handling.md)