a2a-test-framework 0.4.0

data/tests/rest/error_handling_test.rb

@@ -0,0 +1,178 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Error handling applies to all REST endpoints
+
+describe "Error Handling (REST)" do
+  # --- Authentication Errors ---
+  # NOTE: Commented out -- reference server does not implement authentication
+
+  # describe "when a client sends a request without authentication credentials" do
+  #   it "should reject the request with an authentication error" do
+  #   end
+  #
+  #   it "should include authentication challenge information in the error response" do
+  #   end
+  #
+  #   it "should specify which authentication scheme is required" do
+  #   end
+  # end
+
+  # describe "when a client sends a request with invalid authentication credentials" do
+  #   it "should reject the request with an authentication error" do
+  #   end
+  # end
+
+  # describe "when a client sends a request with an expired bearer token" do
+  #   it "should reject the request with an authentication error" do
+  #   end
+  # end
+
+  # --- Authorization Errors ---
+  # NOTE: Commented out -- reference server does not implement authorization
+
+  # describe "when an authenticated client lacks required permissions for an operation" do
+  #   it "should return an authorization error" do
+  #   end
+  # end
+
+  # describe "when an authenticated client attempts to access another client's task" do
+  #   it "should not reveal the existence of that task" do
+  #   end
+  #
+  #   it "should not distinguish between does-not-exist and not-authorized" do
+  #   end
+  # end
+
+  # --- Validation Errors ---
+
+  describe "when a client sends a request with an invalid request body" do
+    it "should return an error response" do
+      # Send invalid JSON
+      uri = URI("#{BASE_URL}/message:send")
+      http = Net::HTTP.new(uri.host, uri.port)
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      request.body = "not valid json{{"
+      response = http.request(request)
+
+      response.code.to_i.should.be >= 400
+    end
+  end
+
+  # --- Resource Errors ---
+
+  describe "when a client requests a resource that does not exist" do
+    it "should return a not found error" do
+      response = http_get("/tasks/nonexistent-#{SecureRandom.uuid}")
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  # --- Error Payload Structure ---
+
+  describe "when any error response is returned" do
+    it "should contain an error with a code field" do
+      response = http_get("/tasks/nonexistent-#{SecureRandom.uuid}")
+
+      if response.code.to_i >= 400
+        data = parse_json(response)
+        if data.key?("error")
+          data["error"]["code"].should.not.be.nil
+        end
+      end
+      true.should.equal true
+    end
+
+    it "should contain a human-readable error message" do
+      response = http_get("/tasks/nonexistent-#{SecureRandom.uuid}")
+
+      if response.code.to_i >= 400
+        data = parse_json(response)
+        if data.key?("error")
+          data["error"]["message"].should.not.be.nil
+          data["error"]["message"].should.be.kind_of String
+        end
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- A2A-Specific Errors ---
+
+  describe "when a task ID does not correspond to an existing task" do
+    it "should return a TaskNotFoundError" do
+      response = http_get("/tasks/does-not-exist-#{SecureRandom.uuid}")
+      response.code.to_i.should.be >= 400
+    end
+  end
+
+  describe "when a CancelTask request targets a completed task" do
+    it "should return a TaskNotCancelableError" do
+      task = create_task!(text: "Error handling cancel test")
+      response = http_post("/tasks/#{task["id"]}:cancel", {})
+      response.code.to_i.should.be >= 400
+    end
+  end
+
+  # --- System Errors ---
+  # NOTE: Commented out -- cannot easily trigger internal server errors
+
+  # describe "when the server experiences a temporary internal failure" do
+  #   it "should return an appropriate error code indicating temporary unavailability" do
+  #   end
+  # end
+
+  # --- Unsupported Operations ---
+
+  describe "when a client requests an unsupported operation" do
+    it "should return an error for GetExtendedAgentCard (not supported)" do
+      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
+
+  # --- Remaining A2A Errors ---
+  # NOTE: Commented out -- require specific server configurations
+
+  # describe "when a client attempts push notification features on a non-supporting server" do
+  #   it "should return a PushNotificationNotSupportedError" do
+  #   end
+  # end
+
+  # describe "when a client sends a message with an unsupported media type" do
+  #   it "should return a ContentTypeNotSupportedError" do
+  #   end
+  # end
+
+  # describe "when an agent returns a malformed response" do
+  #   it "should be classified as InvalidAgentResponseError" do
+  #   end
+  # end
+
+  # describe "when the extended agent card is not configured despite capability being declared" do
+  #   it "should return an ExtendedAgentCardNotConfiguredError" do
+  #   end
+  # end
+
+  # describe "when a client does not declare support for a required extension" do
+  #   it "should return an ExtensionSupportRequiredError" do
+  #   end
+  # end
+
+  # describe "when a client sends a request with an unsupported protocol version" do
+  #   it "should return a VersionNotSupportedError" do
+  #   end
+  # end
+end

