Skip to content

GCloud

Since v0.25.0

Introduction

The Testcontainers module for GCloud.

Adding this module to your project dependencies

Please run the following command to add the GCloud module to your Go dependencies:

go get github.com/testcontainers/testcontainers-go/modules/gcloud

Usage example

The Google Cloud module exposes the following Go packages:

  • BigQuery: github.com/testcontainers/testcontainers-go/modules/gcloud/bigquery.
  • BigTable: github.com/testcontainers/testcontainers-go/modules/gcloud/bigtable.
  • Datastore: github.com/testcontainers/testcontainers-go/modules/gcloud/datastore.
  • Firestore: github.com/testcontainers/testcontainers-go/modules/gcloud/firestore.
  • Pubsub: github.com/testcontainers/testcontainers-go/modules/gcloud/pubsub.
  • Spanner: github.com/testcontainers/testcontainers-go/modules/gcloud/spanner.

Info

By default, the all the emulators use gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators as the default Docker image, except for the BigQuery emulator, which uses ghcr.io/goccy/bigquery-emulator:0.6.1, and Spanner, which uses gcr.io/cloud-spanner-emulator/emulator:1.4.0.

BigQuery

Run function

The BigQuery module exposes one entrypoint function to create the BigQuery container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "ghcr.io/goccy/bigquery-emulator:0.6.1").

Container Options

When starting the BigQuery container, you can pass options in a variadic way to configure it.

WithProjectID

The WithProjectID function sets the project ID for the Google Cloud container.

Data YAML (Seed File)

If you would like to do additional initialization in the BigQuery container, add a data.yaml file represented by an io.Reader to the container request with the WithDataYAML function. That file is copied after the container is created but before it's started. The startup command then used will look like --project test --data-from-yaml /testcontainers-data.yaml.

An example of a data.yaml file that seeds the BigQuery instance with datasets and tables is shown below:

projects:
  - id: test
    datasets:
      - id: dataset1
        tables:
          - id: table_a
            columns:
              - name: id
                type: INTEGER
              - name: name
                type: STRING
              - name: createdAt
                type: TIMESTAMP
            data:
              - id: 1
                name: alice
                createdAt: "2022-10-21T00:00:00"
              - id: 30
                name: bob
                createdAt: "2022-10-21T00:00:00"

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Examples

ctx := context.Background()

