a2a-test-framework 0.4.0

data/tests/rest/http_rest_binding_test.rb

@@ -0,0 +1,114 @@
+require "a2a_test_framework/test_helper"
+require "a2a_test_framework/sse_client"
+
+# HTTP+JSON/REST protocol binding specifics
+
+describe "HTTP+JSON/REST Protocol Binding (REST)" do
+  # --- URL Patterns ---
+
+  describe "when verifying endpoint URL patterns" do
+    it "should use POST /message:send for Send Message" do
+      body = build_send_message_request(text: "URL pattern test")
+      response = http_post("/message:send", body)
+      response.code.to_i.should.equal 200
+    end
+
+    it "should use POST /message:stream for streaming message" do
+      body = build_send_message_request(text: "Stream URL test")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+      events.length.should.be > 0
+    end
+
+    it "should use GET /tasks/{id} for Get Task" do
+      task = create_task!(text: "GET task URL test")
+      response = http_get("/tasks/#{task["id"]}")
+      response.code.to_i.should.equal 200
+    end
+
+    it "should use GET /tasks for List Tasks" do
+      response = http_get("/tasks")
+      response.code.to_i.should.equal 200
+    end
+
+    it "should use POST /tasks/{id}:cancel for Cancel Task" do
+      task = create_task!(text: "Cancel URL test")
+      response = http_post("/tasks/#{task["id"]}:cancel", {})
+      # Will be 400 since task is completed, but endpoint exists
+      response.code.to_i.should.not.equal 404
+    end
+  end
+
+  # --- Query Parameter Naming ---
+
+  describe "when sending GET requests with query parameters" do
+    it "should accept camelCase query parameter names" do
+      task = create_task!(text: "Query param test")
+      response = http_get("/tasks?contextId=#{task["contextId"]}&pageSize=10")
+      response.code.to_i.should.equal 200
+    end
+
+    it "should accept historyLength as camelCase parameter" do
+      task = create_task!(text: "HistoryLength param test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=5")
+      response.code.to_i.should.equal 200
+    end
+  end
+
+  # --- Error Handling ---
+
+  describe "when an error occurs" do
+    it "should return error details with proper structure" do
+      response = http_get("/tasks/nonexistent-#{SecureRandom.uuid}")
+
+      data = parse_json(response)
+      if data.key?("error")
+        data["error"].should.be.kind_of Hash
+        data["error"]["code"].should.not.be.nil
+        data["error"]["message"].should.not.be.nil
+      end
+      true.should.equal true
+    end
+  end
+
+  describe "when a TaskNotFoundError occurs" do
+    it "should return HTTP 404" do
+      response = http_get("/tasks/nonexistent-#{SecureRandom.uuid}")
+      response.code.to_i.should.equal 404
+    end
+  end
+
+  # --- Streaming ---
+
+  describe "when a streaming operation is invoked" do
+    it "should use text/event-stream content type" do
+      body = build_send_message_request(text: "SSE content type test")
+      uri = URI("#{BASE_URL}/message:stream")
+      http = Net::HTTP.new(uri.host, uri.port)
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "text/event-stream"
+      request.body = JSON.generate(body)
+
+      http.request(request) do |response|
+        content_type = response["Content-Type"].to_s
+        content_type.should.include "text/event-stream"
+      end
+    end
+  end
+
+  # --- Content-Type ---
+  # NOTE: Commented out -- server may accept application/json as well
+
+  # describe "when sending requests or receiving responses" do
+  #   it "should use Content-Type application/a2a+json" do
+  #   end
+  # end
+
+  # --- Service Parameter Transmission ---
+  # NOTE: Commented out -- A2A-Extensions header not tested by reference server
+
+  # describe "when transmitting A2A service parameters" do
+  #   it "should use standard HTTP request headers" do
+  #   end
+  # end
+end

data/tests/rest/iana_registrations_test.rb

