a2a-test-framework 0.4.0

data/tests/grpc/send_message_test.rb

@@ -0,0 +1,141 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# # describe "A2AService/SendMessage" do
+# #   # --- Response Type Behavior ---
+# #
+# #   describe "when a client sends a SendMessageRequest with a valid message" do
+# #     it "should respond with a Task object containing a valid task ID and status" do
+# #     end
+# #
+# #     it "should return either a Task or a Message, never both" do
+# #     end
+# #
+# #     it "should return immediately without blocking on task completion" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a SendMessageRequest with a simple message" do
+# #     it "should respond with a Message object containing a role" do
+# #     end
+# #
+# #     it "should respond with a Message object containing one or more Parts" do
+# #     end
+# #   end
+# #
+# #   describe "when the server creates a Task to process the message asynchronously" do
+# #     it "should return a Task that MAY be in a non-terminal state" do
+# #     end
+# #
+# #     it "should allow task processing to continue after response is returned" do
+# #     end
+# #   end
+# #
+# #   # --- Response Structure Validation ---
+# #
+# #   describe "when validating the response structure" do
+# #     it "should contain exactly one of Task or Message" do
+# #     end
+# #
+# #     it "should never contain both a Task and a Message simultaneously" do
+# #     end
+# #   end
+# #
+# #   # --- Error Cases ---
+# #
+# #   describe "when a client sends a Part with an unsupported media type" do
+# #     it "should respond with a ContentTypeNotSupportedError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a SendMessageRequest referencing a completed task" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a SendMessageRequest referencing a canceled task" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a SendMessageRequest referencing a rejected task" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a SendMessageRequest referencing a non-existent task ID" do
+# #     it "should respond with a TaskNotFoundError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a SendMessageRequest referencing a task not accessible to the client" do
+# #     it "should respond with a TaskNotFoundError" do
+# #     end
+# #   end
+# #
+# #   # --- SendMessageConfiguration: Blocking Mode (Default) ---
+# #
+# #   describe "when a client sends a SendMessageRequest with return_immediately unset (blocking mode)" do
+# #     it "should wait until the task reaches completed state before returning" do
+# #     end
+# #
+# #     it "should wait until the task reaches failed state before returning" do
+# #     end
+# #
+# #     it "should wait until the task reaches canceled state before returning" do
+# #     end
+# #
+# #     it "should wait until the task reaches rejected state before returning" do
+# #     end
+# #
+# #     it "should wait until the task reaches input_required state before returning" do
+# #     end
+# #
+# #     it "should wait until the task reaches auth_required state before returning" do
+# #     end
+# #
+# #     it "should include the latest task state with all artifacts and status information" do
+# #     end
+# #
+# #     it "should behave in blocking mode by default when return_immediately is not specified" do
+# #     end
+# #   end
+# #
+# #   # --- SendMessageConfiguration: Non-Blocking Mode ---
+# #
+# #   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 ---
+# #
+# #   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/grpc/send_streaming_message_test.rb

@@ -0,0 +1,122 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# # describe "A2AService/SendStreamingMessage" do
+# #   # --- Streaming Connection Establishment ---
+# #
+# #   describe "when a client sends a SendStreamingMessage request with a valid message" do
+# #     it "should establish a server-streaming connection for real-time updates" do
+# #     end
+# #   end
+# #
+# #   # --- Message-Only Stream Pattern ---
+# #
+# #   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
+# #
+# #     it "should not contain any TaskStatusUpdateEvent objects" do
+# #     end
+# #
+# #     it "should not contain any TaskArtifactUpdateEvent objects" do
+# #     end
+# #
+# #     it "should not contain any Task objects" do
+# #     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
+# #     end
+# #
+# #     it "should follow the Task with TaskStatusUpdateEvent objects" do
+# #     end
+# #
+# #     it "should follow the Task with TaskArtifactUpdateEvent objects" do
+# #     end
+# #   end
+# #
+# #   describe "when the task reaches a terminal state during streaming" do
+# #     it "should close the stream when task reaches completed state" do
+# #     end
+# #
+# #     it "should close the stream when task reaches failed state" do
+# #     end
+# #
+# #     it "should close the stream when task reaches canceled state" do
+# #     end
+# #
+# #     it "should close the stream when task reaches rejected state" do
+# #     end
+# #
+# #     it "should not close the stream while task is in working state" do
+# #     end
+# #   end
+# #
+# #   # --- Immediate Feedback Requirement ---
+# #
+# #   describe "when a client is consuming a stream" do
+# #     it "should provide immediate feedback on progress" do
+# #     end
+# #
+# #     it "should deliver intermediate results as they become available" do
+# #     end
+# #   end
+# #
+# #   # --- Error Cases ---
+# #
+# #   describe "when the server does not support streaming" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   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 canceled task" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a streaming request referencing a rejected task" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a streaming request with an unsupported media type" do
+# #     it "should respond with a ContentTypeNotSupportedError" 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
+# #
+# #   describe "when a client sends a streaming request referencing a task not accessible to the client" do
+# #     it "should respond with a TaskNotFoundError" do
+# #     end
+# #   end
+# #
+# #   # --- Stream Response Structure ---
+# #
+# #   describe "when validating the stream initial response structure" do
+# #     it "should contain exactly one of Task or Message as initial response" do
+# #     end
+# #
+# #     it "should never contain both Task and Message as initial response" do
+# #     end
+# #   end
+# # end

