a2a-test-framework 0.4.0

data/tests/rest/authentication_authorization_test.rb

@@ -0,0 +1,62 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement authentication
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement authentication
+
+# # describe "Authentication and Authorization (REST)" do
+# #   # --- Server Identity Verification ---
+# #
+# #   describe "when a client establishes a connection" do
+# #     it "should verify the server TLS certificate against trusted CAs" do
+# #     end
+# #   end
+# #
+# #   # --- Server Authentication Responsibilities ---
+# #
+# #   describe "when any request is received by the server" do
+# #     it "should authenticate the request based on provided credentials" do
+# #     end
+# #   end
+# #
+# #   describe "when a request fails authentication" do
+# #     it "should use appropriate binding-specific error codes" do
+# #     end
+# #
+# #     it "should provide authentication challenge information with the error response" do
+# #     end
+# #   end
+# #
+# #   # --- In-Task Authorization ---
+# #
+# #   describe "when the agent requires authorization during task processing" do
+# #     it "should use a Task to track the operation" do
+# #     end
+# #
+# #     it "should transition TaskState to TASK_STATE_AUTH_REQUIRED" do
+# #     end
+# #
+# #     it "should include a TaskStatus message explaining the required authorization" do
+# #     end
+# #
+# #     it "should arrange to receive credentials via an out-of-band means" do
+# #     end
+# #   end
+# #
+# #   describe "when the agent transitions to TASK_STATE_AUTH_REQUIRED on a streamed task" do
+# #     it "should maintain the active response stream with the client" do
+# #     end
+# #   end
+# #
+# #   describe "when credentials are received out-of-band for an auth_required task" do
+# #     it "should MAY immediately continue task processing without client follow-up message" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a message to a task in auth_required state" do
+# #     it "should accept and process the message to enable negotiation" do
+# #     end
+# #   end
+# # end

data/tests/rest/cancel_task_test.rb

@@ -0,0 +1,110 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: POST /tasks/{id}:cancel
+# Request: CancelTaskRequest (id, metadata, tenant)
+# Response: Task
+
+describe "POST /tasks/{id}:cancel" do
+  # --- Successful Cancellation ---
+  # NOTE: The reference server completes tasks synchronously, so we cannot
+  # easily get a task in a non-terminal state to cancel. These are commented out.
+
+  # describe "when a client sends a CancelTask request for a working task" do
+  #   it "should respond with an updated Task object" do
+  #   end
+  #
+  #   it "should reflect the cancellation in the Task status" do
+  #   end
+  # end
+
+  # describe "when a client sends a CancelTask request for a task in input_required state" do
+  #   it "should respond with an updated Task object" do
+  #   end
+  #
+  #   it "should reflect the cancellation in the Task status" do
+  #   end
+  # end
+
+  # describe "when a client sends a CancelTask request for a cancelable task" do
+  #   it "should return an updated Task object with cancellation status" do
+  #   end
+  # end
+
+  # --- Error Cases ---
+
+  describe "when a client sends a CancelTask request for a completed task" do
+    it "should respond with a TaskNotCancelableError" do
+      task = create_task!(text: "Complete then cancel")
+      task["status"]["state"].should.equal "TASK_STATE_COMPLETED"
+
+      response = http_post("/tasks/#{task["id"]}:cancel", {})
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  describe "when a client sends a CancelTask request for an already canceled task" do
+    it "should respond with a TaskNotCancelableError" do
+      task = create_task!(text: "Cancel again")
+
+      # First cancel attempt (will fail since task is completed)
+      response = http_post("/tasks/#{task["id"]}:cancel", {})
+
+      # Second attempt should also error
+      response2 = http_post("/tasks/#{task["id"]}:cancel", {})
+      if response2.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response2)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  describe "when a client sends a CancelTask request with a non-existent task ID" do
+    it "should respond with a TaskNotFoundError" do
+      fake_id = "nonexistent-#{SecureRandom.uuid}"
+      response = http_post("/tasks/#{fake_id}:cancel", {})
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  describe "when a client sends a CancelTask request for a task not accessible to the client" do
+    it "should respond with a TaskNotFoundError" do
+      fake_id = "inaccessible-#{SecureRandom.uuid}"
+      response = http_post("/tasks/#{fake_id}:cancel", {})
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  # --- Idempotency ---
+
+  describe "when a client sends multiple CancelTask requests for the same task" do
+    it "should handle repeated cancellation requests consistently" do
+      task = create_task!(text: "Idempotent cancel")
+
+      response1 = http_post("/tasks/#{task["id"]}:cancel", {})
+      response2 = http_post("/tasks/#{task["id"]}:cancel", {})
+
+      # Both should return same type of error (task is already terminal)
+      response1.code.to_i.should.equal response2.code.to_i
+    end
+  end
+end

