DEV Community

Cover image for カラテAPIテストにおけるDSL実践ガイド
Akira
Akira

Posted on • Originally published at apidog.com

カラテAPIテストにおけるDSL実践ガイド

平易な英語に近い構文で読めて、Gitでレビューでき、CIでそのまま実行できるAPIテストが必要なら、Karateは有力な選択肢です。KarateではJavaコードではなく、Given / When / Thenで構成された.featureファイルにAPIテストを記述します。この記事では、Karateの基本構成、実装例、CI実行、Apidogのようなコード不要ツールとの使い分けを実践ベースで整理します。

今すぐApidogを試す

Karateとは

Karateは、APIテスト向けのオープンソースのJavaベース自動化フレームワークです。テストはGherkin形式の.featureファイルに、BDD由来のGiven / When / Then構文で記述します。

Cucumberと似ていますが、KarateではHTTPリクエスト、レスポンス検証、JSONマッチングが組み込まれているため、基本的なAPIテストにステップ定義のグルーコードは不要です。

KarateにはAPIテスト以外にも、モック、Gatling連携によるパフォーマンステスト、UI自動化のモジュールがあります。ただし、最初に導入するならAPIテストのコア機能から始めるのが実用的です。

Karateのテストはプレーンテキストなので、Gitで差分管理しやすく、プルリクエスト上で「どのAPI仕様・アサーションが変わったか」を確認できます。これはGitネイティブのコードベースのワークフローと相性が良いです。

Given / When / Thenに慣れていない場合は、ビヘイビア駆動開発の考え方を押さえておくと、Karateの構造を理解しやすくなります。

基本構成：.featureファイルとkarate-config.js

Karateの最小構成は次の2つです。

  • APIテストを書く.featureファイル
  • 環境別の設定を書くkarate-config.js

まずはシンプルなGETリクエストから見てみます。

Feature: User API

Scenario: List all users
  Given url 'https://jsonplaceholder.typicode.com'
  And path 'users'
  When method get
  Then status 200
  And match response == '#[10]'
Enter fullscreen mode Exit fullscreen mode

このシナリオは次の処理を行います。

  1. urlでベースURLを指定する
  2. pathで/usersを追加する
  3. method getでGETリクエストを送る
  4. status 200でHTTPステータスを検証する
  5. match response == '#[10]'でレスポンスが10件のJSON配列であることを検証する

#[10]はKarateのマッチャーです。JavaScriptではありません。配列の長さを検証するために使います。

Gherkin構文そのものを確認したい場合は、BDDとAPIテストのためのGherkinガイドも参考になります。

環境設定をkarate-config.jsに切り出す

実際のプロジェクトでは、開発環境、QA環境、本番環境でベースURLやトークンが変わります。Karateではkarate-config.jsに共通設定を定義できます。

function fn() {
  var env = karate.env || 'dev';

  var config = {
    baseUrl: 'https://jsonplaceholder.typicode.com'
  };

  if (env === 'qa') {
    config.baseUrl = 'https://qa.example.com';
  }

  return config;
}
Enter fullscreen mode Exit fullscreen mode

.feature側では、URLをハードコーディングせずにbaseUrlを参照します。

Feature: User API

Background:
  * url baseUrl

Scenario: List users
  Given path 'users'
  When method get
  Then status 200
Enter fullscreen mode Exit fullscreen mode

実行時に環境を切り替えるには、karate.envを渡します。

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

これにより、テストファイルを変更せずに環境だけを切り替えられます。

POSTリクエストのサンプル

次に、リクエストボディを送信するシナリオを書きます。

Feature: Create user

Background:
  * url baseUrl

Scenario: Create a new user returns 201
  Given path 'users'
  And request { name: 'Ada', job: 'engineer' }
  When method post
  Then status 201
  And match response.name == 'Ada'
  And match response.id == '#string'
Enter fullscreen mode Exit fullscreen mode

ポイントは次のとおりです。

  • Background:は各シナリオの前に実行される
  • *はGiven、When、Thenの代わりに使える汎用ステップ
  • requestにはJSONをそのまま書ける
  • #stringは「任意の文字列であること」を検証するファジーマッチャー

サーバーが生成するIDやタイムスタンプは固定値で検証しにくいため、#stringや#numberのような型ベースの検証を使うとテストが安定します。

JSONレスポンスを検証する

Karateの中心になるのがmatchです。matchを使うと、レスポンス全体、部分一致、配列、型などを簡潔に検証できます。