data/tests/grpc/streaming_event_delivery_test.rb

@@ -0,0 +1,48 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# # describe "Streaming Event Delivery (gRPC)" 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
+# #     end
+# #
+# #     it "should not reorder events during transmission" do
+# #     end
+# #
+# #     it "should preserve event ordering regardless of protocol binding" do
+# #     end
+# #   end
+# #
+# #   # --- Multiple Streams Per Task ---
+# #
+# #   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
+# #
+# #   describe "when a single client opens two subscription streams for the same task" do
+# #     it "should deliver events to both streams" do
+# #     end
+# #   end
+# # end

data/tests/grpc/subscribe_to_task_test.rb

@@ -0,0 +1,92 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# # describe "A2AService/SubscribeToTask" do
+# #   # --- Stream Initialization ---
+# #
+# #   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
+# #
+# #     it "should not require a separate GetTask call to avoid missing updates" do
+# #     end
+# #   end
+# #
+# #   # --- Stream Content ---
+# #
+# #   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 ---
+# #
+# #   describe "when the subscribed task reaches a terminal state" do
+# #     it "should terminate the stream when task reaches completed state" do
+# #     end
+# #
+# #     it "should terminate the stream when task reaches failed state" do
+# #     end
+# #
+# #     it "should terminate the stream when task reaches canceled state" do
+# #     end
+# #
+# #     it "should terminate the stream when task reaches rejected 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
+# #
+# #   # --- Error Cases ---
+# #
+# #   describe "when the server does not support streaming" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client subscribes to a non-existent task ID" do
+# #     it "should respond with a TaskNotFoundError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client subscribes to a task not accessible to the client" do
+# #     it "should respond with a TaskNotFoundError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client subscribes to a task in completed state" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client subscribes to a task in failed state" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client subscribes to a task in canceled state" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client subscribes to a task in rejected state" do
+# #     it "should respond with an UnsupportedOperationError" do
+# #     end
+# #   end
+# # end

data/tests/grpc/versioning_test.rb

@@ -0,0 +1,32 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- gRPC binding not supported by reference server
+
+# # describe "Protocol Versioning (gRPC)" do
+# #   # --- Version Format ---
+# #
+# #   describe "when a client sends a request with a2a-version metadata" do
+# #     it "should recognize Major.Minor format as valid" do
+# #     end
+# #
+# #     it "should not require patch version numbers" do
+# #     end
+# #   end
+# #
+# #   describe "when the server returns version information" do
+# #     it "should not include patch version numbers" do
+# #     end
+# #   end
+# #
+# #   describe "when performing version negotiation" do
+# #     it "should not consider patch version differences" do
+# #     end
+# #
+# #     it "should treat versions differing only by patch as compatible" do
+# #     end
+# #   end
+# # end

data/tests/rest/agent_card_caching_test.rb

@@ -0,0 +1,39 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement caching headers
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement caching headers
+
+# # describe "Agent Card Caching (REST)" do
+# #   # --- Server Requirements ---
+# #
+# #   describe "when a client fetches the Agent Card" do
+# #     it "should include a Cache-Control header with a max-age directive" do
+# #     end
+# #
+# #     it "should include an ETag header derived from version or content hash" do
+# #     end
+# #
+# #     it "should MAY include a Last-Modified header" do
+# #     end
+# #   end
+# #
+# #   # --- Client Requirements ---
+# #
+# #   describe "when a client caches the Agent Card" do
+# #     it "should honor HTTP caching semantics as defined in RFC 9111" do
+# #     end
+# #   end
+# #
+# #   describe "when a client has an expired cached Agent Card" do
+# #     it "should use conditional requests with If-None-Match or If-Modified-Since" do
+# #     end
+# #   end
+# #
+# #   describe "when the server does not include caching headers" do
+# #     it "should MAY apply an implementation-specific default cache duration" do
+# #     end
+# #   end
+# # end

data/tests/rest/agent_card_signing_test.rb

