service_suite.go

Overview

The service_suite.go file provides a comprehensive suite of automated tests for any implementation of the artifact.Service interface defined in the Artifact Management module. Its main purpose is to validate the correctness, consistency, and expected behavior of artifact service implementations, including saving, loading, listing, versioning, and deleting artifacts. The tests cover scenarios with normal artifact usage, empty states, and user-scoped artifacts to ensure full compliance with the artifact service contract.

This file is a utility test suite designed to be reusable for multiple artifact service implementations by accepting a factory function that constructs the service under test. It exercises the full lifecycle of artifacts, verifying version increments, retrieval of specific versions, deletion of specific versions or entire artifacts, and proper error handling for non-existent artifacts.

Functions and Methods

TestArtifactService

func TestArtifactService(t *testing.T, name string, factory func(t *testing.T) (artifact.Service, error))

• Purpose: Entry point to run all artifact service tests for a given implementation.

• Parameters:

  • t *testing.T: The Go testing object for controlling test execution and reporting.

  • name string: A unique name identifying the artifact service implementation being tested.

  • factory func(t *testing.T) (artifact.Service, error): A factory callback that returns a new instance of the artifact.Service implementation to test.

• Behavior: Runs three main sub-tests:

  • Test<name>ArtifactService: Tests typical artifact operations.

  • Test<name>ArtifactService_Empty: Tests behavior on empty artifact state.

  • Test<name>ArtifactService_UserScoped: Tests artifact operations for user-scoped filenames.

• Usage Example:

TestArtifactService(t, "InMemory", func(t *testing.T) (artifact.Service, error) {
    return NewInMemoryArtifactService(), nil
})

testArtifactService

func testArtifactService(ctx context.Context, t *testing.T, srv artifact.Service, testSuffix string)

• Purpose: Implements tests for standard artifact operations on the provided service:

  • Saving multiple versions of artifacts.

  • Loading latest and specific versions.

  • Listing all artifact filenames.

  • Retrieving all versions of an artifact.

  • Deleting specific versions and verifying effects.

  • Full deletion and confirming non-existence.

• Parameters:

  • ctx context.Context: Context for cancellation and deadlines.

  • t *testing.T: Test harness.

  • srv artifact.Service: The artifact service under test.

  • testSuffix string: A suffix string to append to sub-test names for uniqueness.

• Details:

  • Uses fixed AppName, UserID, and SessionID to isolate test artifacts.

  • Saves artifacts with multiple versions for "file1", "file2", and "file3".

  • Verifies the versioned save response matches expectations.

  • Runs sub-tests for loading, listing, version retrieval, and deletion.

  • Validates error handling when loading or listing deleted artifacts.

• Implementation Notes:

  • Uses cmp.Equal from github.com/google/go-cmp/cmp for deep equality checks of artifact parts.

  • Uses Go 1.21+ slices.Sort for deterministic ordering in comparisons.

testArtifactService_UserScoped

func testArtifactService_UserScoped(ctx context.Context, t *testing.T, srv artifact.Service, testSuffix string)

• Purpose: Tests artifact service behavior when file names are prefixed with "user:", indicating user-scoped artifacts.

• Parameters: Same as testArtifactService.

• Differences from testArtifactService:

  • Artifacts saved under filenames like "user:file1" and "user:file3" to test user-level namespace handling.

  • Validates that the service correctly treats user-scoped filenames by adjusting session scoping internally.

  • Other operations (load, list, versions, delete) ensure correct behavior for user-scoped artifacts.

• Important Detail:

  • The SessionID parameter passed during loading is a placeholder string indicating the user-scoped nature rather than the original session ID, implying internal session ID substitution logic.

• Usage:

  • Ensures implementations support the user-scoped artifact feature described in Artifact Management.

testArtifactService_Empty

func testArtifactService_Empty(ctx context.Context, t *testing.T, srv artifact.Service, testSuffix string)