data/tests/rest/extension_versioning_test.rb

@@ -0,0 +1,44 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement extensions
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement extensions
+
+# # describe "Extension Versioning and Compatibility (REST)" do
+# #   # --- Version in URI ---
+# #
+# #   describe "when extensions are declared in the AgentCard" do
+# #     it "should include version information in each extension URI" do
+# #     end
+# #   end
+# #
+# #   describe "when a breaking change is made to an extension" do
+# #     it "should create a new URI for the incompatible version" do
+# #     end
+# #
+# #     it "should not reuse the old URI for the incompatible version" do
+# #     end
+# #   end
+# #
+# #   # --- Unsupported Extension Version Handling ---
+# #
+# #   describe "when a client requests a non-required extension version the agent does not support" do
+# #     it "should ignore the extension for that interaction" do
+# #     end
+# #
+# #     it "should proceed without it" do
+# #     end
+# #   end
+# #
+# #   describe "when a client requests a required extension version the agent does not support" do
+# #     it "should return an error indicating unsupported extension" do
+# #     end
+# #   end
+# #
+# #   describe "when a client requests a newer extension version" do
+# #     it "should not fall back to a previous extension version automatically" do
+# #     end
+# #   end
+# # end

data/tests/rest/field_presence_optionality_test.rb

@@ -0,0 +1,64 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Field presence and optionality applies to all REST endpoints
+
+describe "Field Presence and Optionality (REST)" do
+  # --- Required Fields ---
+
+  describe "when a client sends a message with all required fields present" do
+    it "should accept the message as valid" do
+      body = build_send_message_request(text: "All fields present")
+      response = http_post("/message:send", body)
+      response.code.to_i.should.equal 200
+    end
+  end
+
+  describe "when a client sends a message with a required field missing" do
+    it "should reject the message with an error" do
+      # Send request without message field (required)
+      response = http_post("/message:send", {})
+      response.code.to_i.should.be >= 400
+    end
+  end
+
+  describe "when a client sends a message with parts as empty array" do
+    it "should reject or handle gracefully" do
+      body = {
+        "message" => {
+          "messageId" => SecureRandom.uuid,
+          "role" => "ROLE_USER",
+          "parts" => []
+        }
+      }
+      response = http_post("/message:send", body)
+      # Server should either reject (400) or handle gracefully
+      (response.code.to_i >= 200 && response.code.to_i < 500).should.equal true
+    end
+  end
+
+  # --- Unrecognized Fields ---
+
+  describe "when a client sends a request with an unrecognized extra field" do
+    it "should ignore the unrecognized field and process normally" do
+      body = build_send_message_request(text: "Extra field test")
+      body["unknownExtraField"] = "should be ignored"
+      body["anotherUnknown"] = 42
+
+      response = http_post("/message:send", body)
+      response.code.to_i.should.equal 200
+    end
+  end
+
+  describe "when a client sends fields from a future protocol version" do
+    it "should process the request based on known fields" do
+      body = build_send_message_request(text: "Future compat test")
+      body["futureField_v99"] = { "data" => "from the future" }
+
+      response = http_post("/message:send", body)
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      (data.key?("task") || data.key?("message")).should.equal true
+    end
+  end
+end

data/tests/rest/functional_equivalence_test.rb

@@ -0,0 +1,23 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Requires testing across multiple protocol bindings simultaneously
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Requires testing across multiple protocol bindings simultaneously
+
+# # describe "Functional Equivalence Requirements (REST)" do
+# #   describe "when the agent supports multiple protocol bindings" do
+# #     it "should provide the same set of operations and capabilities across all bindings" do
+# #     end
+# #
+# #     it "should return semantically equivalent results for the same request across bindings" do
+# #     end
+# #
+# #     it "should map errors consistently using appropriate protocol-specific codes" do
+# #     end
+# #
+# #     it "should support the same authentication schemes across all bindings" do
+# #     end
+# #   end
+# # end

data/tests/rest/get_extended_agent_card_test.rb

