データベース

エミュレータを使用した Spanner インテグレーションテスト

2024年2月5日

Google Cloud Japan Team

※この投稿は米国時間 2024 年 1 月 31 日に、Google Cloud blog に投稿されたものの抄訳です。

Spanner は、高いスケーラビリティと信頼性を備え、グローバルに分散された Google Cloud のデータベースです。優れたパフォーマンスと継続的運用が求められるビジネスクリティカルなアプリケーションに最適です。

デベロッパーは、アプリケーションに Spanner をシームレスに統合するために徹底的にテストを行う必要があります。インテグレーションテストは、システムのさまざまなコンポーネントに変更を加えた後に、それらのコンポーネントが連動するかの検証に重点を置いて行います。Spanner の場合、アプリケーションによるトランザクションやエラー処理などのデータ操作がデータベースと正しく連動するかをインテグレーションテストで確認します。

この投稿では、GitHub Action と Spanner エミュレータを使用して Spanner のインテグレーションテストの環境を設定する方法を紹介します。このエミュレータは Google Cloud 外で Spanner の動作を模倣するものです。Spanner データベースを活用するアプリケーションを迅速に開発するのに役立ちます。

テストするアプリケーションの例として、架空のゲームのプレイヤープロファイルを管理する Golang のバックエンドサービスを使用します。これらで紹介する原則は、他の言語や業界の他のアプリケーションとサービスにも適用できます。

ここではプロファイルサービスと Spanner の間の「インテグレーション」をテストして、サービスへのコード変更が正しく動作するかどうかフィードバックループを素早く獲得します。これは、スタック内のすべてのサービス間で行う完全なエンドツーエンドのテストではありません。エンドツーエンドのテストを行う場合は、本番環境へのデプロイ前に、Spanner を使用した実際のステージング環境を利用する必要があります。

ソフトウェアリリースの有効性を評価するために実施すべきテストの種類の概要については、こちらの投稿をご覧ください。

インテグレーションテストでは、以下のコンポーネントを使用します。

GitHub Actions は、テストの実行を自動化するもので、コードが保存されているプラットフォームに組み込まれています。他の CI / CD プラットフォームも同様に動作します。
Spanner エミュレータは、Spanner データベースの軽量のオフラインエミュレータです。
プロファイル サービスは、Spanner に依存するアプリケーションです。

これらのコンポーネントの詳細は後述しますが、アーキテクチャは以下のようになります。

https://storage.googleapis.com/gweb-cloudblog-publish/images/SpannerEmulatorArchitecture.max-1000x1000.jpg

Spanner エミュレータを使用したプロファイルサービスのインテグレーションテスト

GitHub Actions: ワークフローの自動化

サービスコードが GitHub リポジトリに保存されているため、GitHub Actions が自動インテグレーションテストに最適なコンポーネントとなります。

GitHub Actions は、ソフトウェア開発のワークフローを自動化する継続的インテグレーションと継続的デリバリー（CI / CD）プラットフォームの一部です。GitHub リポジトリとシームレスに統合され、これによりコードの変更またはスケジュール設定されたイベントによってトリガーされる自動タスクを定義、実行できます。

Spanner エミュレータ: ローカルテスト環境

Spanner エミュレータは、完全オフラインで実行できる軽量なツールです。これにより、デベロッパーはクラウド費用を負担することも実際の Spanner インスタンスに依存することもなく、Spanner の利用を想定してアプリケーションをテストできます。これにより、迅速な開発サイクルとインテグレーションに関する問題の早期発見が容易になります。

Spanner エミュレータには、実際の Spanner データベースとは異なる点や制限事項がいくつかあり、これらを把握しておく必要があります。

プロファイルサービスのインテグレーションテストの環境設定

サンプルのゲームアプリケーションのコードは GitHub にあります。最初にプロファイルサービスのインテグレーションテストを見てから、GitHub Action を使用して自動インテグレーションテストを実現するワークフローを見ていきます。

プロファイルサービスのインテグレーションテストは、プロファイルサービスの main_test.go ファイルにあります。このファイルは、以下のセクションにわかれています。

Spanner エミュレータの起動
スキーマと必要なテストデータを使用した Spanner インスタンスと Spanner データベースの設定
プロファイルサービスの設定
テスト自体
テスト完了後のクリーンアップ

Spanner エミュレータの起動

Spanner エミュレータはコンテナとしてデプロイされるため、testcontainers-go ライブラリを使用します。これにより、Spanner エミュレータの起動を以下のとおり非常に簡単にコード化できます。