• Purpose: Verifies the artifact service's behavior when no artifacts exist.

• Parameters: Same as above.

• Tests:

  • Loading a non-existent artifact returns fs.ErrNotExist error.

  • Listing artifacts does not error (should return empty or valid empty list).

  • Deleting an artifact when none exist should not error.

  • Versions request for a non-existent artifact returns fs.ErrNotExist.

• Goal: Ensure graceful handling of empty data sets.

Important Implementation Details and Algorithms

• Versioning Logic:
  Tests verify that saving an artifact increments the version number automatically, starting from 1. Deleting specific versions and entire artifacts affects the listing and loading behavior accordingly.

• User-Scoped Artifacts:
  User-scoped artifacts (filenames prefixed with "user:") are tested to verify that the service isolates them from session-scoped artifacts, aligned with the semantics described in the Artifact Management documentation.

• Error Handling:
  Tests assert that attempts to load or list deleted or non-existent artifacts produce the expected fs.ErrNotExist error, ensuring that the service correctly signals missing data.

• Test Isolation:
  Each test run uses a fresh service instance via the provided factory, isolating state between tests. The tests clean up artifacts by deleting them after verification to prevent leakage.

• Use of context.Context:
  All service calls are made with the Go standard context.Context to support cancellation and timeouts.

• Comparison of Artifacts:
  Uses cmp.Equal for comparing genai.Part instances, which represent artifact content and metadata, ensuring deep content validation.

Interaction With Other Parts of the System

• Artifact Service Implementations:
  This test suite is designed to validate any implementation of the artifact.Service interface from the Artifact Management module, including but not limited to the in-memory service (InMemoryService) or Google Cloud Storage service (GCSService).

• Agent and Session Contexts:
  The tests simulate typical AppName, UserID, and SessionID identifiers that would be provided by session management components as described in Session Management.

• GenAI Artifact Representation:
  Artifacts are represented as genai.Part objects from the genai package, consistent with artifact content handling in the system.

• Testing Framework:
  Uses Go's testing package for unit test orchestration and reporting.

• Dependency on Artifact Request/Response Types:
  The tests use request and response types such as artifact.SaveRequest, artifact.LoadRequest, etc., defined in the artifact module interface.

Visual Diagram: Function Flow and Test Structure

flowchart TD
A[TestArtifactService] --> B[Test<name>ArtifactService]
A --> C[Test<name>ArtifactService_Empty]
A --> D[Test<name>ArtifactService_UserScoped]
B --> E[testArtifactService]
C --> F[testArtifactService_Empty]
D --> G[testArtifactService_UserScoped]
E --> H[Save artifacts]
E --> I["Load artifacts (latest and by version)"]
E --> J[List artifacts]
E --> K[List versions]
E --> L[Delete specific version]
E --> M[Load after deletion]
E --> N[Delete all versions]
E --> O[Load after full deletion]
E --> P[List and Versions after deletion]
E --> Q[Clean up all]
G --> R[Save user-scoped artifacts]
G --> S[Load user-scoped artifacts]
G --> T[List user-scoped artifacts]
G --> U[List versions user-scoped]
G --> V[Delete user-scoped version]
G --> W[Load after user-scoped deletion]
G --> X[Delete all user-scoped]
G --> Y[Load after full user-scoped deletion]
G --> Z[List and Versions user-scoped after deletion]
G --> AA[Clean up user-scoped]
F --> AB[Load empty]
F --> AC[List empty]
F --> AD[Delete empty]
F --> AE[Versions empty]

Summary

The service_suite.go file is a critical testing utility that ensures any artifact service implementation adheres strictly to the expected behavior and interface contract described in the Artifact Management topic. By covering normal, empty, and user-scoped artifact scenarios, it provides robust automated validation of artifact lifecycle operations, versioning, and error handling. This contributes to the reliability and interoperability of artifact services across the system.