a2a-test-framework 0.4.0

data/tests/rest/task_identifier_semantics_test.rb

@@ -0,0 +1,67 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Task identifier semantics
+
+describe "Task Identifier Semantics (REST)" do
+  # --- Server Generation ---
+
+  describe "when a client sends a message that triggers task creation" do
+    it "should generate the taskId on the server" do
+      body = build_send_message_request(text: "Task ID generation")
+      response = http_post("/message:send", body)
+      data = parse_json(response)
+
+      if data["task"]
+        data["task"]["id"].should.not.be.nil
+        data["task"]["id"].should.be.kind_of String
+        data["task"]["id"].length.should.be > 0
+      end
+      true.should.equal true
+    end
+  end
+
+  describe "when multiple tasks are created" do
+    it "should generate a unique taskId for each new task" do
+      task1 = create_task!(text: "Unique ID test 1")
+      task2 = create_task!(text: "Unique ID test 2")
+
+      task1["id"].should.not.equal task2["id"]
+    end
+  end
+
+  describe "when the response is a Task object" do
+    it "should include the generated taskId in the Task object" do
+      task = create_task!(text: "ID in response test")
+      task["id"].should.not.be.nil
+      task["id"].length.should.be > 0
+    end
+  end
+
+  # --- Client-Provided taskId References ---
+
+  describe "when a client provides a taskId that does not correspond to an existing task" do
+    it "should return a TaskNotFoundError" do
+      body = build_send_message_request(text: "Bad task ref")
+      body["message"]["taskId"] = "nonexistent-#{SecureRandom.uuid}"
+      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
+    end
+  end
+
+  # --- TaskId as opaque string ---
+
+  describe "when examining taskId format" do
+    it "should treat taskId as an opaque string (no client assumptions about format)" do
+      task = create_task!(text: "Opaque ID test")
+      # The ID exists and is a non-empty string -- that's all clients should assume
+      task["id"].should.be.kind_of String
+      task["id"].length.should.be > 0
+    end
+  end
+end

data/tests/rest/timestamps_test.rb

