processor_test.go

Overview

The processor_test.go file contains unit tests for validating the functionality of the event processing logic within the ADK-to-A2A event conversion system. Specifically, it tests the behavior of the eventProcessor type (defined elsewhere in the module) which converts internal ADK session.Event streams into A2A a2a.Event sequences, including incremental artifact updates and terminal task status updates.

This file ensures that the event processing correctly handles various event scenarios such as:

• Events with no response or empty content.

• Multi-part LLM output streamed as artifact updates.

• Handling of errors and failures in LLM responses.

• Long-running function calls triggering input-required task states.

• Proper metadata propagation for escalation and agent transfer actions.

• Correct management of artifact chunking flags (append, last chunk).

• Ordering and terminal event generation for a sequence of session events.

The tests simulate realistic event streams and verify that the eventProcessor emits the expected A2A events, ensuring semantic correctness and robustness of the event translation layer.

Functions and Methods

modelResponseFromParts(parts ...*genai.Part) model.LLMResponse

• Purpose: Helper function to create a model.LLMResponse containing given parts as content from the model role.

• Parameters: Variadic list of pointers to genai.Part objects representing segments of the LLM response.

• Returns: A model.LLMResponse with a genai.Content object wrapping the provided parts.

• Usage: Used in tests to construct mock LLM responses containing text, code, function calls, or other content parts.

newArtifactLastChunkEvent(task *a2a.Task) *a2a.TaskArtifactUpdateEvent

• Purpose: Creates an A2A artifact update event marked as the last chunk for a given task.

• Parameters:

  • task - Pointer to an a2a.Task object representing the current task.

• Returns: A pointer to a2a.TaskArtifactUpdateEvent with LastChunk flag set to true.

• Usage: Used in tests to verify that artifact update streams are correctly finalized.

newFinalStatusUpdate(task *a2a.Task, state a2a.TaskState, msg *a2a.Message) *a2a.TaskStatusUpdateEvent

• Purpose: Constructs a final task status update event for a specified task state.

• Parameters:

  • task - Pointer to a2a.Task.

  • state - A2A task state (a2a.TaskStateCompleted, a2a.TaskStateFailed, etc.).

  • msg - Optional pointer to an a2a.Message for additional status context.

• Returns: A pointer to a finalized a2a.TaskStatusUpdateEvent with Final flag set.

• Usage: Used to assert correct terminal events are generated after processing sequences of session events.

TestEventProcessor_Process(t *testing.T)

• Purpose: Comprehensive table-driven test covering a wide range of event processing scenarios by the eventProcessor.

• Test Cases: Each entry includes:

  • name: Descriptive string of the test scenario.

  • events: Slice of pointers to session.Event objects simulating input event streams.

  • processed: Expected slice of pointers to a2a.TaskArtifactUpdateEvent that should be produced during processing.

  • terminal: Expected slice of a2a.Event representing terminal events generated after processing all inputs.

• Behavior:

  • Instantiates an eventProcessor with a mock request context.

  • Iterates over input events, calling process() and accumulating produced artifact updates.

  • Compares produced artifact updates against expected results using cmp.Diff, ignoring non-essential fields.

  • Calls makeTerminalEvents() to obtain terminal events and compares against expected terminal events.

• Key Scenarios Tested:

  • Handling empty or non-contentful events.

  • Multi-part text and code artifact updates.

  • Failure scenarios with and without partial artifacts.

  • Long-running function calls triggering input-required states.

  • Action metadata propagation for escalation and agent transfer.

  • Ensuring that only the first failure is reported.

• Usage: Validates correctness of event-to-A2A event translation under diverse and edge case conditions.

TestEventProcessor_ArtifactUpdates(t *testing.T)

• Purpose: Tests artifact update event generation consistency across multiple session events containing executable code, code execution results, function calls, and text.

• Behavior:

  • Creates a sequence of session.Event objects simulating a realistic LLM response flow with code execution and function call parts.

  • Processes each event with the eventProcessor and collects resulting artifact update events.

  • Asserts that:

    • The number of processed events matches the input event count.

    • The first artifact update event is neither appended nor marked as last chunk.

    • Subsequent artifact update events share the same artifact ID.

    • No intermediate event is marked with LastChunk = true.

  • Confirms that terminal events include a final artifact chunk event marked as appended and last chunk, followed by a final status update.