data/tests/rest/capability_validation_test.rb

@@ -0,0 +1,78 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Capability validation applies to all optional endpoints
+
+describe "Capability Validation (REST)" do
+  # --- Push Notifications Capability ---
+  # NOTE: Reference server declares pushNotifications=true, so these
+  # test the positive case. Negative case (false) is commented out.
+
+  # describe "when pushNotifications capability is false or not declared" do
+  #   it "should return PushNotificationNotSupportedError on CreatePushNotificationConfig" do
+  #   end
+  # end
+
+  # --- Streaming Capability ---
+  # NOTE: Reference server declares streaming=true
+
+  # describe "when streaming capability is false or not declared" do
+  #   it "should return UnsupportedOperationError on SendStreamingMessage" do
+  #   end
+  #
+  #   it "should return UnsupportedOperationError on SubscribeToTask" do
+  #   end
+  # end
+
+  # --- Extended Agent Card Capability ---
+
+  describe "when extendedAgentCard capability is false or not declared" do
+    it "should return an error on GetExtendedAgentCard" do
+      # Reference server has extendedAgentCard=false
+      response = http_get("/extendedAgentCard")
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  # --- Capability Declaration in AgentCard ---
+
+  describe "when examining the AgentCard capabilities" do
+    it "should declare streaming capability" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      data["capabilities"].key?("streaming").should.equal true
+      data["capabilities"]["streaming"].should.equal true
+    end
+
+    it "should declare pushNotifications capability" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      data["capabilities"].key?("pushNotifications").should.equal true
+      data["capabilities"]["pushNotifications"].should.equal true
+    end
+
+    it "should declare extendedAgentCard capability" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      data["capabilities"].key?("extendedAgentCard").should.equal true
+      # Reference server sets this to false
+      data["capabilities"]["extendedAgentCard"].should.equal false
+    end
+  end
+
+  # --- Extensions Capability ---
+  # NOTE: Commented out -- reference server doesn't use required extensions
+
+  # describe "when the AgentCard lists a required extension" do
+  #   it "should return ExtensionSupportRequiredError if client does not declare support" do
+  #   end
+  # end
+end

data/tests/rest/context_identifier_semantics_test.rb

@@ -0,0 +1,75 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Context identifier semantics
+
+describe "Context Identifier Semantics (REST)" do
+  # --- Generation and Assignment ---
+
+  describe "when a client sends a message without a contextId" do
+    it "should generate a contextId and include it in the response" do
+      body = build_send_message_request(text: "No context provided")
+      # Don't include contextId in message
+      response = http_post("/message:send", body)
+      data = parse_json(response)
+
+      if data["task"]
+        data["task"]["contextId"].should.not.be.nil
+        data["task"]["contextId"].should.be.kind_of String
+        data["task"]["contextId"].length.should.be > 0
+      end
+      true.should.equal true
+    end
+  end
+
+  describe "when a client sends a message with a contextId" do
+    it "should preserve that contextId in the response" do
+      provided_context = SecureRandom.uuid
+      body = build_send_message_request(text: "With context", context_id: provided_context)
+      response = http_post("/message:send", body)
+      data = parse_json(response)
+
+      if data["task"]
+        data["task"]["contextId"].should.equal provided_context
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Grouping and Scope ---
+
+  describe "when multiple tasks share the same contextId" do
+    it "should group them under the same conversational session" do
+      context = SecureRandom.uuid
+      body1 = build_send_message_request(text: "Context group 1", context_id: context)
+      body2 = build_send_message_request(text: "Context group 2", context_id: context)
+
+      http_post("/message:send", body1)
+      http_post("/message:send", body2)
+
+      # Both tasks should appear when listing by contextId
+      response = http_get("/tasks?contextId=#{context}")
+      data = parse_json(response)
+
+      data["tasks"].length.should.be >= 2
+      data["tasks"].each { |t| t["contextId"].should.equal context }
+    end
+  end
+
+  # --- ContextId as opaque string ---
+
+  describe "when examining contextId format" do
+    it "should treat contextId as an opaque string" do
+      task = create_task!(text: "Opaque context test")
+      task["contextId"].should.be.kind_of String
+      task["contextId"].length.should.be > 0
+    end
+  end
+
+  # --- Server-Provided Context ---
+  # NOTE: Commented out -- behavior depends on whether server accepts client contexts
+
+  # describe "when the server does not accept client-provided contextIds" do
+  #   it "should reject the request with an error" do
+  #   end
+  # end
+end