読み込んでいます...

var TESTNETWORK = "game-sample-test"

type Emulator struct {
   testcontainers.Container
   Endpoint string
   Project  string
   Instance string
   Database string
}
*snip*
func setupSpannerEmulator(ctx context.Context) (*Emulator, error) {
   req := testcontainers.ContainerRequest{
       Image: "gcr.io/cloud-spanner-emulator/emulator:1.5.0",
       ExposedPorts: []string{"9010/tcp"},
       Networks: []string{
           TESTNETWORK,
       },
       NetworkAliases: map[string][]string{
           TESTNETWORK: []string{
               "emulator",
           },
       },
       Name: "emulator",
       WaitingFor: wait.ForLog("gRPC server listening at"),
   }
   spannerEmulator, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
       ContainerRequest: req,
       Started: true,
   })
   if err != nil {
       return nil, err
   }

// コンテナの IP アドレスを取得する
   ip, err := spannerEmulator.Host(ctx)
   if err != nil {
       return nil, err
   }

// コンテナのポートを取得する
   port, err := spannerEmulator.MappedPort(ctx, "9010")
   if err != nil {
       return nil, err
   }

これにより、エミュレータコンテナにポート 9010 がマッピングされ、これを使用して通信できるようになります。ネットワーキングでは Docker ネットワークを使用するため、そのネットワークにアクセスできるコンテナかプロセスであれば、「emulator」コンテナと通信できます。

testcontainers-go ライブラリを使用することで、コンテナの準備が完了するまで待機してから以降のステップに進みやすくなります。

コンテナの準備が完了したら、ホスト情報を取得してオペレーティングシステムの環境変数として公開し、golang 構造体を定義します。これらはともに、後でインスタンスとデータベースを設定するときに使用します。

読み込んでいます...

すべての準備が完了したら、以下のとおり Spanner のインスタンスとデータベースを作成できます。

読み込んでいます...

Spanner のインスタンスとデータベースを設定する

エミュレータが動作している状態で、テスト用のインスタンスとデータベースを設定する必要があります。まず、以下のとおりインスタンスを設定します。

読み込んでいます...

ここでは、Spanner インスタンスの golang ライブラリを使用してインスタンスを作成します。これは、先に SPANNER_EMULATOR_HOST 環境変数を設定している場合のみ機能します。それ以外の場合は、Spanner ライブラリが Google Cloud プロジェクトで動作している実際の Spanner インスタンスを探します。

ここで、インスタンスの準備が完了するまで待ってからテストに進みます。

読み込んでいます...

データベース設定には、スキーマファイルが必要です。このスキーマファイルをどこから取得するかは、プロセスによります。この例では、Makefile での make profile-integration の手順でマスタースキーマファイルのコピーを作成します。これにより、プレイヤーのプロファイルに関連する最新のスキーマを取得できます。

データベースを設定するには、Spanner のデータベースの golang ライブラリを活用します。

読み込んでいます...

//go:embed test_data/schema.sql
var SCHEMAFILE embed.FS

func setupDatabase(ctx context.Context, ec Emulator) error {
  // ファイルからスキーマのステートメントを取得する
  schema, _ := SCHEMAFILE.ReadFile("test_data/schema.sql")

// 必須: Spanner エミュレータが「DEFAULT」構文をサポートしている場合はこれを削除
  // これは、SQL を使用してデータを挿入する場合も引き続き問題となります。https://github.com/GoogleCloudPlatform/cloud-spanner-emulator/issues/101 をご覧ください。
   schemaStringFix := strings.Replace(string(schema), "account_balance NUMERIC NOT NULL DEFAULT (0.00),", "account_balance NUMERIC,", 1)

schemaStatements := strings.Split(schemaStringFix, ";")

adminClient, err := database.NewDatabaseAdminClient(ctx)
   if err != nil {
       return err
   }
   defer adminClient.Close()

op, err := adminClient.CreateDatabase(ctx, &databasepb.CreateDatabaseRequest{
       Parent:          fmt.Sprintf("projects/%s/instances/%s", ec.Project, ec.Instance),
       CreateStatement: "CREATE DATABASE `" + ec.Database + "`",
       ExtraStatements: schemaStatements,
   })
   if err != nil {
       fmt.Printf("Error: [%s]", err)
       return err
   }
   if _, err := op.Wait(ctx); err != nil {
       fmt.Printf("Error: [%s]", err)
       return err
   }

fmt.Printf("Created emulator database [%s]\n", ec.Database)
   return nil

}