• Usage: Ensures artifact chunking and artifact ID continuity are handled correctly by the processor.

Implementation Details

• The tests rely heavily on mock event construction, using utility functions (modelResponseFromParts, newArtifactLastChunkEvent, newFinalStatusUpdate) to simplify setup.

• The eventProcessor processes each session.Event (defined in Session Management) that may contain LLM responses or actions.

• The processor emits a2a.TaskArtifactUpdateEvent for content parts and manages terminal events like status updates (a2a.TaskStatusUpdateEvent).

• Metadata flags such as escalation (escalate) and agent transfer (transfer_to_agent) are tracked and embedded in final events.

• The tests cover edge cases where errors occur before or after some content parts have been processed, verifying that partial outputs are emitted before failure finalization.

• Long-running function calls are detected based on LongRunningToolIDs and generate input_required terminal state events accordingly.

• The tests use the cmp package with options to ignore fields like generated IDs and timestamps to focus on semantic correctness.

• The file uses Go's testing package for execution and test lifecycle management.

Interaction with Other Parts of the System

• eventProcessor: The primary component under test is implemented in the same package and is part of the event conversion and processing subtopic (Event Conversion and Processing). This processor translates ADK session.Event objects into A2A events.

• ADK Session Events: The input events simulate the session event stream produced by the ADK agent framework (Session Management, Agent Execution Runner).

• A2A Events: The processed output events (a2a.TaskArtifactUpdateEvent, a2a.TaskStatusUpdateEvent) are part of the A2A protocol event model (Remote Agent Communication (A2A)).

• Task and Artifact IDs: The test code manages synthetic task and artifact IDs generated via a2a.NewTaskID() and a2a.NewArtifactID(), consistent with the artifact management subtopic (Artifact Management).

• Long-running Tool Support: The detection of long-running tools and input-required states aligns with the logic for handling asynchronous workflows in the A2A protocol.

• Action Metadata: The handling of escalation and transfer actions ties into agent lifecycle and callback logic (Agent Lifecycle and Callbacks) and the remote agent communication metadata conventions.

Visual Diagram: EventProcessor Test Structure and Workflow

flowchart TD
A[Start Test Case] --> B[Create Task & Context]
B --> C[Initialize eventProcessor]
C --> D[Iterate Over Input session.Events]
D --> E{Call processor.process()}
E -->|Produces ArtifactUpdateEvent| F[Append to processed list]
E -->|No output| G[Continue]
F --> G
G --> H{All events processed?}
H -->|No| D
H -->|Yes| I["Call processor.makeTerminalEvents()"]
I --> J[Compare processed events to expected]
I --> K[Compare terminal events to expected]
J --> L{Mismatch?}
K --> L
L -->|Yes| M[Test fails]
L -->|No| N[Test passes]

This flowchart illustrates the test execution flow within TestEventProcessor_Process and TestEventProcessor_ArtifactUpdates:

• Setup of task and request context.

• Creation of eventProcessor.

• Processing each session event through the processor.

• Collecting artifact update events.

• Generating terminal events after all inputs.

• Comparing actual outputs to expected results.

• Passing or failing the test based on comparison.

Usage Examples (from tests)

Example snippet to create a test case for multi-part artifact update:

events := []*session.Event{{
    LLMResponse: modelResponseFromParts(genai.NewPartFromText("Hello"), genai.NewPartFromText(", world!")),
}}

expectedProcessed := []*a2a.TaskArtifactUpdateEvent{
    a2a.NewArtifactEvent(task, a2a.TextPart{Text: "Hello"}, a2a.TextPart{Text: ", world!"}),
}

expectedTerminal := []a2a.Event{
    newArtifactLastChunkEvent(task),
    newFinalStatusUpdate(task, a2a.TaskStateCompleted, nil),
}

// Inside test:
// - process each event
// - assert processed matches expectedProcessed
// - assert terminal events match expectedTerminal

Summary

The processor_test.go file is crucial for verifying the correctness of the event processing pipeline that converts ADK session events into A2A protocol events, ensuring reliable streaming of partial outputs, correct handling of errors and terminal states, and proper metadata propagation for agent orchestration. It provides comprehensive coverage for typical and edge case scenarios encountered during remote agent communication workflows.

For detailed understanding of the event processor implementation and event translation logic, see the [Event Conversion and Processing](80591) subtopic and the related files within the [Remote Agent Communication (A2A)](80565) domain.