data/tests/rest/create_task_push_notification_config_test.rb

@@ -0,0 +1,122 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: POST /tasks/{task_id}/pushNotificationConfigs
+# Request: TaskPushNotificationConfig (taskId, url, token, authentication, tenant)
+# Response: TaskPushNotificationConfig
+
+describe "POST /tasks/{task_id}/pushNotificationConfigs" do
+  # --- Successful Creation ---
+
+  describe "when a client creates a push notification config with a valid webhook URL" do
+    it "should respond with a PushNotificationConfig object" do
+      task = create_task!(text: "Push config creation")
+      body = build_push_notification_config(
+        task_id: task["id"],
+        url: "https://example.com/webhook",
+        token: "test-token-123"
+      )
+
+      response = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["url"].should.equal "https://example.com/webhook"
+      data["token"].should.equal "test-token-123"
+    end
+
+    it "should contain an assigned ID in the response" do
+      task = create_task!(text: "Push config ID test")
+      body = build_push_notification_config(
+        task_id: task["id"],
+        url: "https://example.com/hook2"
+      )
+
+      response = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      data = parse_json(response)
+
+      data["id"].should.not.be.nil
+      data["id"].should.be.kind_of String
+      data["id"].length.should.be > 0
+    end
+  end
+
+  # --- Configuration with Authentication ---
+
+  describe "when a client creates a config with authentication details" do
+    it "should store and return the authentication scheme" do
+      task = create_task!(text: "Auth config test")
+      body = build_push_notification_config(
+        task_id: task["id"],
+        url: "https://example.com/authed-hook",
+        authentication: { "scheme" => "Bearer", "credentials" => "my-secret" }
+      )
+
+      response = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["authentication"].should.not.be.nil
+      data["authentication"]["scheme"].should.equal "Bearer"
+    end
+  end
+
+  # --- Webhook Delivery ---
+  # NOTE: Commented out -- requires an actual webhook receiver endpoint
+
+  # describe "when the task status changes after config creation" do
+  #   it "should send an HTTP POST request to the configured webhook URL" do
+  #   end
+  #
+  #   it "should send the payload as a StreamResponse object" do
+  #   end
+  # end
+
+  # --- Configuration Persistence ---
+  # NOTE: Commented out -- requires async task lifecycle
+
+  # describe "when a push notification config exists for a non-terminal task" do
+  #   it "should remain active while the task is in a non-terminal state" do
+  #   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
+      body = build_push_notification_config(
+        task_id: "nonexistent-#{SecureRandom.uuid}",
+        url: "https://example.com/hook"
+      )
+
+      response = http_post("/tasks/nonexistent-#{SecureRandom.uuid}/pushNotificationConfigs", body)
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  # --- Capability Validation ---
+  # NOTE: Reference server declares pushNotifications=true
+
+  describe "when the AgentCard declares pushNotifications capability as true" do
+    it "should accept and process the request" do
+      task = create_task!(text: "Capability check")
+      body = build_push_notification_config(
+        task_id: task["id"],
+        url: "https://example.com/cap-hook"
+      )
+
+      response = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      response.code.to_i.should.equal 200
+    end
+  end
+
+  # describe "when the AgentCard declares pushNotifications capability as false" do
+  #   it "should respond with a PushNotificationNotSupportedError" do
+  #   end
+  # end
+end

