Orb のテスト手法

Orb のテストに関するベストプラクティスを説明します。

Orb は、CircleCI のパイプラインの重要な構成要素であり、ツールのインストール、テストの実行、アプリケーションのデプロイを行います。 他のソフトウェアと同様に、新しい変更による Orb の破損を防ぐために、テストを行うことが重要です。 Orb は YAML で開発されるため、そのテストプロセスはプログラミング言語のテストプロセスとは少し異なります。 しかし、Orb 開発キットがあれば、Orb について厳密かつ網羅的なテストを簡単に実施できます。

このガイドに従って、Orb 開発キットを使用して Orb を作成すると、 Orb テンプレートと同じ構造の Orb プロジェクトが出来上がります。 .circleci/ ディレクトリの中を見ると、config.yml と test-deploy.yml の 2 つの設定ファイルがあり、どちらにも実行可能なテスト一式が含まれています。

最初の設定ファイルは、2 つ目のワークフローの test-deploy で結合テストを実行できるよう、Orb の開発版をパブリッシュします。 パイプラインのこの時点では、Orb がまだパブリッシュされていないため、Orb を_直接_テストすることはできませんが、この段階ではスクリプトの構文チェックやバリデーションおよびレビュー、単体テストを実行することも可能です。

Orb の開発版がパブリッシュされた後、最後の orb-tools/continue ジョブが 2 つ目のワークフロー、test-deploy をトリガーします。

完全な config.yml テンプレートについては、こちらを参照してください。

2 つ目の設定ファイルには、2 つの主要タスクがあります。1 つ目の設定ファイルで Orb の開発版がパブリッシュされたので、結合テストで Orb を_直接_テストできるようになりました。タグが作成された場合は、この 2 つ目の設定ファイルにより Orb が CircleCI Orb レジストリにパブリッシュされます。

完全な test-deploy.yml テンプレートについては、こちらを参照してください。

Orb のテストの最も基本的な形式は、設定ファイルのバリデーションとコードの構文チェックです。 パッケージ化およびパブリッシュされる Orb は、有効な YAML 形式であり、かつ CircleCI の構文に従っている必要があります。 Orb 開発キットを使用していれば、これら両方のチェックは、プロジェクトの設定ファイル .circleci/config.yml に定められた CI/CD パイプラインにより自動で行われます。 また、ローカル環境において手動で実施することも可能です。

# Snippet from lint-pack workflow in config.yml
workflows:
  lint-pack:
    jobs:
      - orb-tools/lint # Lints the YAML and CircleCI syntax of the orb
      - orb-tools/pack # Packs the orb source and validates it

上記ワークフローの最初にあるジョブ orb-tools/lint は、Orb 開発キットの主要コンポーネントである orb-tools Orb のジョブです。 この orb-tools/lint ジョブは、 YAML の基本的な構文チェックを行います。 構文チェックのルールやその他の設定は Orb レジストリに記載されているジョブのパラメーターにより変更できます。

yamllint をローカルにインストールしている場合:

$ yamllint ./src

CircleCI の Local Execute を使用する場合:

circleci local execute orb-tools/lint

YAML の構文チェックに加えて、「パッケージ化」した orb.yml ファイルを検証し、Orbスキーマに正しく準拠していることを確認する必要があります。 まず、Orb を パッケージ化して、複数のソースファイルを orb.yml に結合させます。 次に、 circleci orb validate コマンドを実行して、スキーマを確認します。

# Snippet from lint-pack workflow in config.yml
workflows:
  lint-pack:
    jobs:
      - orb-tools/pack # Packs the orb source and validates it

Orb をローカルでパッケージ化してバリデーションを行うには、次のコマンドを実行します。

circleci orb pack src > orb.yml
circleci orb validate orb.yml

または、CircleCI の Local Execute を使用します。

circleci local execute orb-tools/pack