完全一致に近いスキーマ検証 

And match response == { id: '#number', name: 'Ada', job: 'engineer' }
Enter fullscreen mode Exit fullscreen mode

この例では、次を検証しています。

  • idは数値
  • nameはAda
  • jobはengineer

#number、#string、#boolean、#uuidなどはファジーマッチャーです。値そのものではなく、型や存在を検証します。

一部のフィールドだけ検証する

レスポンス全体ではなく、必要なフィールドだけを検証したい場合はcontainsを使います。

And match response contains { name: 'Ada' }
Enter fullscreen mode Exit fullscreen mode

レスポンスに他のフィールドが含まれていても、nameがAdaであれば合格します。

Karateでは、部分一致のために次のような構文も使えます。

And match response !contains { error: true }
And match response contains only { name: 'Ada', job: 'engineer' }
And match response contains any { role: 'admin', role: 'user' }
And match response contains deep { profile: { active: true } }
Enter fullscreen mode Exit fullscreen mode

配列の長さを検証する 

And match response == '#[10]'
Enter fullscreen mode Exit fullscreen mode

これはレスポンスが長さ10の配列であることを検証します。

配列の全要素にスキーマを適用する 

And match each response == { id: '#number', name: '#string' }
Enter fullscreen mode Exit fullscreen mode

この1行で、配列内のすべての要素が次の条件を満たすか確認できます。

  • idが数値
  • nameが文字列

通常のテストフレームワークならループと複数のアサーションが必要になりますが、Karateでは1行で書けます。APIレスポンス検証の考え方をさらに整理したい場合は、APIアサーションに関する実践ガイドも参考になります。

データ駆動テストを書く

同じAPIに対して複数の入力値を試す場合は、Scenario OutlineとExamplesを使います。

Scenario Outline: Create users from a table
  Given url baseUrl
  And path 'users'
  And request { name: '<name>', job: '<job>' }
  When method post
  Then status 201
  And match response.name == '<name>'

  Examples:
    | name  | job       |
    | Ada   | engineer  |
    | Grace | scientist |
    | Alan  | analyst   |
Enter fullscreen mode Exit fullscreen mode

このシナリオは、Examplesの行数分だけ実行されます。この例では3回実行されます。

大量のテストデータを.featureファイルに直接書きたくない場合は、外部ファイルを読み込めます。

Examples:
  | read('classpath:test-data/users.json') |
Enter fullscreen mode Exit fullscreen mode

KarateはJSONやCSVを読み込めるため、テストデータをコードとは別に管理できます。

CIでKarateを実行する

KarateをCIで実行する方法は主に2つあります。

方法1：MavenまたはGradleから実行する

MavenまたはGradleプロジェクトでは、KarateをJUnit 5経由で実行できます。

一般的な流れは次のとおりです。

  1. karate-junit5依存関係を追加する
  2. JUnitのランナークラスを作成する
  3. CIでmvn testまたはgradle testを実行する

既存のJavaプロジェクトに組み込む場合は、この方法が自然です。

方法2：スタンドアロンjarで実行する

Javaプロジェクトに組み込みたくない場合は、スタンドアロンのkarate.jarを使えます。

java -jar karate.jar src/test/java/features
Enter fullscreen mode Exit fullscreen mode

タグで対象を絞ることもできます。

java -jar karate.jar --tags @smoke src/test/java/features
Enter fullscreen mode Exit fullscreen mode

並列実行と出力先の指定も可能です。

java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Enter fullscreen mode Exit fullscreen mode

環境を切り替える場合は、システムプロパティでkarate.envを渡します。

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Karateは実行後にHTMLレポートを出力するため、CIのアーティファクトとして保存しておくと失敗原因を確認しやすくなります。CI/CD全体でAPIテストを組み込む考え方は、CI/CDでAPIテストを自動化する方法でも解説されています。

Karateの長所とトレードオフ

Karateの主な長所は次のとおりです。

  • .featureファイルが読みやすい
  • HTTPリクエストとアサーションが組み込み済み
  • Javaのステップ定義を書かずにAPIテストを作れる
  • JSONマッチングが強力
  • Gitで差分レビューしやすい
  • CIに組み込みやすい
  • モックやパフォーマンステストにも拡張できる

一方で、次のトレードオフがあります。

  • JVM上で動作するためJava実行環境が必要
  • DSLの書き方を覚える必要がある
  • 複雑な共通処理ではJavaScriptやJavaインターオップが必要になることがある
  • 非開発者だけでテストを作成・保守するには学習コストがある