@@ -0,0 +1,67 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: GET /extendedAgentCard
+# Request: GetExtendedAgentCardRequest (tenant)
+# Response: AgentCard
+#
+# NOTE: The reference server declares extendedAgentCard=false, so this
+# endpoint returns an UnsupportedOperationError.
+
+describe "GET /extendedAgentCard" do
+  # --- Authentication Requirement ---
+  # NOTE: Commented out -- reference server does not implement auth
+
+  # describe "when a client sends an authenticated request using a declared security scheme" do
+  #   it "should accept the request" do
+  #   end
+  # end
+
+  # describe "when a client sends a request without authentication" do
+  #   it "should reject the request with an authentication error" do
+  #   end
+  # end
+
+  # describe "when a client sends a request using an undeclared security scheme" do
+  #   it "should reject the request" do
+  #   end
+  # end
+
+  # --- Successful Retrieval ---
+  # NOTE: Commented out -- reference server doesn't support extended card
+
+  # describe "when an authenticated client retrieves the extended agent card" do
+  #   it "should respond with a complete AgentCard object" do
+  #   end
+  # end
+
+  # --- Availability / Capability Validation ---
+
+  describe "when the AgentCard declares extendedAgentCard capability as false" do
+    it "should respond with an error" do
+      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
+
+  # --- Card Replacement Behavior ---
+  # NOTE: Commented out -- not testable without extended card support
+
+  # describe "when a client retrieves the extended agent card after caching the public card" do
+  #   it "should replace the cached public AgentCard with the extended card" do
+  #   end
+  # end
+
+  # --- Error Cases ---
+  # NOTE: Commented out -- reference server responds with unsupported
+
+  # describe "when the agent declares support but has no extended card configured" do
+  #   it "should respond with an ExtendedAgentCardNotConfiguredError" do
+  #   end
+  # end
+end

data/tests/rest/get_task_push_notification_config_test.rb

@@ -0,0 +1,75 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: GET /tasks/{task_id}/pushNotificationConfigs/{id}
+# Request: GetTaskPushNotificationConfigRequest (taskId, id, tenant)
+# Response: TaskPushNotificationConfig
+
+describe "GET /tasks/{task_id}/pushNotificationConfigs/{id}" do
+  # --- Successful Retrieval ---
+
+  describe "when a client retrieves an existing push notification config" do
+    it "should respond with a PushNotificationConfig object" do
+      task = create_task!(text: "Get config test")
+      # Create a config first
+      body = build_push_notification_config(
+        task_id: task["id"],
+        url: "https://example.com/get-hook",
+        token: "get-token"
+      )
+      create_response = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      created = parse_json(create_response)
+      config_id = created["id"]
+
+      # Now retrieve it
+      response = http_get("/tasks/#{task["id"]}/pushNotificationConfigs/#{config_id}")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["id"].should.equal config_id
+      data["url"].should.equal "https://example.com/get-hook"
+    end
+
+    it "should include the webhook URL in the configuration details" do
+      task = create_task!(text: "URL check test")
+      body = build_push_notification_config(
+        task_id: task["id"],
+        url: "https://example.com/url-check"
+      )
+      create_response = http_post("/tasks/#{task["id"]}/pushNotificationConfigs", body)
+      created = parse_json(create_response)
+
+      response = http_get("/tasks/#{task["id"]}/pushNotificationConfigs/#{created["id"]}")
+      data = parse_json(response)
+
+      data["url"].should.equal "https://example.com/url-check"
+    end
+  end
+
+  # --- Error Cases ---
+
+  describe "when a client requests a non-existent config ID" do
+    it "should respond with an error" do
+      task = create_task!(text: "Missing config test")
+      response = http_get("/tasks/#{task["id"]}/pushNotificationConfigs/nonexistent-#{SecureRandom.uuid}")
+
+      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 doesn't implement auth
+
+  # describe "when the server does not support push notifications" do
+  #   it "should respond with a PushNotificationNotSupportedError" do
+  #   end
+  # end
+
+  # describe "when a client lacks access to the configuration" do
+  #   it "should respond with an error" do
+  #   end
+  # end
+end

data/tests/rest/get_task_test.rb