@@ -0,0 +1,70 @@
+require "a2a_test_framework/test_helper"
+require "time"
+
+# Cross-cutting: Timestamp conventions apply to all REST endpoints returning timestamps
+
+describe "Timestamp Conventions (REST)" do
+  # --- Format Requirements ---
+
+  describe "when the server returns a response containing timestamp fields" do
+    it "should represent timestamps as ISO 8601 formatted strings" do
+      task = create_task!(text: "Timestamp format test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      timestamp = data["status"]["timestamp"]
+      timestamp.should.not.be.nil
+      # ISO 8601 basic pattern: YYYY-MM-DD followed by T
+      timestamp.should.match(/\d{4}-\d{2}-\d{2}T/)
+    end
+
+    it "should use UTC timezone denoted by Z suffix" do
+      task = create_task!(text: "UTC test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      timestamp = data["status"]["timestamp"]
+      timestamp.should.match(/Z\z/)
+    end
+
+    it "should be parseable as a valid datetime" do
+      task = create_task!(text: "Parseable test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      timestamp = data["status"]["timestamp"]
+      # Should not raise
+      parsed = Time.parse(timestamp)
+      parsed.should.be.kind_of Time
+    end
+  end
+
+  # --- Full pattern validation ---
+
+  describe "when validating timestamp format" do
+    it "should match ISO 8601 pattern with milliseconds" do
+      task = create_task!(text: "Pattern test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      timestamp = data["status"]["timestamp"]
+      # Allow both with and without milliseconds
+      valid_pattern = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z\z/
+      timestamp.should.match(valid_pattern)
+    end
+  end
+
+  # --- Timezone Restrictions ---
+
+  describe "when validating timezone in timestamps" do
+    it "should not include timezone offsets other than Z" do
+      task = create_task!(text: "No offset test")
+      response = http_get("/tasks/#{task["id"]}")
+      data = parse_json(response)
+
+      timestamp = data["status"]["timestamp"]
+      # Should not have +HH:MM or -HH:MM offsets
+      timestamp.should.not.match(/[+-]\d{2}:\d{2}\z/)
+    end
+  end
+end

data/tests/rest/versioning_responsibilities_test.rb

@@ -0,0 +1,46 @@
+require "a2a_test_framework/test_helper"
+
+# NOTE: All tests commented out -- Reference server does not implement version negotiation
+
+# require "a2a_test_framework/test_helper"
+
+# # NOTE: All tests commented out -- Reference server does not implement version negotiation
+
+# # describe "Versioning - Server Responsibilities (REST)" do
+# #   describe "when a client sends a request with A2A-Version for a supported version" do
+# #     it "should process the request using the semantics of the requested version" do
+# #     end
+# #   end
+# #
+# #   describe "when a client requests an older supported version" do
+# #     it "should process the request using the older version semantics" do
+# #     end
+# #   end
+# #
+# #   describe "when a client requests an unsupported version" do
+# #     it "should return a VersionNotSupportedError" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends an empty A2A-Version value" do
+# #     it "should interpret the empty value as version 0.3" do
+# #     end
+# #   end
+# #
+# #   describe "when a client sends a request without an A2A-Version header" do
+# #     it "should interpret the missing header as version 0.3" do
+# #     end
+# #   end
+# # end
+# #
+# # describe "Versioning - Client Responsibilities (REST)" do
+# #   describe "when a client sends any request to an A2A server" do
+# #     it "should include the A2A-Version header" do
+# #     end
+# #   end
+# #
+# #   describe "when A2A-Version is provided as a query parameter" do
+# #     it "should accept it as equivalent to the A2A-Version header" do
+# #     end
+# #   end
+# # end

data/tests/rest/versioning_test.rb

@@ -0,0 +1,44 @@
+require "a2a_test_framework/test_helper"
+
+# Cross-cutting: Protocol versioning applies to all REST endpoints
+# Version is communicated via A2A-Version header.
+
+describe "Protocol Versioning (REST)" do
+  # NOTE: Version negotiation is not fully implemented in the reference server.
+  # These tests verify basic version-related behavior.
+
+  # --- Version Format ---
+  # NOTE: Commented out -- reference server may not validate version header
+
+  # describe "when a client sends a request with A2A-Version header" do
+  #   it "should recognize Major.Minor format as valid" 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
+  # end
+
+  # --- Basic Version Behavior ---
+
+  describe "when the AgentCard declares protocol version" do
+    it "should include protocolVersion in supportedInterfaces" do
+      response = http_get("/.well-known/agent-card.json")
+      data = parse_json(response)
+
+      data["supportedInterfaces"].each do |iface|
+        if iface.key?("protocolVersion")
+          iface["protocolVersion"].should.be.kind_of String
+          iface["protocolVersion"].should.match(/\d+\.\d+/)
+        end
+      end
+      true.should.equal true
+    end
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: a2a-test-framework
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Nathan
+bindir: exe
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: scampi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: agent2agent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A comprehensive test framework for validating A2A protocol server implementations.
+  Includes tests for REST and gRPC bindings covering agent discovery, messaging, streaming,
+  task management, push notifications, error handling, and more.
+executables:
+- a2a-test
+extensions: []
+extra_rdoc_files: []
+files:
+- a2a.json
+- a2a.proto
+- endpoints/grpc/cancel_task.json
+- endpoints/grpc/create_task_push_notification_config.json
+- endpoints/grpc/delete_task_push_notification_config.json
+- endpoints/grpc/get_extended_agent_card.json
+- endpoints/grpc/get_task.json
+- endpoints/grpc/get_task_push_notification_config.json
+- endpoints/grpc/list_task_push_notification_configs.json
+- endpoints/grpc/list_tasks.json
+- endpoints/grpc/send_message.json
+- endpoints/grpc/send_streaming_message.json
+- endpoints/grpc/subscribe_to_task.json
+- endpoints/rest/cancel_task.json
+- endpoints/rest/create_task_push_notification_config.json
+- endpoints/rest/delete_task_push_notification_config.json
+- endpoints/rest/get_extended_agent_card.json
+- endpoints/rest/get_task.json
+- endpoints/rest/get_task_push_notification_config.json
+- endpoints/rest/list_task_push_notification_configs.json
+- endpoints/rest/list_tasks.json
+- endpoints/rest/send_message.json
+- endpoints/rest/send_streaming_message.json
+- endpoints/rest/subscribe_to_task.json
+- exe/a2a-test
+- lib/a2a_test_framework.rb
+- lib/a2a_test_framework/cli.rb
+- lib/a2a_test_framework/sse_client.rb
+- lib/a2a_test_framework/test_helper.rb
+- lib/a2a_test_framework/version.rb
+- tests/grpc/cancel_task_test.rb
+- tests/grpc/create_task_push_notification_config_test.rb
+- tests/grpc/delete_task_push_notification_config_test.rb
+- tests/grpc/error_code_mappings_test.rb
+- tests/grpc/error_handling_test.rb
+- tests/grpc/get_extended_agent_card_test.rb
+- tests/grpc/get_task_push_notification_config_test.rb
+- tests/grpc/get_task_test.rb
+- tests/grpc/grpc_binding_test.rb
+- tests/grpc/list_task_push_notification_configs_test.rb
+- tests/grpc/list_tasks_test.rb
+- tests/grpc/protocol_data_model_test.rb
+- tests/grpc/send_message_test.rb
+- tests/grpc/send_streaming_message_test.rb
+- tests/grpc/streaming_event_delivery_test.rb
+- tests/grpc/subscribe_to_task_test.rb
+- tests/grpc/versioning_test.rb
+- tests/rest/agent_card_caching_test.rb
+- tests/rest/agent_card_signing_test.rb
+- tests/rest/agent_discovery_test.rb
+- tests/rest/authentication_authorization_test.rb
+- tests/rest/cancel_task_test.rb
+- tests/rest/capability_validation_test.rb
+- tests/rest/context_identifier_semantics_test.rb
+- tests/rest/create_task_push_notification_config_test.rb
+- tests/rest/custom_binding_test.rb
+- tests/rest/delete_task_push_notification_config_test.rb
+- tests/rest/error_code_mappings_test.rb
+- tests/rest/error_handling_test.rb
+- tests/rest/extension_versioning_test.rb
+- tests/rest/field_presence_optionality_test.rb
+- tests/rest/functional_equivalence_test.rb
+- tests/rest/get_extended_agent_card_test.rb
+- tests/rest/get_task_push_notification_config_test.rb
+- tests/rest/get_task_test.rb
+- tests/rest/history_length_semantics_test.rb
+- tests/rest/http_rest_binding_test.rb
+- tests/rest/iana_registrations_test.rb
+- tests/rest/idempotency_test.rb
+- tests/rest/in_task_authorization_test.rb
+- tests/rest/json_field_naming_test.rb
+- tests/rest/json_rpc_binding_test.rb
+- tests/rest/list_task_push_notification_configs_test.rb
+- tests/rest/list_tasks_test.rb
+- tests/rest/messages_and_artifacts_test.rb
+- tests/rest/multi_turn_conversation_test.rb
+- tests/rest/protocol_data_model_test.rb
+- tests/rest/protocol_security_test.rb
+- tests/rest/protocol_selection_negotiation_test.rb
+- tests/rest/push_notification_delivery_test.rb
+- tests/rest/security_considerations_test.rb
+- tests/rest/send_message_test.rb
+- tests/rest/send_streaming_message_test.rb
+- tests/rest/service_parameters_test.rb
+- tests/rest/streaming_event_delivery_test.rb
+- tests/rest/subscribe_to_task_test.rb
+- tests/rest/task_identifier_semantics_test.rb
+- tests/rest/timestamps_test.rb
+- tests/rest/versioning_responsibilities_test.rb
+- tests/rest/versioning_test.rb
+homepage: https://github.com/a2aproject/a2a-test-framework
+licenses:
+- Apache-2.0
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Conformance test suite for A2A (Agent-to-Agent) protocol implementations
+test_files: []