a2a-test-framework 0.4.0

data/tests/rest/list_tasks_test.rb

@@ -0,0 +1,162 @@
+require "a2a_test_framework/test_helper"
+
+# REST endpoint: GET /tasks
+# Request: ListTasksRequest (contextId, status, historyLength, includeArtifacts, pageSize, pageToken, statusTimestampAfter, tenant)
+# Response: ListTasksResponse (tasks[], nextPageToken, pageSize, totalSize)
+
+describe "GET /tasks" do
+  # --- Authorization Scoping ---
+  # NOTE: Commented out -- reference server does not implement authentication
+
+  # describe "when an authenticated client sends a ListTasks request" do
+  #   it "should only return tasks visible to the authenticated client" do
+  #   end
+  #
+  #   it "should not return tasks belonging to other clients" do
+  #   end
+  # end
+
+  # describe "when an unauthenticated client sends a ListTasks request" do
+  #   it "should respond with an authentication error" do
+  #   end
+  # end
+
+  # --- includeArtifacts Field Behavior ---
+
+  describe "when a client sends a ListTasks request without setting includeArtifacts" do
+    it "should omit the artifacts field from each Task object" do
+      create_task!(text: "Artifacts omit test")
+      response = http_get("/tasks")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["tasks"].should.be.kind_of Array
+      data["tasks"].length.should.be > 0
+
+      # Without includeArtifacts, artifacts should be omitted
+      task = data["tasks"].first
+      task.key?("artifacts").should.equal false
+    end
+  end
+
+  describe "when a client sends a ListTasks request with includeArtifacts set to true" do
+    it "should include the artifacts field in each Task" do
+      create_task!(text: "Artifacts include test")
+      response = http_get("/tasks?includeArtifacts=true")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      task = data["tasks"].first
+      task.key?("artifacts").should.equal true
+      task["artifacts"].should.be.kind_of Array
+    end
+  end
+
+  # --- nextPageToken Field ---
+
+  describe "when a client receives a ListTasks response" do
+    it "should contain a nextPageToken field" do
+      create_task!(text: "Page token test")
+      response = http_get("/tasks")
+      data = parse_json(response)
+
+      data.key?("nextPageToken").should.equal true
+    end
+  end
+
+  describe "when all tasks fit within a single page" do
+    it "should set nextPageToken to an empty string" do
+      # Use a large page size to fit all
+      response = http_get("/tasks?pageSize=100")
+      data = parse_json(response)
+
+      if data["tasks"].length < 100
+        data["nextPageToken"].should.equal ""
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Cursor-Based Pagination ---
+
+  describe "when using pagination" do
+    it "should respect pageSize parameter" do
+      3.times { |i| create_task!(text: "Page size test #{i}") }
+
+      response = http_get("/tasks?pageSize=2")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["tasks"].length.should.be <= 2
+    end
+
+    it "should include pageSize in the response" do
+      response = http_get("/tasks?pageSize=5")
+      data = parse_json(response)
+
+      data["pageSize"].should.not.be.nil
+      data["pageSize"].should.be > 0
+    end
+
+    it "should include totalSize in the response" do
+      create_task!(text: "Total size test")
+      response = http_get("/tasks")
+      data = parse_json(response)
+
+      data["totalSize"].should.not.be.nil
+      data["totalSize"].should.be >= 1
+    end
+
+    it "should return the first page when no pageToken is provided" do
+      response = http_get("/tasks?pageSize=2")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["tasks"].should.be.kind_of Array
+    end
+  end
+
+  # --- Filtering ---
+
+  describe "when a client filters tasks by contextId" do
+    it "should only return tasks matching that contextId" do
+      task = create_task!(text: "Context filter test")
+      context_id = task["contextId"]
+
+      response = http_get("/tasks?contextId=#{context_id}")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["tasks"].each do |t|
+        t["contextId"].should.equal context_id
+      end
+    end
+
+    it "should return empty list for non-existent contextId" do
+      response = http_get("/tasks?contextId=nonexistent-#{SecureRandom.uuid}")
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      data["tasks"].length.should.equal 0
+    end
+  end
+
+  # --- Ordering ---
+  # NOTE: Commented out -- ordering behavior depends on server implementation
+
+  # describe "when tasks are returned in the response" do
+  #   it "should sort tasks by status timestamp in descending order" do
+  #   end
+  #
+  #   it "should place the most recently updated task first" do
+  #   end
+  # end
+
+  # describe "when paginating through all results" do
+  #   it "should maintain consistent ordering across pages" do
+  #   end
+  #
+  #   it "should not have a later-page task with a more recent update than earlier-page tasks" do
+  #   end
+  # end
+end