@@ -0,0 +1,134 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: GET /tasks/{id}
+# Request: GetTaskRequest (id, historyLength, tenant)
+# Response: Task
+
+describe "GET /tasks/{id}" do
+  # --- Successful Retrieval ---
+
+  describe "when a client retrieves an existing task" do
+    it "should respond with HTTP 200 and a Task object" do
+      task = create_task!(text: "Task for retrieval")
+      response = http_get("/tasks/#{task["id"]}")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["id"].should.equal task["id"]
+      data.should.be.kind_of Hash
+    end
+
+    it "should include the current status in the Task object" do
+      task = create_task!(text: "Status check")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      data["status"].should.not.be.nil
+      data["status"].should.be.kind_of Hash
+      data["status"]["state"].should.not.be.nil
+    end
+
+    it "should include any generated artifacts in the Task object" do
+      task = create_task!(text: "Artifact check")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      if data["artifacts"]
+        data["artifacts"].should.be.kind_of Array
+        data["artifacts"].each do |artifact|
+          artifact["artifactId"].should.not.be.nil
+          artifact["parts"].should.be.kind_of Array
+        end
+      end
+      true.should.equal true
+    end
+
+    it "should include contextId in the Task object" do
+      task = create_task!(text: "Context check")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      data["contextId"].should.not.be.nil
+      data["contextId"].should.be.kind_of String
+    end
+  end
+
+  describe "when a task has completed" do
+    it "should return a status with state TASK_STATE_COMPLETED" do
+      task = create_task!(text: "Completed task")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      data["status"]["state"].should.equal "TASK_STATE_COMPLETED"
+    end
+  end
+
+  # --- History Length Parameter ---
+
+  describe "when a client sends a GetTask request with historyLength" do
+    it "should include history messages when historyLength is positive" do
+      task = create_task!(text: "History test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=10")
+      data = parse_json(response)
+
+      if data["history"]
+        data["history"].should.be.kind_of Array
+        data["history"].length.should.be > 0
+      end
+      true.should.equal true
+    end
+
+    it "should omit history when historyLength is 0" do
+      task = create_task!(text: "No history test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=0")
+      data = parse_json(response)
+
+      # When historyLength=0, history should be omitted or empty
+      if data.key?("history")
+        (data["history"].nil? || data["history"].empty?).should.equal true
+      else
+        true.should.equal true
+      end
+    end
+
+    it "should limit history to the specified number of messages" do
+      # Create a task with some history
+      task = create_task!(text: "Multi-message task")
+      response = http_get("/tasks/#{task["id"]}?historyLength=1")
+      data = parse_json(response)
+
+      if data["history"]
+        data["history"].length.should.be <= 1
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Error Cases ---
+
+  describe "when a client sends a GetTask request with a non-existent task ID" do
+    it "should respond with an error (404 or error body)" do
+      response = http_get("/tasks/nonexistent-task-id-#{SecureRandom.uuid}")
+
+      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 GetTask request for a task not accessible to the client" do
+    it "should respond with an error indistinguishable from not-found" do
+      response = http_get("/tasks/inaccessible-task-#{SecureRandom.uuid}")
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+end

data/tests/rest/history_length_semantics_test.rb

@@ -0,0 +1,91 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: historyLength semantics apply to:
+# REST: GET /tasks/{id}, GET /tasks, POST /message:send
+
+describe "History Length Semantics (REST)" do
+  # --- Unset/Undefined ---
+
+  describe "when a client sends a request without specifying historyLength" do
+    it "should return the server default amount of history" do
+      task = create_task!(text: "Default history test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      # Server should return history by default
+      if data["history"]
+        data["history"].should.be.kind_of Array
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Zero Value ---
+
+  describe "when a client sends a request with historyLength set to 0" do
+    it "should omit or empty the history field" do
+      task = create_task!(text: "Zero history test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=0")
+      data = parse_json(response)
+
+      if data.key?("history")
+        (data["history"].nil? || data["history"].empty?).should.equal true
+      else
+        true.should.equal true
+      end
+    end
+  end
+
+  # --- Positive Value ---
+
+  describe "when a client sends a request with historyLength set to a positive number" do
+    it "should return at most that many recent messages" do
+      task = create_task!(text: "Limited history test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=1")
+      data = parse_json(response)
+
+      if data["history"]
+        data["history"].length.should.be <= 1
+      end
+      true.should.equal true
+    end
+  end
+
+  describe "when historyLength is greater than total available messages" do
+    it "should return all available messages" do
+      task = create_task!(text: "Large history test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=1000")
+      data = parse_json(response)
+
+      if data["history"]
+        data["history"].should.be.kind_of Array
+        # Should return whatever is available, not error
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Consistency Across Operations ---
+
+  describe "when historyLength is used in GetTask vs ListTasks" do
+    it "should apply the same truncation semantics in both operations" do
+      task = create_task!(text: "Consistency test")
+
+      # GetTask with historyLength=1
+      get_resp = http_get("/tasks/#{task["id"]}?historyLength=1")
+      get_data = parse_json(get_resp)
+
+      # ListTasks with historyLength=1
+      list_resp = http_get("/tasks?historyLength=1&contextId=#{task["contextId"]}")
+      list_data = parse_json(list_resp)
+
+      if get_data["history"] && list_data["tasks"].length > 0
+        list_task = list_data["tasks"].find { |t| t["id"] == task["id"] }
+        if list_task && list_task["history"]
+          list_task["history"].length.should.be <= 1
+        end
+      end
+      true.should.equal true
+    end
+  end
+end