data/tests/rest/custom_binding_test.rb

@@ -0,0 +1,96 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Custom binding testing not applicable to conformance suite
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Custom binding testing not applicable to conformance suite
+
+# # describe "Custom Binding Guidelines" do
+# #   # --- Binding Requirements ---
+# #
+# #   describe "when a custom binding is implemented" do
+# #     it "should implement all core operations defined in Section 3" do
+# #     end
+# #
+# #     it "should use functionally equivalent data structures" do
+# #     end
+# #
+# #     it "should maintain operation semantics consistent with abstract definitions" do
+# #     end
+# #
+# #     it "should provide comprehensive documentation" do
+# #     end
+# #   end
+# #
+# #   # --- Data Type Mappings ---
+# #
+# #   describe "when mapping data types in a custom binding" do
+# #     it "should define how each Protocol Buffer message type is represented" do
+# #     end
+# #
+# #     it "should follow timestamp conventions from Section 5.6.1" do
+# #     end
+# #   end
+# #
+# #   # --- Service Parameter Transmission ---
+# #
+# #   describe "when documenting service parameter transmission" do
+# #     it "should document how service parameters are transmitted" do
+# #     end
+# #
+# #     it "should address the protocol-specific transmission mechanism" do
+# #     end
+# #   end
+# #
+# #   # --- Error Mapping ---
+# #
+# #   describe "when mapping errors in a custom binding" do
+# #     it "should provide mappings for all A2A-specific error types" do
+# #     end
+# #
+# #     it "should ensure error details are accessible to clients" do
+# #     end
+# #   end
+# #
+# #   # --- Streaming Support ---
+# #
+# #   describe "when a custom binding does not support streaming" do
+# #     it "should clearly document this limitation in the Agent Card" do
+# #     end
+# #   end
+# #
+# #   # --- Authentication ---
+# #
+# #   describe "when implementing authentication" do
+# #     it "should support authentication schemes declared in the Agent Card" do
+# #     end
+# #   end
+# #
+# #   # --- Agent Card Declaration ---
+# #
+# #   describe "when declaring a custom binding in the Agent Card" do
+# #     it "should use a URI to identify the binding" do
+# #     end
+# #
+# #     it "should provide the full URL where the binding is available" do
+# #     end
+# #   end
+# # end
+# #
+# # describe "Custom Binding Identification" do
+# #   describe "when identifying a custom protocol binding" do
+# #     it "should use a URI as the protocolBinding field" do
+# #     end
+# #   end
+# #
+# #   describe "when a breaking change is introduced to a custom binding" do
+# #     it "should use a new URI to distinguish incompatible versions" do
+# #     end
+# #   end
+# #
+# #   describe "when multiple implementers have custom bindings" do
+# #     it "should use URIs for globally unique identification" do
+# #     end
+# #   end
+# # end

data/tests/rest/delete_task_push_notification_config_test.rb