data/tests/rest/messages_and_artifacts_test.rb

@@ -0,0 +1,101 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Messages and artifacts semantics
+
+describe "Messages and Artifacts (REST)" do
+  # --- Message/Artifact Separation ---
+
+  describe "when a task produces output results" do
+    it "should return results using Artifacts associated with the Task" do
+      task = create_task!(text: "Artifact output test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      # The echo agent produces artifacts
+      data["artifacts"].should.not.be.nil
+      data["artifacts"].should.be.kind_of Array
+      data["artifacts"].length.should.be > 0
+
+      artifact = data["artifacts"].first
+      artifact["parts"].should.be.kind_of Array
+      artifact["parts"].length.should.be > 0
+    end
+  end
+
+  describe "when examining artifact structure" do
+    it "should include artifactId for each artifact" do
+      task = create_task!(text: "ArtifactId test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      if data["artifacts"] && data["artifacts"].length > 0
+        data["artifacts"].each do |artifact|
+          artifact["artifactId"].should.not.be.nil
+          artifact["artifactId"].should.be.kind_of String
+        end
+      end
+      true.should.equal true
+    end
+
+    it "should include parts array in each artifact" do
+      task = create_task!(text: "Artifact parts test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      if data["artifacts"] && data["artifacts"].length > 0
+        data["artifacts"].each do |artifact|
+          artifact["parts"].should.be.kind_of Array
+          artifact["parts"].each do |part|
+            # Each part should have some content
+            has_content = part.key?("text") || part.key?("data") || part.key?("url") || part.key?("raw")
+            has_content.should.equal true
+          end
+        end
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Message History ---
+
+  describe "when examining task history" do
+    it "should include both user and agent messages" do
+      task = create_task!(text: "History messages test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=10")
+      data = parse_json(response)
+
+      if data["history"] && data["history"].length > 0
+        roles = data["history"].map { |m| m["role"] }
+        roles.should.include "ROLE_USER"
+        roles.should.include "ROLE_AGENT"
+      end
+      true.should.equal true
+    end
+
+    it "should include messageId in each history message" do
+      task = create_task!(text: "Message ID history test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=10")
+      data = parse_json(response)
+
+      if data["history"] && data["history"].length > 0
+        data["history"].each do |msg|
+          msg["messageId"].should.not.be.nil
+        end
+      end
+      true.should.equal true
+    end
+  end
+
+  # --- Message Reliability ---
+  # NOTE: Commented out -- cannot test delivery guarantees in conformance suite
+
+  # describe "when a client disconnects and reconnects to a stream" do
+  #   it "should not guarantee delivery of all status update messages during disconnection" do
+  #   end
+  # end
+
+  # describe "when determining message persistence" do
+  #   it "should let the agent determine which Messages are persisted in the Task History" do
+  #   end
+  # end
+end

data/tests/rest/multi_turn_conversation_test.rb

@@ -0,0 +1,94 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Multi-turn conversation patterns
+# REST: POST /message:send, POST /message:stream
+
+describe "Multi-Turn Conversation Patterns (REST)" do
+  # --- Context Continuity ---
+
+  describe "when a client sends a message with a contextId from a previous interaction" do
+    it "should create a new task within the same context" do
+      # Create first task
+      task1 = create_task!(text: "First message in context")
+      context_id = task1["contextId"]
+
+      # Send second message with same contextId
+      body = build_send_message_request(text: "Second message", context_id: context_id)
+      response = http_post("/message:send", body)
+      response.code.to_i.should.equal 200
+
+      data = parse_json(response)
+      if data["task"]
+        data["task"]["contextId"].should.equal context_id
+      end
+      true.should.equal true
+    end
+  end
+
+  describe "when a client sends a message to continue a specific task" do
+    it "should add the message to the task history" do
+      # The reference server completes tasks synchronously, so sending to
+      # a completed task will error. This tests the message is accepted
+      # or properly rejected.
+      task = create_task!(text: "Original message")
+
+      body = build_send_message_request(text: "Follow up message")
+      body["message"]["taskId"] = task["id"]
+      response = http_post("/message:send", body)
+
+      # Either accepted (200) or rejected because task is terminal (4xx)
+      (response.code.to_i == 200 || response.code.to_i >= 400).should.equal true
+    end
+  end
+
+  # --- Context Sharing ---
+
+  describe "when multiple tasks share the same contextId" do
+    it "should list all tasks when filtering by contextId" do
+      # Create two tasks, second one with explicit contextId
+      task1 = create_task!(text: "Context sharing 1")
+      context_id = task1["contextId"]
+
+      body2 = build_send_message_request(text: "Context sharing 2", context_id: context_id)
+      http_post("/message:send", body2)
+
+      # List tasks by context
+      response = http_get("/tasks?contextId=#{context_id}")
+      data = parse_json(response)
+
+      data["tasks"].length.should.be >= 2
+      data["tasks"].each { |t| t["contextId"].should.equal context_id }
+    end
+  end
+
+  # --- Input Required State ---
+  # NOTE: Commented out -- reference server does not enter INPUT_REQUIRED state
+
+  # describe "when the agent needs additional input from the client" do
+  #   it "should transition the task to input_required state" do
+  #   end
+  # end
+
+  # describe "when a client sends a message to a task in input_required state" do
+  #   it "should accept the message and continue processing the task" do
+  #   end
+  # end
+
+  # --- Follow-up Messages ---
+  # NOTE: Commented out -- reference server completes tasks immediately
+
+  # describe "when a client sends a follow-up message with taskId to refine an existing task" do
+  #   it "should accept the message as a refinement of the existing task" do
+  #   end
+  # end
+
+  # describe "when a client sends a message with referenceTaskIds" do
+  #   it "should use the referenced tasks to understand context and intent" do
+  #   end
+  # end
+
+  # describe "when a client sends a message with mismatching contextId and taskId" do
+  #   it "should reject the message with an error" do
+  #   end
+  # end
+end

data/tests/rest/protocol_data_model_test.rb

@@ -0,0 +1,99 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Protocol data model applies to all REST endpoints
+# Verifies that data structures conform to the A2A protocol specification.
+
+describe "Protocol Data Model (REST)" do
+  describe "when validating Task object structure" do
+    it "should contain required fields: id, status" do
+      task = create_task!(text: "Task model test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      data["id"].should.not.be.nil
+      data["status"].should.not.be.nil
+    end
+
+    it "should contain status with state and timestamp" do
+      task = create_task!(text: "Status model test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      data["status"]["state"].should.not.be.nil
+      data["status"]["timestamp"].should.not.be.nil
+    end
+  end
+
+  describe "when validating Message object structure" do
+    it "should contain role and parts fields" do
+      task = create_task!(text: "Message model test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=10")
+      data = parse_json(response)
+
+      if data["history"] && data["history"].length > 0
+        msg = data["history"].first
+        msg["role"].should.not.be.nil
+        msg["parts"].should.not.be.nil
+        msg["parts"].should.be.kind_of Array
+      end
+      true.should.equal true
+    end
+
+    it "should contain messageId in messages" do
+      task = create_task!(text: "MessageId test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=10")
+      data = parse_json(response)
+
+      if data["history"] && data["history"].length > 0
+        msg = data["history"].first
+        msg["messageId"].should.not.be.nil
+        msg["messageId"].should.be.kind_of String
+      end
+      true.should.equal true
+    end
+  end
+
+  describe "when validating Part object structure" do
+    it "should contain at least one content field (text, data, url, or raw)" do
+      task = create_task!(text: "Part model test")
+      response = http_get("/tasks/#{task["id"]}?historyLength=10")
+      data = parse_json(response)
+
+      if data["history"] && data["history"].length > 0
+        part = data["history"].first["parts"].first
+        has_content = part.key?("text") || part.key?("data") || part.key?("url") || part.key?("raw")
+        has_content.should.equal true
+      end
+      true.should.equal true
+    end
+  end
+
+  describe "when validating Artifact object structure" do
+    it "should contain artifactId and parts" do
+      task = create_task!(text: "Artifact model test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      if data["artifacts"] && data["artifacts"].length > 0
+        artifact = data["artifacts"].first
+        artifact["artifactId"].should.not.be.nil
+        artifact["parts"].should.not.be.nil
+        artifact["parts"].should.be.kind_of Array
+      end
+      true.should.equal true
+    end
+  end
+
+  describe "when validating SendMessageResponse structure" do
+    it "should contain exactly one of task or message at the top level" do
+      body = build_send_message_request(text: "Response model test")
+      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
+    end
+  end
+end

data/tests/rest/protocol_security_test.rb

@@ -0,0 +1,25 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement protocol security
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement protocol security
+
+# # describe "Protocol Security (REST)" do
+# #   describe "when using HTTP-based bindings in production" do
+# #     it "should use HTTPS for encrypted communication" do
+# #     end
+# #
+# #     it "should not allow plain HTTP for production deployments" do
+# #     end
+# #   end
+# #
+# #   describe "when configuring TLS" do
+# #     it "should use TLS 1.3 or higher" do
+# #     end
+# #
+# #     it "should use strong cipher suites" do
+# #     end
+# #   end
+# # end

data/tests/rest/protocol_selection_negotiation_test.rb

@@ -0,0 +1,24 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement protocol negotiation
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement protocol negotiation
+
+# # describe "Protocol Selection and Negotiation (REST)" do
+# #   describe "when the agent supports multiple protocols" do
+# #     it "should declare all supported protocols in the AgentCard" do
+# #     end
+# #   end
+# #
+# #   describe "when a client chooses a protocol declared in the AgentCard" do
+# #     it "should accept requests via that protocol" do
+# #     end
+# #   end
+# #
+# #   describe "when the client's preferred protocol is unavailable" do
+# #     it "should implement fallback logic to try alternative declared protocols" do
+# #     end
+# #   end
+# # end

data/tests/rest/push_notification_delivery_test.rb

@@ -0,0 +1,115 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Push notification delivery requires external webhook receiver
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Push notification delivery requires external webhook receiver
+
+# # describe "Push Notification Delivery Protocol (REST)" do
+# #   # --- Delivery Protocol ---
+# #
+# #   describe "when a push notification is triggered regardless of agent binding" do
+# #     it "should use plain HTTP for webhook calls" do
+# #     end
+# #
+# #     it "should use JSON format as defined in the HTTP protocol binding" do
+# #     end
+# #   end
+# #
+# #   describe "when checking capability requirements" do
+# #     it "should only allow streaming operations if capabilities.streaming is true" do
+# #     end
+# #
+# #     it "should only allow push notification operations if capabilities.pushNotifications is true" do
+# #     end
+# #   end
+# #
+# #   # --- Push Notification Payload ---
+# #
+# #   describe "when the agent sends a push notification" do
+# #     it "should use HTTP POST method" do
+# #     end
+# #
+# #     it "should include Content-Type header set to application/a2a+json" do
+# #     end
+# #   end
+# #
+# #   describe "when a push notification payload is delivered" do
+# #     it "should contain exactly one of task, message, statusUpdate, or artifactUpdate" do
+# #     end
+# #   end
+# #
+# #   describe "when the payload contains a task field" do
+# #     it "should contain a valid Task object with current state" do
+# #     end
+# #   end
+# #
+# #   describe "when the payload contains a statusUpdate field" do
+# #     it "should contain a valid TaskStatusUpdateEvent object" do
+# #     end
+# #   end
+# #
+# #   describe "when the payload contains an artifactUpdate field" do
+# #     it "should contain a valid TaskArtifactUpdateEvent object" do
+# #     end
+# #   end
+# #
+# #   # --- Authentication ---
+# #
+# #   describe "when push notification config includes authentication info" do
+# #     it "should include authentication credentials in webhook request headers" do
+# #     end
+# #
+# #     it "should match the format specified in PushNotificationConfig.authentication" do
+# #     end
+# #   end
+# #
+# #   describe "when push notification config uses Bearer token authentication" do
+# #     it "should include an Authorization header with Bearer token" do
+# #     end
+# #   end
+# #
+# #   # --- Client Responsibilities ---
+# #
+# #   describe "when a client receives a valid push notification" do
+# #     it "should respond with an HTTP 2xx status code to acknowledge receipt" do
+# #     end
+# #   end
+# #
+# #   describe "when a client receives the same notification twice" do
+# #     it "should process notifications idempotently" do
+# #     end
+# #
+# #     it "should not cause unintended side effects from duplicates" do
+# #     end
+# #   end
+# #
+# #   describe "when a client receives a push notification" do
+# #     it "should validate the task ID matches an expected task" do
+# #     end
+# #
+# #     it "should verify the notification source" do
+# #     end
+# #   end
+# #
+# #   # --- Server Delivery Guarantees ---
+# #
+# #   describe "when a task status changes and a webhook is configured" do
+# #     it "should attempt delivery at least once" do
+# #     end
+# #   end
+# #
+# #   describe "when a webhook delivery fails" do
+# #     it "should MAY implement retry logic with exponential backoff" do
+# #     end
+# #
+# #     it "should include a reasonable timeout for the request" do
+# #     end
+# #   end
+# #
+# #   describe "when a webhook endpoint consistently fails" do
+# #     it "should MAY stop attempting delivery after consecutive failures" do
+# #     end
+# #   end
+# # end