a2a-test-framework 0.4.0

data/tests/rest/security_considerations_test.rb

@@ -0,0 +1,101 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement security features
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement security features
+
+# # describe "Security Considerations (REST)" do
+# #   # --- Data Access and Authorization Scoping ---
+# #
+# #   describe "when any request is received" do
+# #     it "should implement authorization checks on every operation request" do
+# #     end
+# #
+# #     it "should scope results to the caller's authorized access boundaries" do
+# #     end
+# #
+# #     it "should scope results even without filter parameters" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a ListTasks request" do
+# #     it "should only return tasks visible to the authenticated client" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a GetTask request" do
+# #     it "should verify the client has access to the requested task" do
+# #     end
+# #   end
+# #
+# #   describe "when authorization checks are performed" do
+# #     it "should occur before any database queries" do
+# #     end
+# #
+# #     it "should not leak information about resources outside the caller's scope" do
+# #     end
+# #   end
+# #
+# #   # --- Push Notification Security ---
+# #
+# #   describe "when the agent sends webhook notifications" do
+# #     it "should include authentication credentials as specified in PushNotificationConfig" do
+# #     end
+# #   end
+# #
+# #   describe "when a client creates a push notification config with a webhook URL" do
+# #     it "should validate the URL to prevent SSRF attacks" do
+# #     end
+# #
+# #     it "should reject private IP ranges for webhooks" do
+# #     end
+# #   end
+# #
+# #   describe "when a client receives a webhook request" do
+# #     it "should validate webhook authenticity using authentication credentials" do
+# #     end
+# #
+# #     it "should respond with HTTP 2xx for successful receipt" do
+# #     end
+# #   end
+# #
+# #   describe "when configuring webhook URLs" do
+# #     it "should use HTTPS to protect payload confidentiality" do
+# #     end
+# #   end
+# #
+# #   # --- Extended Agent Card Access Control ---
+# #
+# #   describe "when a client requests the extended agent card" do
+# #     it "should require authentication" do
+# #     end
+# #
+# #     it "should validate client permissions before returning privileged info" do
+# #     end
+# #   end
+# #
+# #   # --- General Security Best Practices ---
+# #
+# #   describe "when handling requests in production" do
+# #     it "should use encrypted communication" do
+# #     end
+# #
+# #     it "should validate all input parameters before processing" do
+# #     end
+# #   end
+# #
+# #   describe "when handling credentials" do
+# #     it "should treat API keys, tokens, and credentials as secrets" do
+# #     end
+# #
+# #     it "should not include sensitive information in logs" do
+# #     end
+# #   end
+# #
+# #   describe "when handling personal data" do
+# #     it "should comply with applicable data protection regulations" do
+# #     end
+# #   end
+# # end

data/tests/rest/send_message_test.rb