この関数では、エミュレータが理解できるようにスキーマの変更を処理します。スキーマファイルを、末尾のセミコロンを除いたステートメントの配列に変換する必要があります。

データベースの設定が完了したら、プロファイルサービスを起動できます。

プロファイルサービスを起動する

ここで、プロファイルサービスを、エミュレータと通信できる別のコンテナ（testcontainers-go を使用）として起動します。

読み込んでいます...

type Service struct {
   testcontainers.Container
   Endpoint string
}
*snip*
func setupService(ctx context.Context, ec *Emulator) (*Service, error) {
   var service = "profile-service"
   req := testcontainers.ContainerRequest{
       Image:        fmt.Sprintf("%s:latest", service),
       Name:         service,
       ExposedPorts: []string{"80:80/tcp"}, // ローカルホストの 80 にバインドし、コンテナポートについて知らない状態を回避する
       Networks:     []string{TESTNETWORK},
       NetworkAliases: map[string][]string{
           TESTNETWORK: []string{
               service,
           },
       },
       Env: map[string]string{
           "SPANNER_PROJECT_ID":    ec.Project,
           "SPANNER_INSTANCE_ID":   ec.Instance,
           "SPANNER_DATABASE_ID":   ec.Database,
           "SERVICE_HOST":          "0.0.0.0",
           "SERVICE_PORT":          "80",
           "SPANNER_EMULATOR_HOST": ec.Endpoint,
       },
       WaitingFor: wait.ForLog("Listening and serving HTTP on 0.0.0.0:80"),
   }
   serviceContainer, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
       ContainerRequest: req,
       Started:          true,
   })
   if err != nil {
       return nil, err
   }

サービスの準備が完了したら、以下のとおりエンドポイント情報を取得して、テストで使用する構造体として公開します。

読み込んでいます...

エミュレータとサービスの両方が動作している状態で、テストを実行できます。

テストの実行

このインテグレーションテストでは、testify assert ライブラリを使用して、プロファイルサービスのエンドポイントに到達します。サービスにより、以下の動作をテストします。

読み込んでいます...

クリーンアップ

テストが実行されたら、作成したコンテナをクリーンアップします。これを行うには、teardown 関数を実行します。

読み込んでいます...

ここでも、testcontainers-go のおかげで簡単にクリーンアップを行えます。

GitHub Actions のワークフロー

GitHub Actions の設定は、リポジトリの .github/workflows ディレクトリにワークフローファイルを追加するだけの簡単な処理です。

アクションの動作は、各ファイルの手順によって変わります。アクションを push リクエスト時にトリガーするか、それとも pull リクエスト時にトリガーするか。すべてのファイルに変更が発生した場合にアクションをトリガーするか、それとも一部のファイルの変更によってアクションをトリガーするか。アクションを実行するために、どのような依存関係を設定する必要があるでしょうか。

以下は、プロファイルサービスについて定義された YAML アクションです。

読み込んでいます...

この単純な yaml ファイルでは、backend_services/profile ディレクトリの変更を含む pull リクエストがあった場合のみ動作するようタスクが定義されます。このアクションにより、Go の依存関係がインストールされ、何度かの lint チェックが実行されてから、単体テストとインテグレーションテストに移ります。

単体テストとインテグレーションテストの make コマンドは、リポジトリの Makefile で定義されています。

読み込んでいます...

インテグレーションテストにより test_data/schema.sql ファイルが設定されています。

これにより、プロファイルサービスの変更に伴って pull リクエストが開かれると、インテグレーションテストはおおむね以下のようになります。

https://storage.googleapis.com/gweb-cloudblog-publish/images/Profile_Service_Test_start.max-1800x1800.png

https://storage.googleapis.com/gweb-cloudblog-publish/images/ProfileIntegrationTestEnd.max-1500x1500.png

まとめ

Spanner エミュレータと GitHub Actions を活用することで、Spanner アプリケーション用の堅牢なインテグレーションテスト環境を設定できます。この手法により、開発工程の早い段階でインテグレーションに関する問題を検出、解決し、Spanner をアプリケーションにスムーズに統合できます。

Spanner の機能をより詳しく知りたい場合は、無料トライアルインスタンスをご利用ください。これを利用すると、90 日間無料で Spanner を試して、その特徴と機能を実際に体験できます。

ーデベロッパーリレーションズ エンジニア Derek Downey

投稿先