bigQueryContainer, err := tcbigquery.Run(
    ctx,
    "ghcr.io/goccy/bigquery-emulator:0.6.1",
    tcbigquery.WithProjectID("bigquery-project"),
)
defer func() {
    if err := testcontainers.TerminateContainer(bigQueryContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to run container: %v", err)
    return
}

projectID := bigQueryContainer.ProjectID()

opts := []option.ClientOption{
    option.WithEndpoint(bigQueryContainer.URI()),
    option.WithGRPCDialOption(grpc.WithTransportCredentials(insecure.NewCredentials())),
    option.WithoutAuthentication(),
    internaloption.SkipDialSettingsValidation(),
}

client, err := bigquery.NewClient(ctx, projectID, opts...)
if err != nil {
    log.Printf("failed to create bigquery client: %v", err)
    return
}
defer client.Close()

It's important to set the option.WithEndpoint() option using the container's URI, as shown in the client example above.

BigTable

Run function

The BigTable module exposes one entrypoint function to create the BigTable container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators").

Container Options

When starting the BigTable container, you can pass options in a variadic way to configure it.

WithProjectID

The WithProjectID function sets the project ID for the Google Cloud container.

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Examples

ctx := context.Background()

bigTableContainer, err := tcbigtable.Run(
    ctx,
    "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators",
    tcbigtable.WithProjectID("bigtable-project"),
)
defer func() {
    if err := testcontainers.TerminateContainer(bigTableContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to run container: %v", err)
    return
}

projectID := bigTableContainer.ProjectID()

const (
    instanceID = "test-instance"
    tableName  = "test-table"
)

options := []option.ClientOption{
    option.WithEndpoint(bigTableContainer.URI()),
    option.WithoutAuthentication(),
    option.WithGRPCDialOption(grpc.WithTransportCredentials(insecure.NewCredentials())),
}
adminClient, err := bigtable.NewAdminClient(ctx, projectID, instanceID, options...)
if err != nil {
    log.Printf("failed to create admin client: %v", err)
    return
}
defer adminClient.Close()

client, err := bigtable.NewClient(ctx, projectID, instanceID, options...)
if err != nil {
    log.Printf("failed to create client: %v", err)
    return
}
defer client.Close()

It's important to set the option.WithEndpoint() option using the container's URI, as shown in the Admin client example above.

Datastore

Run function

The Datastore module exposes one entrypoint function to create the Datastore container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators").

Container Options

When starting the Datastore container, you can pass options in a variadic way to configure it.

WithProjectID

The WithProjectID function sets the project ID for the Google Cloud container.

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Examples

ctx := context.Background()

datastoreContainer, err := tcdatastore.Run(
    ctx,
    "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators",
    tcdatastore.WithProjectID("datastore-project"),
)
defer func() {
    if err := testcontainers.TerminateContainer(datastoreContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to run container: %v", err)
    return
}

projectID := datastoreContainer.ProjectID()

options := []option.ClientOption{
    option.WithEndpoint(datastoreContainer.URI()),
    option.WithoutAuthentication(),
    option.WithGRPCDialOption(grpc.WithTransportCredentials(insecure.NewCredentials())),
}

dsClient, err := datastore.NewClient(ctx, projectID, options...)
if err != nil {
    log.Printf("failed to create client: %v", err)
    return
}
defer dsClient.Close()

It's important to set the option.WithEndpoint() option using the container's URI, as shown in the client example above.

Firestore

Run function

The Firestore module exposes one entrypoint function to create the Firestore container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators").

Container Options

When starting the Firestore container, you can pass options in a variadic way to configure it.

WithProjectID

The WithProjectID function sets the project ID for the Google Cloud container.

Datastore mode

Using the WithDatastoreMode option will run the Firestore emulator using Firestore In Datastore mode allowing you to use Datastore APIs and clients towards the Firestore emulator.

Requires cloud-sdk:465.0.0 or higher

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Examples

ctx := context.Background()

firestoreContainer, err := tcfirestore.Run(
    ctx,
    "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators",
    tcfirestore.WithProjectID("firestore-project"),
)
defer func() {
    if err := testcontainers.TerminateContainer(firestoreContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to run container: %v", err)
    return
}

projectID := firestoreContainer.ProjectID()

conn, err := grpc.NewClient(firestoreContainer.URI(), grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithPerRPCCredentials(emulatorCreds{}))
if err != nil {
    log.Printf("failed to dial: %v", err)
    return
}

options := []option.ClientOption{option.WithGRPCConn(conn)}
client, err := firestore.NewClient(ctx, projectID, options...)
if err != nil {
    log.Printf("failed to create client: %v", err)
    return
}
defer client.Close()

It's important to set the target string of the grpc.NewClient method using the container's URI, as shown in the client example above.

Pubsub

Run function

The Pubsub module exposes one entrypoint function to create the Pubsub container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators").

Container Options

When starting the Pubsub container, you can pass options in a variadic way to configure it.

WithProjectID

The WithProjectID function sets the project ID for the Google Cloud container.

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Examples

ctx := context.Background()

pubsubContainer, err := tcpubsub.Run(
    ctx,
    "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators",
    tcpubsub.WithProjectID("pubsub-project"),
)
defer func() {
    if err := testcontainers.TerminateContainer(pubsubContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to run container: %v", err)
    return
}

projectID := pubsubContainer.ProjectID()

conn, err := grpc.NewClient(pubsubContainer.URI(), grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
    log.Printf("failed to dial: %v", err)
    return
}

options := []option.ClientOption{option.WithGRPCConn(conn)}
client, err := pubsub.NewClient(ctx, projectID, options...)
if err != nil {
    log.Printf("failed to create client: %v", err)
    return
}
defer client.Close()

It's important to set the target string of the grpc.NewClient method using the container's URI, as shown in the client example above.

Spanner

Run function

The Spanner module exposes one entrypoint function to create the Spanner container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators").

Container Options

When starting the Spanner container, you can pass options in a variadic way to configure it.

WithProjectID

The WithProjectID function sets the project ID for the Google Cloud container.

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Examples

ctx := context.Background()

spannerContainer, err := tcspanner.Run(
    ctx,
    "gcr.io/cloud-spanner-emulator/emulator:1.4.0",
    tcspanner.WithProjectID("spanner-project"),
)
defer func() {
    if err := testcontainers.TerminateContainer(spannerContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to run container: %v", err)
    return
}

projectID := spannerContainer.ProjectID()

const (
    instanceID   = "test-instance"
    databaseName = "test-db"
)

options := []option.ClientOption{
    option.WithEndpoint(spannerContainer.URI()),
    option.WithGRPCDialOption(grpc.WithTransportCredentials(insecure.NewCredentials())),
    option.WithoutAuthentication(),
    internaloption.SkipDialSettingsValidation(),
}

instanceAdmin, err := instance.NewInstanceAdminClient(ctx, options...)
if err != nil {
    log.Printf("failed to create instance admin client: %v", err)
    return
}
defer instanceAdmin.Close()

c, err := database.NewDatabaseAdminClient(ctx, options...)
if err != nil {
    log.Printf("failed to create admin client: %v", err)
    return
}
defer c.Close()

It's important to set the option.WithEndpoint() option using the container's URI, as shown in the Admin client example above.