つまり、KarateはコードファーストなAPIテストフレームワークです。開発者がGit上でテストを管理したい場合に強く、非開発者も広く関わる運用では別の選択肢も検討するとよいです。

Karate vs コード不要のアプローチ（Apidog）

Karateは、.featureファイルをコードとして管理するGitネイティブなアプローチです。アプリケーションコードの隣にテストを置き、レビューし、CIで実行したいチームに向いています。

一方、Apidogは、視覚的にAPIテストを作成するコード不要のアプローチです。UI上でリクエストを連結し、クリック操作でアサーションを追加できます。

Apidogでは、APIの設計、デバッグ、モック、ドキュメント、テストを1箇所で扱えるため、既に定義したエンドポイントやスキーマをテストに再利用しやすくなります。Javaプロジェクトを保守したくないQAエンジニアやプロダクト担当者にとっては、開始しやすい方法です。

ApidogのテストはUIだけに閉じません。Apidog CLIを使うと、保存済みのシナリオやスイートをCIでヘッドレス実行できます。

まずCLIをインストールします。

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

次に、シナリオまたはスイートID、環境ID、レポート形式を指定して実行します。

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,json,junit
Enter fullscreen mode Exit fullscreen mode

主なオプションは次のとおりです。

  • -t: シナリオ、フォルダ、またはスイートを指定
  • -e: 実行環境を指定
  • -r: レポート形式を指定（cli、html、json、junitなど）
  • -dまたは--iteration-data: データ駆動実行用のデータファイルパスまたはテストデータIDを指定

Apidog CLIは、Nodeを実行できるCI環境で動作します。保存済みのApidogシナリオを実行するためのCLIであり、インタラクティブなリクエスト送信ツールやロードジェネレーターではありません。

詳しい使い方はCI/CDのためのApidog CLI、別ランナーとの比較はApidog CLI vs Newmanを参照してください。

どちらもCIで自動実行できます。違いは、テストを「コードで書くか」「UIで作るか」です。

選択方法

Karateを選ぶべきケースは次のとおりです。

  • 開発者主導でAPIテストを管理したい
  • JVMやJavaプロジェクトに慣れている
  • テストをアプリケーションコードの隣でGit管理したい
  • PRレビューでテスト差分を確認したい
  • JSONレスポンスの細かい検証をコードで制御したい

Apidogのようなコード不要ツールを選ぶべきケースは次のとおりです。

  • QAやプロダクト担当者もテスト作成に参加する
  • API設計、ドキュメント、モック、テストをまとめて管理したい
  • Javaビルドを保守せずにAPIチェックをCIで回したい
  • UIで素早くシナリオを作成したい
  • チーム全体でAPI仕様とテストを共有したい

両方を併用するチームもあります。たとえば、深いリグレッションテストはKarateでコード管理し、広いカバレッジや非開発者が編集するテストはApidogで管理する構成です。

まだ比較中であれば、API自動化テストフレームワークの選択方法で判断基準を整理できます。

よくある質問

Karateを使うにはJavaを知っている必要がありますか？

基本的なAPIテストを書くためにJavaを書く必要はありません。ただし、Karate自体はJVM上で動くため、Javaの実行環境は必要です。複雑な共通処理やカスタムヘルパーを書く場合は、JavaScriptまたはJavaの知識が役立ちます。

KarateはCucumberと何が違いますか？

どちらもGherkinのGiven / When / Then構文を使います。Cucumberではステップ定義コードを書く必要がありますが、KarateにはAPIテスト用のHTTPステップやアサーションが組み込まれています。そのため、標準的なAPIテストではグルーコードを保守する必要がありません。

KarateはMavenやGradleなしで実行できますか？

はい。スタンドアロンのkarate.jarを使えば、java -jar karate.jar <path>で.featureファイルを直接実行できます。タグ指定、並列実行、出力ディレクトリ指定にも対応しています。

#stringや#[10]は何ですか？

Karateのファジーマッチャーです。#stringは任意の文字列、#numberは数値、#[10]は長さ10のJSON配列を検証します。生成IDやタイムスタンプのように値が毎回変わるレスポンスを検証するときに便利です。

コード不要のAPIテストもCIで実行できますか？

はい。Apidogのような視覚的なAPIテストツールでも、保存済みシナリオをCLIからヘッドレス実行できます。Apidog CLIはNodeが動くCI環境で実行できるため、UIで作成したテストも自動化パイプラインに組み込めます。

Top comments (0)