artifacts_test.go

Overview

The artifacts_test.go file contains unit tests that validate the core functionality of the artifact storage and retrieval system implemented via the artifactinternal.Artifacts adapter. This adapter provides a context-aware facade over the underlying artifact service implementations, enabling versioned saving, loading, and listing of artifacts scoped by application, user, and session identifiers.

The tests focus on verifying that artifacts can be saved, retrieved (including versioned retrieval), and listed correctly using an in-memory artifact backend (artifact.InMemoryService()). Additionally, the tests cover error scenarios such as attempts to load non-existent artifacts or invalid versions to ensure robust error handling.

This file plays a critical role in ensuring the correctness of the artifact management subsystem as described in the Artifact Management topic and the Artifact Interface Adapter subtopic.

Test Functions and Their Details

TestArtifacts(t *testing.T)

Purpose:
Verifies the basic lifecycle of artifacts: saving, loading, and listing.

Process:

• Creates an Artifacts adapter instance bound to a test application, user, and session.

• Saves an artifact named "testArtifact" with text content "test data".

• Loads the saved artifact and compares its content to the original using cmp.Diff.

• Lists all artifacts and verifies the presence of "testArtifact" in the returned file names.

Parameters:

• t *testing.T: The Go testing framework's test context.

Return:

• None. Uses t.Fatalf and t.Errorf to report failures.

Usage Example:
This test simulates a typical usage scenario where an agent or tool saves an artifact, then later loads and lists it successfully.

TestArtifacts_WithLoadVersion(t *testing.T)

Purpose:
Tests the versioning support by saving multiple versions of the same artifact and loading a specific version.

Process:

• Sets up an Artifacts adapter instance similar to TestArtifacts.

• Saves "testArtifact" twice with different content ("test data" and "test data 2").

• Loads the artifact specifying version 0 (the most recent).

• Compares the loaded content to the expected second version.

Parameters:

• t *testing.T: Testing context.

Return:

• None. Failures are reported through t.Fatalf or t.Errorf.

Usage Example:
Ensures that versioned artifact retrieval works correctly, a key feature for workflows that depend on artifact history or rollback.

TestArtifacts_Errors(t *testing.T)

Purpose:
Validates error handling when loading non-existent artifacts or invalid versions.

Process:

• Attempts to load an artifact that does not exist, expecting an error.

• Attempts to load a specific version of a non-existent artifact, expecting an error.

• Saves a valid artifact "existsArtifact".

• Attempts to load a non-existent version (99) of this artifact, expecting an error.

Parameters:

• t *testing.T: Testing context.

Return:

• None. Uses t.Errorf and t.Fatalf to flag unexpected success or failure.

Usage Example:
Simulates edge cases that might occur in production to ensure that the system gracefully handles invalid requests.

Key Implementation Details

• Contextual Binding:
  Each test creates an artifactinternal.Artifacts struct with AppName, UserID, and SessionID, which scopes artifact storage and retrieval to that context. This matches the design described in Artifact Interface Adapter.

• In-Memory Service Backend:
  The tests use artifact.InMemoryService() as the backend, which provides a volatile, thread-safe artifact store suitable for testing scenarios. This aligns with the In-Memory Artifact Service described in Artifact Management.

• Version Handling:
  The Save method automatically increments artifact versions. The LoadVersion method allows fetching a specific version by number. The test verifies that the latest version is returned when loading without specifying a version.

• Use of genai.Part:
  Artifact data is wrapped in genai.Part instances (genai.NewPartFromText) for opaque handling of text or binary content, consistent with the system's artifact content model.

• Error Assertions:
  The tests check for expected errors when loading artifacts that do not exist or requesting invalid versions, ensuring that the artifact service's error semantics are correctly propagated.

Interaction with Other System Parts

• Artifact Service Layer:
  The tests interact via the Artifacts adapter, which wraps the low-level artifact service interface defined in the Artifact Management topic. The service manages storage, versioning, and retrieval.

• Agent and Session Context:
  The adapter includes contextual identifiers (AppName, UserID, SessionID), reflecting the interaction pattern described in Agent Invocation Context and Session Management, where artifacts are scoped per session and user.

• Testing Utilities:
  The test relies on github.com/google/go-cmp/cmp for structural comparison of artifact parts and the testing package for assertions and error reporting.

• Artifact Content Model:
  Uses the genai package to create and compare artifact parts, integrating with the content abstraction used across the system.

Mermaid Diagram: File Structure and Test Workflow

flowchart TD
A[Artifacts Adapter] -->|Save| B[InMemoryService Save]
A -->|Load| C[InMemoryService Load]
A -->|LoadVersion| D[InMemoryService LoadVersion]
A -->|List| E[InMemoryService List]
subgraph TestArtifacts
T1[Save artifact]
T2[Load artifact]
T3[Compare content]
T4[List artifacts]
T1 --> T2 --> T3 --> T4
end
subgraph TestArtifacts_WithLoadVersion
V1[Save version 1]
V2[Save version 2]
V3[Load specific version]
V4[Compare content]
V1 --> V2 --> V3 --> V4
end
subgraph TestArtifacts_Errors
E1[Load non-existent artifact]
E2[LoadVersion non-existent artifact]
E3[Save valid artifact]
E4[LoadVersion invalid version]
E1 --> E2 --> E3 --> E4
end
T1 --> A
T2 --> A
T4 --> A
V1 --> A
V2 --> A
V3 --> A
E1 --> A
E2 --> A
E3 --> A
E4 --> A

Summary of Key Points

• The file tests the Artifacts adapter's ability to save, load, load specific versions, and list artifacts using an in-memory backend.

• It verifies correctness of data content and error handling in edge cases.

• Tests ensure that the versioning mechanism and artifact scoping by app/user/session function as designed.

• The tests demonstrate how the artifact management functionality integrates with the context-aware adapter pattern.

• This file supports the reliability of the artifact storage system foundational to agent workflows and session-based data persistence as outlined in Artifact Management and Artifact Interface Adapter.