@@ -0,0 +1,74 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement agent card signing
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement agent card signing
+
+# # describe "Agent Card Signing (REST)" do
+# #   # --- Canonicalization Requirements ---
+# #
+# #   describe "when an Agent Card is signed" do
+# #     it "should canonicalize content using JCS (RFC 8785) before signing" do
+# #     end
+# #
+# #     it "should omit optional fields not explicitly set before canonicalization" do
+# #     end
+# #
+# #     it "should include optional fields explicitly set to defaults" do
+# #     end
+# #
+# #     it "should always include required fields in canonical form" do
+# #     end
+# #
+# #     it "should order properties lexicographically per RFC 8785" do
+# #     end
+# #
+# #     it "should remove insignificant whitespace per RFC 8785" do
+# #     end
+# #
+# #     it "should exclude the signatures field from content being signed" do
+# #     end
+# #   end
+# #
+# #   # --- Signature Format ---
+# #
+# #   describe "when validating a signed Agent Card" do
+# #     it "should include alg parameter in JWS protected header" do
+# #     end
+# #
+# #     it "should include kid parameter in JWS protected header" do
+# #     end
+# #
+# #     it "should have typ set to JOSE in the protected header" do
+# #     end
+# #
+# #     it "should have a base64url-encoded JSON protected field" do
+# #     end
+# #
+# #     it "should have a base64url-encoded signature value" do
+# #     end
+# #   end
+# #
+# #   # --- Signature Verification ---
+# #
+# #   describe "when a client verifies an Agent Card signature" do
+# #     it "should follow verification steps in order" do
+# #     end
+# #
+# #     it "should verify at least one signature before trusting the Agent Card" do
+# #     end
+# #
+# #     it "should retrieve public keys over HTTPS" do
+# #     end
+# #
+# #     it "should not use expired or revoked keys for verification" do
+# #     end
+# #   end
+# #
+# #   describe "when an Agent Card has multiple signatures" do
+# #     it "should accept multiple signatures for key rotation support" do
+# #     end
+# #   end
+# # end

data/tests/rest/agent_discovery_test.rb

@@ -0,0 +1,117 @@
+require "a2a_test_framework/test_helper"
+
+# Agent discovery: well-known URI and AgentCard structure
+
+describe "Agent Discovery (REST)" do
+  # --- Purpose ---
+
+  describe "when a server is running" do
+    it "should make an Agent Card available at the well-known URI" do
+      response = http_get("/.well-known/agent-card.json")
+      response.code.to_i.should.equal 200
+    end
+
+    it "should describe identity, capabilities, skills, and interaction requirements" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      # Identity
+      data["name"].should.not.be.nil
+      data["name"].should.be.kind_of String
+      data["version"].should.not.be.nil
+
+      # Capabilities
+      data["capabilities"].should.not.be.nil
+      data["capabilities"].should.be.kind_of Hash
+
+      # Skills
+      data["skills"].should.not.be.nil
+      data["skills"].should.be.kind_of Array
+      data["skills"].length.should.be > 0
+    end
+  end
+
+  # --- Discovery Mechanisms ---
+
+  describe "when a client requests the well-known Agent Card URI" do
+    it "should return the Agent Card as JSON from /.well-known/agent-card.json" do
+      response = http_get("/.well-known/agent-card.json")
+      response.code.to_i.should.equal 200
+
+      content_type = response["Content-Type"].to_s
+      content_type.should.include "json"
+
+      data = parse_json(response)
+      data.should.be.kind_of Hash
+      data["name"].should.not.be.nil
+    end
+  end
+
+  # --- Supported Interfaces Declaration ---
+
+  describe "when the AgentCard declares supportedInterfaces" do
+    it "should declare supported protocol combinations" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      data["supportedInterfaces"].should.not.be.nil
+      data["supportedInterfaces"].should.be.kind_of Array
+      data["supportedInterfaces"].length.should.be > 0
+    end
+
+    it "should include protocolBinding and url for each interface" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      data["supportedInterfaces"].each do |iface|
+        iface["url"].should.not.be.nil
+        iface["protocolBinding"].should.not.be.nil
+      end
+    end
+  end
+
+  # --- AgentCard Structure ---
+
+  describe "when validating AgentCard structure" do
+    it "should include a name field" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+      data["name"].should.be.kind_of String
+      data["name"].length.should.be > 0
+    end
+
+    it "should include a version field" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+      data["version"].should.be.kind_of String
+      data["version"].length.should.be > 0
+    end
+
+    it "should include capabilities with boolean fields" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      caps = data["capabilities"]
+      caps.key?("streaming").should.equal true
+      caps.key?("pushNotifications").should.equal true
+    end
+
+    it "should include skills with required fields" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      skill = data["skills"].first
+      skill["id"].should.not.be.nil
+      skill["name"].should.not.be.nil
+      skill["description"].should.not.be.nil
+    end
+  end
+
+  # --- Client Protocol Selection ---
+  # NOTE: Commented out -- behavioral requirement, not testable against single server
+
+  # describe "when a client parses supportedInterfaces" do
+  #   it "should select the first supported transport from the list" do
+  #   end
+  # end
+end