Orb 開発キットを使用する大きなメリットとして、完成版の Orb に 外部の bash スクリプトをインポートできる機能が挙げられます。 bash スクリプトは src/scripts ディレクトリに保存できるので、スクリプトに対して別のテストも実行できます。

bash スクリプトの最も基本的なテストは、”ShellCheck” というバリデーションツールです。 これは bash 用の構文チェックツールのようなもので、詳細は shellcheck.net に記載されています。

lint-pack ワークフローには、 ShellCheck Orb が含まれています。 ShellCheck Orb のステップはすべて省略可能であり、特に Orb でスクリプトのインストールが不要な場合は削除してかまいません。

ShellCheck をローカルで実行するには、次のコマンドを実行します。

shellcheck src/scripts/*.sh

または、CircleCI の Local Execute を使用します。

circleci local execute shellcheck/check

orb-tools Orb には、orb-tools/review ジョブが含まれています。このジョブは、ベストプラクティスを実装し、Orb の品質を向上するために設計された一連のテストを Orb に対して実行します。 “review” ジョブは、ShellCheck に厳密に基づいて作られおり、”RC” Review Check というルールのリストに基づいて動作します。 各 “RC” コードは特定のルールに対応しています。ただし、このルールはオプションであって無視することもできます。

Review Check は JUNIT XML 形式に出力され、UI にネイティブに表示されるよう、自動的に CircleCI にアップロードされます。

エラーをクリックすると、エラーが検出されたファイルやコードの行などの詳細情報と、解決策の提案が表示されます。

Orb 開発キットの <<include(file)>>ファイルインクルード機能と src/scripts ディレクトリを使用して、bash ファイルを保存して読み込むと、スクリプトに対して有効な結合テストを作成できます。

内部スクリプトが複雑な Orb の場合、コードの品質向上やローカル開発テストの簡易化のために、単体テストを実施することをお勧めします。

bash 単体テストについては、 BATS-Core ライブラリをお勧めします。これは、bash 用のオープンソースのテストフレームワークで、JavaScript 用の Jest に類似しています。

CircleCI では BATS orb をすでに作成しており、BATS を簡単に CircleCI パイプラインに統合できます。

BATS を Orb に追加するには、次のステップに従います。

1. tests ディレクトリを Orb の src ディレクトリに追加します。
2. tests ディレクトリでテストを作成します。
3. circleci/bats Orb を config.yml ファイルに追加します。
4. bats/run ジョブを config.yml ファイルのパブリッシュ前のジョブに追加します。

workflows:
  lint-pack:
    jobs:
      - orb-tools/lint:
          filters: *filters
      - orb-tools/pack:
          filters: *filters
      - orb-tools/review:
          filters: *filters
# Add bats
      - bats/run:
          filters: *filters
          path: ./src/tests
# ...
# And ensure to mark it as required in the publish job.
 - orb-tools/publish:
          requires:
            [orb-tools/lint, orb-tools/review, orb-tools/pack, shellcheck/check, bats/run]

bash 用単体テストの記述方法については、 Slack Orb を参照してください。

ソースコード上で行えるバリデーション、構文チェック、ShellCheck および他のテストの完了後に、実際の CircleCI 設定ファイルで Orb の機能をテストする必要があります。 2 つ目の設定ファイル (test-deploy.yml) では、1 つ目の設定ファイルでパブリッシュした Orb の開発版にアクセスし、Orb コマンドおよびジョブの実行を試してみることができます。

デフォルトでは、新しい Orb を作成すると、”greet” コマンドを備えた Orb ソースのサンプルが手に入ります。 結合テストとして、test-deploy ワークフローで greet コマンド (場合によっては、他のコマンド) をテストできます。 このコマンドを実行して、エラーが無く実行されているかをバリデーションすることができます。また、追加のチェックを実行することで、コマンドの機能を確認することもできます。

test-deploy.yml ファイルに、command-tests という名前のジョブが表示されます。 このサンプルジョブでは、結合テストとして 1 つまたはすべてのコマンドを実行します。

このジョブでは、テストするパラメーターを使って、Orb コマンドを呼び出すことができます。 例えば、コマンドによりコマンドライン ツールをインストールする場合、追加ステップでテストを実行してコマンドが有効かどうかを確認できます。

デフォルトでは、含まれている “greet” コマンドがテストされます。 greet コマンドは stdout にメッセージを出力するだけなので、他のバリデーションチェックは行うことはできません。

jobs:
    command-tests:
      docker:
        - image: cimg/base:current
          auth:
            username: mydockerhub-user
            password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
      steps:
        # Run your orb's commands to validate them.
        - <orb-name>/greet

以下は、 GitHub CLI Orb の実際のサンプルスニペットです。

jobs:
    command-tests:
      docker:
        - image: cimg/base:current
          auth:
            username: mydockerhub-user
            password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
      steps:
        - github-cli/install
        - run:
            name: verify Install
            command: command -v gh

この例では、 github-cli/install コマンドをテストしています。 このコマンドだけでは成功または失敗する場合がありますが、次のステップで GitHub CLI がインストールされており、コマンドラインで利用できるかを確認することもできます。 gh バイナリがこのパスになければ、このジョブはこのステップで失敗します。

必要に応じて、コマンドをテストするために複数のジョブを使用できます。Orb にコマンドがない場合は、そのようなジョブがない可能性があります。 orb-tools/publish ジョブが、お客様のテストを含むジョブを要求していることを確認してください。

Orb 内でのジョブのテストは、コマンドのテストと非常によく似ています。 ただし、考慮すべき制限が他にいくつかあります。

まず、test-deploy ワークフローでは、上記のコマンドのテストで述べたように、orb-tools/publish ジョブは、最終的にはワークフローの中でそれ以前のすべてのジョブが完了している必要があります。 Orb のジョブをテストするには、ジョブをこのワークフローに追加して、orb-tools/publish ジョブでそれが求められていることを確認する必要があります。

以下は、CircleCI の AWS ECR Orb のサンプルです。

# Shortened for this example
workflows:
  test-deploy:
    jobs:
      - aws-ecr/build-and-push-image:
          name: integration-tests-default-profile
          tag: integration,myECRRepoTag
          dockerfile: sample/Dockerfile
          executor: amd64
          post-steps:
            - run:
                name: "Delete repository"
                command: aws ecr delete-repository
          filters:
            tags:
              only: /.*/