@@ -0,0 +1,103 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: DELETE /tasks/{task_id}/pushNotificationConfigs/{id}
+# Request: DeleteTaskPushNotificationConfigRequest (taskId, id, tenant)
+# Response: google.protobuf.Empty
+
+describe "DELETE /tasks/{task_id}/pushNotificationConfigs/{id}" do
+  # --- Successful Deletion ---
+
+  describe "when a client deletes an existing push notification config" do
+    it "should respond with a successful status" do
+      task = create_task!(text: "Delete config test")
+      body = build_push_notification_config(task_id: task["id"], url: "https://example.com/to-delete")
+      create_resp = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      config = parse_json(create_resp)
+
+      response = http_delete("/tasks/#{task["id"]}/pushNotificationConfigs/#{config["id"]}")
+      response.code.to_i.should.be < 400
+    end
+
+    it "should cause subsequent GetPushNotificationConfig requests to fail" do
+      task = create_task!(text: "Delete then get test")
+      body = build_push_notification_config(task_id: task["id"], url: "https://example.com/delete-verify")
+      create_resp = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      config = parse_json(create_resp)
+
+      # Delete it
+      http_delete("/tasks/#{task["id"]}/pushNotificationConfigs/#{config["id"]}")
+
+      # Try to get it -- should fail
+      get_response = http_get("/tasks/#{task["id"]}/pushNotificationConfigs/#{config["id"]}")
+      if get_response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(get_response)
+        data.key?("error").should.equal true
+      end
+    end
+
+    it "should remove config from the list" do
+      task = create_task!(text: "Delete from list test")
+      body = build_push_notification_config(task_id: task["id"], url: "https://example.com/list-delete")
+      create_resp = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      config = parse_json(create_resp)
+
+      # Delete
+      http_delete("/tasks/#{task["id"]}/pushNotificationConfigs/#{config["id"]}")
+
+      # List should be empty
+      list_resp = http_get("/tasks/#{task["id"]}/pushNotificationConfigs")
+      list_data = parse_json(list_resp)
+      list_data["configs"].length.should.equal 0
+    end
+  end
+
+  # --- Idempotency ---
+
+  describe "when a client sends multiple delete requests for the same config" do
+    it "should handle repeated deletion without error" do
+      task = create_task!(text: "Idempotent delete test")
+      body = build_push_notification_config(task_id: task["id"], url: "https://example.com/idem-delete")
+      create_resp = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      config = parse_json(create_resp)
+
+      # Delete twice
+      response1 = http_delete("/tasks/#{task["id"]}/pushNotificationConfigs/#{config["id"]}")
+      response2 = http_delete("/tasks/#{task["id"]}/pushNotificationConfigs/#{config["id"]}")
+
+      # Both should succeed (or second returns not-found gracefully)
+      response1.code.to_i.should.be < 500
+      response2.code.to_i.should.be < 500
+    end
+  end
+
+  # --- Error Cases ---
+
+  describe "when a client sends a request with a non-existent task ID" do
+    it "should respond with an error" do
+      response = http_delete("/tasks/nonexistent-#{SecureRandom.uuid}/pushNotificationConfigs/fake-id")
+
+      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 -- server supports push notifications
+
+  # describe "when the server does not support push notifications" do
+  #   it "should respond with a PushNotificationNotSupportedError" do
+  #   end
+  # end
+
+  # NOTE: Commented out -- requires webhook delivery verification
+
+  # describe "when a task changes status after config deletion" do
+  #   it "should not send notifications to the previously configured webhook URL" do
+  #   end
+  # end
+end

data/tests/rest/error_code_mappings_test.rb

@@ -0,0 +1,45 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: HTTP status code mappings for REST binding
+
+describe "Error Code Mappings (REST - HTTP Status)" do
+  describe "when a TaskNotFoundError occurs" do
+    it "should return HTTP 404 Not Found" do
+      response = http_get("/tasks/nonexistent-#{SecureRandom.uuid}")
+      response.code.to_i.should.equal 404
+    end
+  end
+
+  describe "when a TaskNotCancelableError occurs" do
+    it "should return HTTP 400 Bad Request" do
+      task = create_task!(text: "Cancel error code test")
+      response = http_post("/tasks/#{task["id"]}:cancel", {})
+      response.code.to_i.should.equal 400
+    end
+  end
+
+  describe "when an UnsupportedOperationError occurs" do
+    it "should return HTTP 400 Bad Request" do
+      response = http_get("/extendedAgentCard")
+      # Extended agent card returns unsupported operation
+      response.code.to_i.should.equal 400
+    end
+  end
+
+  # NOTE: Commented out -- difficult to trigger these specific errors
+
+  # describe "when a ContentTypeNotSupportedError occurs" do
+  #   it "should return HTTP 400 Bad Request" do
+  #   end
+  # end
+
+  # describe "when an InvalidAgentResponseError occurs" do
+  #   it "should return HTTP 500 Internal Server Error" do
+  #   end
+  # end
+
+  # describe "when a PushNotificationNotSupportedError occurs" do
+  #   it "should return HTTP 400 Bad Request" do
+  #   end
+  # end
+end