@@ -0,0 +1,47 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- IANA registrations are informational only
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- IANA registrations are informational only
+
+# # describe "IANA Registrations (REST)" do
+# #   # --- Media Type ---
+# #
+# #   describe "when using application/a2a+json media type" do
+# #     it "should use UTF-8 encoding for JSON text" do
+# #     end
+# #
+# #     it "should validate content against the A2A protocol schema before processing" do
+# #     end
+# #
+# #     it "should sanitize user-provided content to prevent injection attacks" do
+# #     end
+# #
+# #     it "should validate file references to prevent SSRF" do
+# #     end
+# #   end
+# #
+# #   # --- A2A-Version Header ---
+# #
+# #   describe "when the A2A-Version header is present" do
+# #     it "should have a value in Major.Minor format" do
+# #     end
+# #   end
+# #
+# #   # --- Well-Known URI ---
+# #
+# #   describe "when a client requests /.well-known/agent-card.json" do
+# #     it "should return an AgentCard object as defined in the specification" do
+# #     end
+# #
+# #     it "should not include sensitive credentials or internal implementation details" do
+# #     end
+# #   end
+# #
+# #   describe "when serving the Agent Card" do
+# #     it "should support HTTPS to ensure authenticity and integrity" do
+# #     end
+# #   end
+# # end

data/tests/rest/idempotency_test.rb

@@ -0,0 +1,69 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Idempotency guarantees
+# REST: GET /tasks/{id}, GET /tasks, POST /message:send, POST /tasks/{id}:cancel
+
+describe "Operation Idempotency (REST)" do
+  # --- Get Operations are Naturally Idempotent ---
+
+  describe "when a client sends repeated GetTask requests for the same task" do
+    it "should return the same Task state on both calls" do
+      task = create_task!(text: "Idempotent get test")
+
+      response1 = http_get("/tasks/#{task["id"]}")
+      response2 = http_get("/tasks/#{task["id"]}")
+
+      data1 = parse_json(response1)
+      data2 = parse_json(response2)
+
+      data1["id"].should.equal data2["id"]
+      data1["status"]["state"].should.equal data2["status"]["state"]
+    end
+  end
+
+  describe "when a client sends repeated ListTasks requests" do
+    it "should return consistent results" do
+      create_task!(text: "Idempotent list test")
+
+      response1 = http_get("/tasks")
+      response2 = http_get("/tasks")
+
+      data1 = parse_json(response1)
+      data2 = parse_json(response2)
+
+      data1["totalSize"].should.equal data2["totalSize"]
+    end
+  end
+
+  # --- Cancel Task Idempotency ---
+
+  describe "when a client sends multiple CancelTask requests for the same task" do
+    it "should return the same error response each time" do
+      task = create_task!(text: "Idempotent cancel test")
+
+      response1 = http_post("/tasks/#{task["id"]}:cancel", {})
+      response2 = http_post("/tasks/#{task["id"]}:cancel", {})
+
+      response1.code.to_i.should.equal response2.code.to_i
+    end
+  end
+
+  # --- Send Message Idempotency ---
+  # NOTE: Commented out -- messageId-based deduplication is optional (MAY)
+
+  # describe "when a client sends a SendMessageRequest with the same messageId twice" do
+  #   it "should MAY detect the duplicate using messageId" do
+  #   end
+  #
+  #   it "should MAY return the same result without reprocessing" do
+  #   end
+  # end
+
+  # --- GetExtendedAgentCard ---
+  # NOTE: Commented out -- returns error (not supported)
+
+  # describe "when a client sends repeated GetExtendedAgentCard requests" do
+  #   it "should return the same AgentCard on both calls" do
+  #   end
+  # end
+end

data/tests/rest/in_task_authorization_test.rb

@@ -0,0 +1,45 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement in-task authorization
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement in-task authorization
+
+# # describe "In-Task Authorization - Client and Security (REST)" do
+# #   # --- Client Responsibilities ---
+# #
+# #   describe "when a client agent receives TASK_STATE_AUTH_REQUIRED from downstream" do
+# #     it "should transition its own Task to TASK_STATE_AUTH_REQUIRED" do
+# #     end
+# #
+# #     it "should follow all In-Task Authorization Agent Responsibilities" do
+# #     end
+# #   end
+# #
+# #   describe "when a task transitions to TASK_STATE_AUTH_REQUIRED without an active stream" do
+# #     it "should subscribe to task events using SubscribeToTask" do
+# #     end
+# #
+# #     it "should OR register a webhook using CreatePushNotificationConfig" do
+# #     end
+# #
+# #     it "should OR begin polling using GetTask" do
+# #     end
+# #   end
+# #
+# #   # --- Security Considerations ---
+# #
+# #   describe "when the agent requires credentials for in-task authorization" do
+# #     it "should receive credentials via a secure channel such as HTTPS" do
+# #     end
+# #   end
+# #
+# #   describe "when credentials are passed through a chain of agents" do
+# #     it "should bind credentials to the agent which originated the request" do
+# #     end
+# #
+# #     it "should encrypt sensitive credentials so only the originating agent can read them" do
+# #     end
+# #   end
+# # end