# ...
      - orb-tools/publish:
          orb-name: circleci/aws-ecr
          vcs-type: << pipeline.project.type >>
          pub-type: production
          requires:
            - integration-tests-default-profile
          context: orb-publisher
          filters:
            branches:
              ignore: /.*/
            tags:
              only: /^v[0-9]+\.[0-9]+\.[0-9]+$/

AWS ECR Orb には、イメージをビルドし AWS ECR リポジトリにプッシュする、”build-and-push-image” という名前のジョブが含まれています。 このジョブや他のジョブを複数のパラメーター オプションを使用して実行し、コードを変更するたびに機能をテストします。

新たなステップを追加してコマンドをテストする方法と同様に、 post-steps を利用してジョブ環境でバリデーションしたり、このサンプルで示すように、ジョブで作成したものをすべて「クリーンアップ」したりすることもできます。 Post-Step は、既存のジョブの最後に挿入可能な追加のステップです。

Orb の新しい機能を追加し、CI にパスする適切なテストを作成できたら、Orb レジストリに Orb をパブリッシュしましょう。 本番対応の Orb をリリースする方法については、 Orb のパブリッシュを参照してください。

• CircleCI Orb の概要については、 Orb のコンセプトを参照してください。
• ワークフローやジョブで使用する Orb については、 Orb のパブリッシュを参照してください。
• 再利用可能な Orb、コマンド、パラメーター、Executor のサンプルについては、 再利用可能な設定ファイル リファレンスガイドを参照してください。