gcs_test.go

Overview

The gcs_test.go file provides unit testing infrastructure and mock implementations for the Google Cloud Storage (GCS) backend artifact service within the Artifact Management topic. It defines an in-memory fake client that simulates GCS operations such as storing, retrieving, listing, and deleting objects (artifacts) entirely in memory. This allows testing the artifact service logic without requiring actual access to Google Cloud infrastructure.

The primary goal of this file is to support reliable and isolated testing of the GCS artifact service implementation by mocking GCS client interfaces (gcsClient, gcsBucket, gcsObject, etc.) using thread-safe, in-memory data structures. It also includes a test function that integrates with the broader artifact service test suite to validate conformance.

Classes, Functions, and Methods

newGCSArtifactServiceForTesting(bucketName string) (artifact.Service, error)

• Purpose:
  Creates a new instance of the GCS artifact service (gcsService) configured with a fake in-memory GCS client and bucket for testing.

• Parameters:

  • bucketName string: Name of the bucket to simulate.

• Returns:

  • artifact.Service: The artifact service interface implemented by the gcsService backed by the fake client.

  • error: Always nil in this implementation.

• Usage:
  Used in test factories to instantiate the service under test with a mock backend.

TestGCSArtifactService(t *testing.T)

• Purpose:
  Test entry point to execute the standard artifact service tests against the GCS implementation using the fake in-memory client.

• Parameters:

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

• Behavior:
  Defines a factory function that returns the test service instance and passes it to the generic tests.TestArtifactService function for running a battery of artifact service compliance tests.

• Usage:
  This function is automatically run by go test to verify the GCS artifact service behavior.

Mock Implementations

The following types implement mock versions of GCS client interfaces. They simulate GCS behavior using in-memory data structures and provide thread-safe access to enable parallel test execution.

fakeClient

• Implements:
  gcsClient interface.

• Fields:

  • inMemoryBucket gcsBucket: A singleton in-memory bucket instance.

• Key Methods:

  • bucket(name string) gcsBucket: Returns the in-memory bucket regardless of name.

• Usage:
  Acts as the root GCS client for tests, providing access to the fake bucket.

fakeBucket

• Implements:
  gcsBucket interface.

• Fields:

  • mu sync.Mutex: Mutex to synchronize access to internal map.

  • objectsMap map[string]*fakeObject: Map storing fake objects keyed by object name.

• Key Methods:

  • object(name string) gcsObject: Returns the fake object for the given name, creating one if it does not exist.

  • objects(ctx context.Context, q *storage.Query) gcsObjectIterator: Returns an iterator over objects filtered by prefix.

• Concurrency:
  All methods lock the mutex to ensure thread-safe access.

• Behavior:
  Supports listing and retrieving objects similar to real GCS buckets.

fakeObject

• Implements:
  gcsObject interface.

• Fields:

  • mu sync.Mutex: Mutex for concurrency control.

  • name string: Object name.

  • data []byte: Stored object content.

  • deleted bool: Flag indicating deletion status.

  • contentType string: MIME content type of the object.

• Key Methods:

  • newWriter(ctx context.Context) gcsWriter: Returns a writer to write data to the object. Writing "undeletes" the object and clears previous data.

  • attrs(ctx context.Context) (*storage.ObjectAttrs, error): Returns object metadata if it exists and is not deleted.

  • delete(ctx context.Context) error: Marks the object as deleted in memory.

  • newReader(ctx context.Context) (io.ReadCloser, error): Returns a reader for the object's data if present and not deleted.

• Concurrency:
  All methods lock the mutex to provide safe concurrent access.

fakeWriter

• Implements:
  gcsWriter interface.

• Fields:

  • obj *fakeObject: The target fake object to write into.

  • buffer *bytes.Buffer: Internal buffer collecting data written.

  • contentType string: Content type to set on the object.

• Key Methods:

  • Write(p []byte) (int, error): Writes bytes into the internal buffer.

  • Close() error: On close, locks the object, sets its data from the buffer, and updates the content type.

  • SetContentType(cType string): Sets the content type to be saved.

• Behavior:
  Simulates the streaming write behavior of GCS object writers.

fakeObjectIterator

• Implements:
  gcsObjectIterator interface.

• Fields:

  • objects []*fakeObject: Slice of objects to iterate over.

  • index int: Current iteration index.

• Key Methods:

  • next() (*storage.ObjectAttrs, error): Returns the attributes of the next object or iterator.Done when exhausted.

• Behavior:
  Implements the iterator pattern for listing matching objects with prefix filtering.

Important Implementation Details

• Thread Safety:
  All mutable structures (fakeBucket, fakeObject) use mutexes to protect access and state mutations, enabling concurrent test execution without race conditions.

• Object Lifecycle:
  Writing to an object clears previous data and "undeletes" it. Deletion marks objects as deleted without removing them from the map to preserve iterator stability.

• Prefix Filtering:
  The fakeBucket.objects method applies prefix filtering to simulate GCS query behavior, returning only objects whose names start with the specified prefix.

• Iterator Pattern:
  The fakeObjectIterator maintains internal state and returns one object at a time, mirroring GCS's iterator semantics.

• Interface Compliance:
  The file asserts interface implementations with blank identifier assignments to ensure types conform to their respective interfaces at compile time.

Interaction with System Components

• The fake client and bucket implementations satisfy the gcsClient and gcsBucket interfaces expected by the production gcsService implementation in the Google Cloud Storage Service topic.

• The newGCSArtifactServiceForTesting function creates a gcsService backed by this fake client, allowing the same artifact service logic to be tested end-to-end without external dependencies.

• The TestGCSArtifactService function integrates with the generic artifact service test suite defined in internal/artifact/tests to validate functionality such as saving, loading, listing, and deleting artifacts.

• This file enables continuous integration and local testing of the GCS artifact service by isolating it from real Google Cloud resources.

Usage Example

func TestExample(t *testing.T) {
    service, err := newGCSArtifactServiceForTesting("my-test-bucket")
    if err != nil {
        t.Fatal(err)
    }

    // Use the service to save, load, or delete artifacts in tests.
    // Example: save an artifact and verify version increment.
    
    // Note: For comprehensive tests, see TestGCSArtifactService.
}

Mermaid Diagram: Structure of gcs_test.go

classDiagram
class fakeClient {
-inMemoryBucket: gcsBucket
+bucket()
}
class fakeBucket {
-mu: Mutex
-objectsMap: map[string]*fakeObject
+object()
+objects()
}
class fakeObject {
-mu: Mutex
-name: string
-data: []byte
-deleted: bool
-contentType: string
+newWriter()
+attrs()
+delete()
+newReader()
}
class fakeWriter {
-obj: *fakeObject
-buffer: bytes.Buffer
-contentType: string
+Write()
+Close()
+SetContentType()
}
class fakeObjectIterator {
-objects: []*fakeObject
-index: int
+next()
}
fakeClient "1" --> "1" fakeBucket : contains
fakeBucket "1" --> "*" fakeObject : stores
fakeBucket --> fakeObjectIterator : returns iterator
fakeObject --> fakeWriter : creates writer
fakeObjectIterator --> fakeObject : iterates over

This documentation references the broader Artifact Management and Google Cloud Storage Service topics for detailed service interfaces, naming conventions, and artifact versioning schemes. The testing mocks here implement the client interfaces described therein, enabling the development and validation of artifact persistence logic in isolation.