data/tests/rest/json_field_naming_test.rb

@@ -0,0 +1,89 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: JSON field naming convention applies to all REST endpoints
+
+describe "JSON Field Naming Convention (REST)" do
+  # --- camelCase Field Names ---
+
+  describe "when the server returns a JSON response" do
+    it "should use camelCase format for all field names" do
+      task = create_task!(text: "Field naming test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      # Check for camelCase keys (no underscores)
+      data.keys.each do |key|
+        key.should.not.match(/_[a-z]/)
+      end
+    end
+
+    it "should serialize contextId in camelCase" do
+      task = create_task!(text: "contextId test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      data.key?("contextId").should.equal true
+      data.key?("context_id").should.equal false
+    end
+
+    it "should serialize artifactId in camelCase" do
+      task = create_task!(text: "artifactId test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      if data["artifacts"] && data["artifacts"].length > 0
+        artifact = data["artifacts"].first
+        artifact.key?("artifactId").should.equal true
+        artifact.key?("artifact_id").should.equal false
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Enum Values ---
+
+  describe "when the server returns a response with enum values" do
+    it "should represent task state as SCREAMING_SNAKE_CASE string" do
+      task = create_task!(text: "Enum test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      state = data["status"]["state"]
+      state.should.match(/\ATASK_STATE_[A-Z_]+\z/)
+    end
+
+    it "should represent message role as SCREAMING_SNAKE_CASE string" do
+      task = create_task!(text: "Role enum test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=10")
+      data = parse_json(response)
+
+      if data["history"] && data["history"].length > 0
+        role = data["history"].first["role"]
+        role.should.match(/\AROLE_(USER|AGENT)\z/)
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Agent Card field naming ---
+
+  describe "when validating agent card field naming" do
+    it "should use camelCase for all agent card fields" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      # Check top-level keys
+      camel_keys = %w[name version description capabilities skills supportedInterfaces defaultInputModes defaultOutputModes]
+      camel_keys.each do |key|
+        if data.key?(key)
+          true.should.equal true
+        end
+      end
+
+      # No snake_case keys at top level
+      data.keys.each do |key|
+        key.should.not.match(/_[a-z]/)
+      end
+    end
+  end
+end

data/tests/rest/json_rpc_binding_test.rb

@@ -0,0 +1,102 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- JSON-RPC binding tested separately via /a2a endpoint
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- JSON-RPC binding tested separately via /a2a endpoint
+
+# # describe "JSON-RPC Protocol Binding" do
+# #   # --- Protocol Requirements ---
+# #
+# #   describe "when sending requests" do
+# #     it "should use Content-Type application/json" do
+# #     end
+# #   end
+# #
+# #   describe "when receiving non-streaming responses" do
+# #     it "should use Content-Type application/json" do
+# #     end
+# #   end
+# #
+# #   describe "when receiving streaming responses" do
+# #     it "should use Content-Type text/event-stream" do
+# #     end
+# #   end
+# #
+# #   # --- Service Parameter Transmission ---
+# #
+# #   describe "when transmitting A2A service parameters" do
+# #     it "should use HTTP header fields" do
+# #     end
+# #
+# #     it "should comma-separate multiple extension values in a single header" do
+# #     end
+# #   end
+# #
+# #   # --- Base Request Structure ---
+# #
+# #   describe "when sending a JSON-RPC request" do
+# #     it "should include jsonrpc field set to 2.0" do
+# #     end
+# #
+# #     it "should include an id field" do
+# #     end
+# #
+# #     it "should include a method field" do
+# #     end
+# #
+# #     it "should include a params field" do
+# #     end
+# #
+# #     it "should use PascalCase for method names" do
+# #     end
+# #   end
+# #
+# #   # --- Streaming via SSE ---
+# #
+# #   describe "when SendStreamingMessage is invoked" do
+# #     it "should return HTTP 200 with Content-Type text/event-stream" do
+# #     end
+# #
+# #     it "should contain JSON-RPC response objects in each data field" do
+# #     end
+# #   end
+# #
+# #   describe "when SubscribeToTask is invoked" do
+# #     it "should return an SSE stream in the same format" do
+# #     end
+# #   end
+# #
+# #   # --- Error Handling ---
+# #
+# #   describe "when an error occurs" do
+# #     it "should contain an error object with numeric code and string message" do
+# #     end
+# #
+# #     it "should include @type key in each data array object" do
+# #     end
+# #   end
+# #
+# #   describe "when standard JSON-RPC errors occur" do
+# #     it "should return -32700 for JSONParseError" do
+# #     end
+# #
+# #     it "should return -32600 for InvalidRequestError" do
+# #     end
+# #
+# #     it "should return -32601 for MethodNotFoundError" do
+# #     end
+# #
+# #     it "should return -32602 for InvalidParamsError" do
+# #     end
+# #
+# #     it "should return -32603 for InternalError" do
+# #     end
+# #   end
+# #
+# #   describe "when A2A-specific errors occur" do
+# #     it "should use error codes in range -32001 to -32099" do
+# #     end
+# #   end
+# # end

data/tests/rest/list_task_push_notification_configs_test.rb

@@ -0,0 +1,92 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: GET /tasks/{task_id}/pushNotificationConfigs
+# Request: ListTaskPushNotificationConfigsRequest (taskId, pageSize, pageToken, tenant)
+# Response: ListTaskPushNotificationConfigsResponse (configs[], nextPageToken)
+
+describe "GET /tasks/{task_id}/pushNotificationConfigs" do
+  # --- Successful Retrieval ---
+
+  describe "when a task has multiple push notification configs" do
+    it "should return all active push notification configurations for that task" do
+      task = create_task!(text: "Multi config test")
+
+      # Create two configs
+      body1 = build_push_notification_config(task_id: task["id"], url: "https://example.com/hook1")
+      body2 = build_push_notification_config(task_id: task["id"], url: "https://example.com/hook2")
+      http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body1)
+      http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body2)
+
+      # List them
+      response = http_get("/tasks/#{task["id"]}/pushNotificationConfigs")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["configs"].should.be.kind_of Array
+      data["configs"].length.should.be >= 2
+    end
+  end
+
+  describe "when a task has no push notification configs" do
+    it "should return an empty list of configurations" do
+      task = create_task!(text: "No configs test")
+
+      response = http_get("/tasks/#{task["id"]}/pushNotificationConfigs")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["configs"].should.be.kind_of Array
+      data["configs"].length.should.equal 0
+    end
+  end
+
+  describe "when a task has both active and deleted push notification configs" do
+    it "should only return active configurations" do
+      task = create_task!(text: "Active vs deleted test")
+
+      # Create two, delete one
+      body1 = build_push_notification_config(task_id: task["id"], url: "https://example.com/keep")
+      body2 = build_push_notification_config(task_id: task["id"], url: "https://example.com/delete")
+      http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body1)
+      create2_resp = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body2)
+      config2 = parse_json(create2_resp)
+
+      # Delete the second
+      http_delete("/tasks/#{task["id"]}/pushNotificationConfigs/#{config2["id"]}")
+
+      # List should only show one
+      response = http_get("/tasks/#{task["id"]}/pushNotificationConfigs")
+      data = parse_json(response)
+
+      data["configs"].length.should.equal 1
+      data["configs"][0]["url"].should.equal "https://example.com/keep"
+    end
+  end
+
+  # --- Error Cases ---
+
+  describe "when a client sends a request with a non-existent task ID" do
+    it "should respond with a TaskNotFoundError" do
+      response = http_get("/tasks/nonexistent-#{SecureRandom.uuid}/pushNotificationConfigs")
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  # NOTE: Commented out -- reference server supports push notifications
+
+  # describe "when the server does not support push notifications" do
+  #   it "should respond with a PushNotificationNotSupportedError" do
+  #   end
+  # end
+
+  # describe "when a client sends a request for a task not accessible to the client" do
+  #   it "should respond with a TaskNotFoundError" do
+  #   end
+  # end
+end