@@ -0,0 +1,230 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: POST /message:send
+# Request: SendMessageRequest (message, configuration, metadata)
+# Response: SendMessageResponse (task | message)
+
+describe "POST /message:send" do
+  # --- Response Type Behavior ---
+
+  describe "when a client sends a SendMessageRequest with a valid message" do
+    it "should respond with HTTP 200" do
+      body = build_send_message_request(text: "Hello")
+      response = http_post("/message:send", body)
+      response.code.to_i.should.equal 200
+    end
+
+    it "should respond with a Task object containing a valid task ID and status" do
+      body = build_send_message_request(text: "Hello")
+      response = http_post("/message:send", body)
+      data = parse_json(response)
+
+      if data.key?("task")
+        data["task"].should.be.kind_of Hash
+        data["task"]["id"].should.not.be.nil
+        data["task"]["id"].should.be.kind_of String
+        data["task"]["id"].length.should.be > 0
+        data["task"]["status"].should.not.be.nil
+        data["task"]["status"].should.be.kind_of Hash
+        data["task"]["status"]["state"].should.not.be.nil
+      end
+      true.should.equal true
+    end
+
+    it "should return either a Task or a Message, never both" do
+      body = build_send_message_request(text: "Hello")
+      response = http_post("/message:send", body)
+      data = parse_json(response)
+
+      has_task = data.key?("task") && !data["task"].nil?
+      has_message = data.key?("message") && !data["message"].nil?
+
+      (has_task || has_message).should.equal true
+      (has_task && has_message).should.equal false
+    end
+
+    it "should return immediately without blocking indefinitely" do
+      body = build_send_message_request(text: "Quick test")
+      start_time = Time.now
+      response = http_post("/message:send", body)
+      elapsed = Time.now - start_time
+
+      response.code.to_i.should.equal 200
+      elapsed.should.be < 30
+    end
+  end
+
+  describe "when the server creates a Task to process the message" do
+    it "should return a Task with a valid state" do
+      body = build_send_message_request(text: "Test task creation")
+      response = http_post("/message:send", body)
+      data = parse_json(response)
+
+      if data.key?("task")
+        state = data["task"]["status"]["state"]
+        valid_states = %w[
+          TASK_STATE_SUBMITTED TASK_STATE_WORKING TASK_STATE_COMPLETED
+          TASK_STATE_FAILED TASK_STATE_CANCELED TASK_STATE_INPUT_REQUIRED
+          TASK_STATE_AUTH_REQUIRED TASK_STATE_REJECTED
+        ]
+        valid_states.should.include state
+      end
+      true.should.equal true
+    end
+
+    it "should include a contextId in the Task" do
+      body = build_send_message_request(text: "Context test")
+      response = http_post("/message:send", body)
+      data = parse_json(response)
+
+      if data.key?("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
+
+  # --- Error Cases ---
+
+  describe "when a client sends a SendMessageRequest referencing a non-existent task ID" do
+    it "should respond with an error" do
+      body = build_send_message_request(text: "Hello")
+      body["message"]["taskId"] = "nonexistent-task-id-#{SecureRandom.uuid}"
+      response = http_post("/message:send", body)
+
+      # Should get an error (4xx or error in 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
+
+  describe "when a client sends a SendMessageRequest referencing a completed task" do
+    it "should respond with an error indicating unsupported operation" do
+      # Create and complete a task first
+      task = create_task!(text: "Complete me")
+
+      if task["status"]["state"] == "TASK_STATE_COMPLETED"
+        # Send another message referencing the completed task
+        body = build_send_message_request(text: "Follow up")
+        body["message"]["taskId"] = task["id"]
+        response = http_post("/message:send", body)
+
+        if response.code.to_i >= 400
+          true.should.equal true
+        else
+          data = parse_json(response)
+          data.key?("error").should.equal true
+        end
+      else
+        true.should.equal true
+      end
+    end
+  end
+
+  # --- Request Structure ---
+
+  describe "when validating request structure" do
+    it "should accept a request with only a message field" do
+      body = build_send_message_request(text: "Minimal request")
+      response = http_post("/message:send", body)
+      response.code.to_i.should.equal 200
+    end
+
+    it "should accept a request with message and metadata" do
+      body = build_send_message_request(text: "With metadata", metadata: { "key" => "value" })
+      response = http_post("/message:send", body)
+      response.code.to_i.should.equal 200
+    end
+  end
+
+  # --- HTTP Method and Path ---
+
+  describe "when verifying HTTP method and path" do
+    it "should respond to POST on /message:send" do
+      body = build_send_message_request(text: "POST test")
+      response = http_post("/message:send", body)
+      response.code.to_i.should.not.equal 404
+      response.code.to_i.should.not.equal 405
+    end
+
+    it "should reject GET requests on /message:send" do
+      response = http_get("/message:send")
+      response.code.to_i.should.equal 405
+    end
+  end
+
+  # --- Content-Type Handling ---
+
+  describe "when verifying content-type handling" do
+    it "should return application/json or application/a2a+json Content-Type in response" do
+      body = build_send_message_request(text: "Content-Type test")
+      response = http_post("/message:send", body)
+      content_type = response["Content-Type"].to_s
+      (content_type.include?("application/json") || content_type.include?("application/a2a+json")).should.equal true
+    end
+  end
+
+  # --- SendMessageConfiguration: Blocking Mode ---
+  # NOTE: The reference server completes tasks synchronously, so blocking/non-blocking
+  # behavior is effectively the same. These tests verify the response is valid.
+
+  describe "when return_immediately is not set (blocking mode default)" do
+    it "should return a task in a terminal or actionable state" do
+      body = build_send_message_request(text: "Blocking test")
+      response = http_post("/message:send", body)
+      data = parse_json(response)
+
+      if data.key?("task")
+        state = data["task"]["status"]["state"]
+        # In blocking mode, should return terminal or actionable state
+        actionable_states = %w[
+          TASK_STATE_COMPLETED TASK_STATE_FAILED TASK_STATE_CANCELED
+          TASK_STATE_REJECTED TASK_STATE_INPUT_REQUIRED TASK_STATE_AUTH_REQUIRED
+        ]
+        actionable_states.should.include state
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- SendMessageConfiguration: Non-Blocking Mode ---
+  # NOTE: Commented out -- reference server completes synchronously
+
+  # describe "when a client sends a SendMessageRequest with return_immediately set to true" do
+  #   it "should return immediately after creating the task" do
+  #   end
+  #
+  #   it "should not wait for the task to reach a terminal state" do
+  #   end
+  #
+  #   it "should return a task in an in-progress state" do
+  #   end
+  #
+  #   it "should require the client to poll for updates using GetTask or subscribe" do
+  #   end
+  # end
+
+  # --- SendMessageConfiguration: No Effect Cases ---
+  # NOTE: Commented out -- requires async server behavior
+
+  # describe "when return_immediately is set but the agent returns a direct Message" do
+  #   it "should have no effect on the response behavior" do
+  #   end
+  # end
+
+  # describe "when return_immediately is set on a streaming operation" do
+  #   it "should have no effect on the streaming behavior" do
+  #   end
+  # end
+
+  # describe "when return_immediately is set and push notifications are configured" do
+  #   it "should operate push notification delivery independently of execution mode" do
+  #   end
+  # end
+end

data/tests/rest/send_streaming_message_test.rb

@@ -0,0 +1,129 @@
+require "a2a_test_framework/test_helper"
+require "a2a_test_framework/sse_client"
+
+# REST endpoint: POST /message:stream
+# Request: SendMessageRequest
+# Response: StreamResponse (SSE stream containing Task, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent)
+
+describe "POST /message:stream" do
+  # --- Streaming Connection Establishment ---
+
+  describe "when a client sends a SendStreamingMessage request with a valid message" do
+    it "should establish a streaming connection and return events" do
+      body = build_send_message_request(text: "Stream me!")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+
+      events.length.should.be > 0
+    end
+  end
+
+  # --- Task Lifecycle Stream Pattern ---
+
+  describe "when the agent returns a Task response via stream" do
+    it "should send a Task object as the first item in the stream" do
+      body = build_send_message_request(text: "First event test")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+
+      events.length.should.be > 0
+      first = events.first.data
+      first.should.be.kind_of Hash
+      # First event should contain a task snapshot
+      first.key?("task").should.equal true
+      first["task"]["id"].should.not.be.nil
+      first["task"]["status"].should.not.be.nil
+    end
+
+    it "should include TaskArtifactUpdateEvent in the stream" do
+      body = build_send_message_request(text: "Artifact event test")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+
+      artifact_events = events.select { |e| e.data.is_a?(Hash) && e.data.key?("artifactUpdate") }
+      artifact_events.length.should.be > 0
+
+      ae = artifact_events.first.data["artifactUpdate"]
+      ae["taskId"].should.not.be.nil
+      ae["artifact"].should.not.be.nil
+      ae["artifact"]["parts"].should.be.kind_of Array
+    end
+
+    it "should include TaskStatusUpdateEvent with terminal state" do
+      body = build_send_message_request(text: "Status event test")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+
+      status_events = events.select { |e| e.data.is_a?(Hash) && e.data.key?("statusUpdate") }
+      status_events.length.should.be > 0
+
+      # Last status event should have a terminal state
+      last_status = status_events.last.data["statusUpdate"]
+      last_status["status"]["state"].should.equal "TASK_STATE_COMPLETED"
+    end
+  end
+
+  describe "when the task reaches a terminal state during streaming" do
+    it "should close the stream when task reaches completed state" do
+      body = build_send_message_request(text: "Stream close test")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+
+      # Stream should have ended (we got events back, not a timeout with no data)
+      events.length.should.be > 0
+
+      # Last event should indicate terminal state
+      last_event = events.last.data
+      if last_event.is_a?(Hash) && last_event.key?("statusUpdate")
+        last_event["statusUpdate"]["status"]["state"].should.equal "TASK_STATE_COMPLETED"
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Event Ordering ---
+
+  describe "when validating event ordering" do
+    it "should deliver events in correct order: task, artifact, status(completed)" do
+      body = build_send_message_request(text: "Order test")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+
+      events.length.should.be >= 3
+
+      # First should be task snapshot
+      events[0].data.key?("task").should.equal true
+      # Second should be artifact update
+      events[1].data.key?("artifactUpdate").should.equal true
+      # Third should be status completed
+      events[2].data.key?("statusUpdate").should.equal true
+      events[2].data["statusUpdate"]["status"]["state"].should.equal "TASK_STATE_COMPLETED"
+    end
+  end
+
+  # --- Error Cases ---
+  # NOTE: Commented out -- server supports streaming, cannot easily test unsupported case
+
+  # describe "when the server does not support streaming" do
+  #   it "should respond with an UnsupportedOperationError" do
+  #   end
+  # end
+
+  # --- Message-Only Stream Pattern ---
+  # NOTE: Commented out -- reference server always returns Task-based streams
+
+  # describe "when the agent returns a Message response via stream" do
+  #   it "should contain exactly one Message object in the stream" do
+  #   end
+  #
+  #   it "should close the stream immediately after the Message" do
+  #   end
+  # end
+
+  # --- Error cases for referencing terminal tasks ---
+  # NOTE: Commented out -- streaming endpoint creates new tasks in reference server
+
+  # describe "when a client sends a streaming request referencing a completed task" do
+  #   it "should respond with an UnsupportedOperationError" do
+  #   end
+  # end
+
+  # describe "when a client sends a streaming request referencing a non-existent task ID" do
+  #   it "should respond with a TaskNotFoundError" do
+  #   end
+  # end
+end

data/tests/rest/service_parameters_test.rb

@@ -0,0 +1,52 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement A2A service parameters
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement A2A service parameters
+
+# # describe "Service Parameters (REST)" do
+# #   # --- Key Case Insensitivity ---
+# #
+# #   describe "when a client sends service parameter keys in different cases" do
+# #     it "should treat A2A-Version and a2a-version as the same parameter" do
+# #     end
+# #
+# #     it "should treat A2A-Extensions and a2a-extensions as the same parameter" do
+# #     end
+# #   end
+# #
+# #   # --- Value Case Sensitivity ---
+# #
+# #   describe "when a client sends service parameter values" do
+# #     it "should treat values as case-sensitive" do
+# #     end
+# #   end
+# #
+# #   # --- A2A-Version Parameter ---
+# #
+# #   describe "when A2A-Version is set to an unsupported version" do
+# #     it "should respond with a VersionNotSupportedError" do
+# #     end
+# #   end
+# #
+# #   describe "when A2A-Version is set to a supported version" do
+# #     it "should process the request normally" do
+# #     end
+# #   end
+# #
+# #   # --- A2A-Extensions Parameter ---
+# #
+# #   describe "when A2A-Extensions contains multiple extension URIs" do
+# #     it "should interpret the value as a comma-separated list of extension URIs" do
+# #     end
+# #   end
+# #
+# #   # --- Prefix Convention ---
+# #
+# #   describe "when examining specification-defined service parameters" do
+# #     it "should all be prefixed with a2a-" do
+# #     end
+# #   end
+# # end

data/tests/rest/streaming_event_delivery_test.rb

@@ -0,0 +1,58 @@
+require "a2a_test_framework/test_helper"
+require "a2a_test_framework/sse_client"
+
+# Cross-cutting: Streaming event delivery applies to:
+# REST: POST /message:stream, GET /tasks/{id}:subscribe
+
+describe "Streaming Event Delivery (REST)" do
+  # --- Event Ordering ---
+
+  describe "when a task generates multiple events in sequence" do
+    it "should deliver all events in the order they were generated" do
+      body = build_send_message_request(text: "Event order test")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+
+      events.length.should.be >= 3
+
+      # Verify ordering: task first, then artifact, then status completed
+      events[0].data.key?("task").should.equal true
+      events[1].data.key?("artifactUpdate").should.equal true
+      events[2].data.key?("statusUpdate").should.equal true
+    end
+
+    it "should not reorder events during transmission" do
+      body = build_send_message_request(text: "No reorder test")
+      events = SSEClient.post_stream("/message:stream", body, timeout_seconds: 10)
+
+      # The last status event should be terminal
+      status_events = events.select { |e| e.data.is_a?(Hash) && e.data.key?("statusUpdate") }
+      if status_events.length > 0
+        last_status = status_events.last.data["statusUpdate"]["status"]["state"]
+        last_status.should.equal "TASK_STATE_COMPLETED"
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Multiple Streams Per Task ---
+  # NOTE: Commented out -- requires tasks in non-terminal state for subscribe
+
+  # describe "when multiple clients subscribe to the same task" do
+  #   it "should serve multiple concurrent streams simultaneously" do
+  #   end
+  #
+  #   it "should broadcast events to all active streams for a task" do
+  #   end
+  #
+  #   it "should deliver the same events in the same order to each stream" do
+  #   end
+  # end
+
+  # describe "when one client closes their stream" do
+  #   it "should keep other active streams open and receiving events" do
+  #   end
+  #
+  #   it "should not affect the task lifecycle" do
+  #   end
+  # end
+end

data/tests/rest/subscribe_to_task_test.rb

@@ -0,0 +1,99 @@
+require "a2a_test_framework/test_helper"
+require "a2a_test_framework/sse_client"
+
+# REST endpoint: GET /tasks/{id}:subscribe
+# Request: SubscribeToTaskRequest (id, tenant)
+# Response: stream of StreamResponse (SSE)
+
+describe "GET /tasks/{id}:subscribe" do
+  # --- Stream Initialization ---
+  # NOTE: The reference server completes tasks synchronously, so subscribing
+  # to a task after SendMessage will always find it in a terminal state.
+  # We can only test error cases here.
+
+  # describe "when a client subscribes to a working task" do
+  #   it "should send a Task object as the first event in the stream" do
+  #   end
+  #
+  #   it "should represent the current state of the task at time of subscription" do
+  #   end
+  # end
+
+  # --- Error Cases ---
+
+  describe "when a client subscribes to a non-existent task ID" do
+    it "should respond with an error" do
+      response = http_get("/tasks/nonexistent-#{SecureRandom.uuid}:subscribe")
+
+      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 subscribes to a task in completed state" do
+    it "should respond with an error indicating unsupported operation" do
+      task = create_task!(text: "Subscribe to completed")
+      task["status"]["state"].should.equal "TASK_STATE_COMPLETED"
+
+      response = http_get("/tasks/#{task["id"]}:subscribe")
+
+      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 subscribes to a task not accessible to the client" do
+    it "should respond with an error" do
+      response = http_get("/tasks/inaccessible-#{SecureRandom.uuid}:subscribe")
+
+      if response.code.to_i >= 400
+        true.should.equal true
+      else
+        data = parse_json(response)
+        data.key?("error").should.equal true
+      end
+    end
+  end
+
+  # --- Stream Content ---
+  # NOTE: Commented out -- requires a task in non-terminal state
+
+  # describe "when the subscribed task status changes" do
+  #   it "should deliver a TaskStatusUpdateEvent object" do
+  #   end
+  # end
+
+  # describe "when the subscribed task generates a new artifact" do
+  #   it "should deliver a TaskArtifactUpdateEvent object" do
+  #   end
+  # end
+
+  # --- Stream Termination ---
+  # NOTE: Commented out -- requires a task in non-terminal state
+
+  # describe "when the subscribed task reaches a terminal state" do
+  #   it "should terminate the stream when task reaches completed state" do
+  #   end
+  # end
+
+  # describe "when the subscribed task is in a non-terminal state" do
+  #   it "should keep the stream open while task is in working state" do
+  #   end
+  # end
+
+  # --- Server Not Supporting Streaming ---
+  # NOTE: Commented out -- reference server supports streaming
+
+  # describe "when the server does not support streaming" do
+  #   it "should respond with an UnsupportedOperationError" do
+  #   end
+  # end
+end