まるで平易な英語のように読め、コードの隣にあるGitに存在し、あらゆるCIパイプラインで実行できるAPIテストを望んでいませんか？Karateはまさにそのために作られました。Karateはドメイン固有言語（DSL）を使用するため、JavaメソッドではなくGiven / When / Thenステップとしてテストを記述します。このガイドでは、Karateとは何か、そのフィーチャーファイルの仕組み、そして実行可能なサンプルについて説明します。
Karateとは
Karateは、API向けのオープンソースのJavaベーステスト自動化フレームワークです。各テストは、ビヘイビア駆動開発（BDD）に由来する同じGiven/When/Then構造であるGherkinを使用して、.featureファイル内のシナリオとして記述します。Cucumberのようなツールとの違いは、ステップ定義のグルーコードを記述する必要がないことです。KarateにはHTTPステップ、アサーション、JSON処理が組み込まれているため、機能するAPIテストにはJavaが一切不要です。
このプロジェクトはAPIテスト以上のものをバンドルしています。リポジトリには、モック、パフォーマンステスト（Gatling経由）、UI自動化用のモジュールが含まれています。このガイドでは、ほとんどのチームがまず最初に利用するAPIテストのコアに焦点を当てています。
テストはプレーンテキストファイルであるため、バージョン管理が容易です。プルリクエストの差分を見れば、どのアサーションが変更されたかが正確に分かります。これはコードレビューやGitネイティブのコードベースのワークフローと相性が良いです。
Given/When/Thenスタイルが初めての方は、ビヘイビア駆動開発に関する入門記事で、その起源とチームがそれを使用する理由について説明しています。
仕組み：フィーチャーファイルとkarate-config.js
Karateテストはフィーチャーファイルから始まります。各ファイルには1つのFeature:と1つ以上のScenario:ブロックがあります。シナリオ内では、Givenでリクエストを設定し、Whenで実行し、Thenでアサートします。
Karate自身のクイックスタートが示す構造は次のとおりです。
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]'
上から下へ読んでください。urlはベースアドレスを設定します。pathはリソースを追加します。method getはリクエストを送信します。status 200はHTTPコードをチェックします。最後の行は、レスポンスがちょうど10個のアイテムを持つJSON配列であることをアサートします。#[10]はKarateマーカーであり、JavaScriptではありません。これらのマーカーの詳細については、アサーションのセクションで説明します。
ここでのGherkinは標準的なGiven/When/Thenです。その構文自体をより深く理解したい場合は、BDDとAPIテストのためのGherkinガイドをご覧ください。
ほとんどのプロジェクトでは、開発環境のベース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;
}
karate.envは、実行時に渡すシステムプロパティから取得されます。単一のフィーチャーファイルを変更することなく環境を切り替えることができます。シナリオでは、アドレスをハードコーディングする代わりにGiven url baseUrlと記述します。
サンプルシナリオ
リクエストボディを持つものを記述してみましょう。このシナリオはユーザーを作成し、ステータスをチェックし、レスポンスの形状を検証します。
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'
いくつか注目すべき点があります。Background:ブロックはファイル内の各シナリオの前に実行されるため、ベースURLを一度設定します。*はワイルドカードステップであり、Karateは*をGiven、When、Thenと同じように扱います。これにより、文法を気にすることなくセットアップステップを記述できます。requestキーワードはJSONペイロードを直接受け取ります。シリアライザーもPOJOも不要です。また、#stringはidフィールドが存在し、特定の値に固定することなく文字列であることをアサートするファジーマッチャーです。
アサーションとJSONマッチング
アサーションこそがKarateの真骨頂です。コアキーワードはmatchです。これは実際値と期待値を比較し、不一致があった場合にテストを失敗させます。
完全一致は等価性をチェックします。
And match response == { id: '#number', name: 'Ada', job: 'engineer' }
#number、#string、#boolean、#uuidトークンはファジーマッチャーです。これらはリテラル値を要求することなく型と存在をアサートするため、サーバーが生成されたIDやタイムスタンプを返す場合にテストの安定性を保ちます。
フィールドのサブセットのみを気にする場合は、containsを使用します。
And match response contains { name: 'Ada' }
これは、レスポンスに他の10個のフィールドがあったとしても、nameがAdaと等しい限り合格します。Karateは、部分的なマッチングをより細かく制御するために、!contains、contains only、contains any、contains deepもサポートしています。
配列も検証できます。match response == '#[10]'は長さ10の配列をアサートします。eachを使用すると、すべての要素にスキーマを適用できます。
And match each response == { id: '#number', name: '#string' }
この1行は、配列内のすべてのオブジェクトが数値のidと文字列のnameを持っていることをチェックします。このような形状の検証は、汎用テストフレームワークではループと複数のアサーションが必要になります。レスポンス検証の全体像を知りたい場合は、APIアサーションに関する実践ガイドで、ツール全体のパターンが説明されています。
データ駆動テストとCI
実際のテストスイートは、多くの入力に対して同じロジックを実行します。Karateはこれを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 |
これはシナリオを3回、1行につき1回実行します。インラインテーブルの代わりに外部ファイルから行を読み取ることもでき、これにより大規模なデータセットをフィーチャーファイルから除外できます。
Examples:
| read('classpath:test-data/users.json') |
KarateはこのようにJSONファイルとCSVファイルを読み取るため、テストデータはチームが管理しやすい場所に置くことができます。
継続的インテグレーションには、2つの方法があります。MavenまたはGradleプロジェクトでは、KarateはJUnit 5を介して実行されます。karate-junit5依存関係を追加し、ランナーをフィーチャーファイルに指定すると、mvn testが他の単体テストと同じようにこれらを実行します。これは、既存のCIステップに特別なツールが不要であることを意味します。
2つ目の方法は、ビルドツールを必要としないスタンドアロンjarです。プロジェクトのリリースからkarate.jarをダウンロードし、フィーチャーファイルを直接実行します。このjarは最新のJavaバージョンを必要とするため、最小要件についてはリリースノートを確認してください。
java -jar karate.jar src/test/java/features
タグでフィルタリングしたり、並行して実行したり、出力ディレクトリを選択したりできます。
java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
システムプロパティで環境を渡すことができ、これはkarate-config.js内のkarate.envに流れ込みます。
java -jar karate.jar -Dkarate.env=qa src/test/java/features
Karateは、各実行後にHTMLレポートを出力ディレクトリに書き込むため、パイプラインアーティファクトで障害を簡単に検査できます。より広範なCIの全体像については、CI/CDでAPIテストを自動化する方法をご覧ください。
長所とトレードオフ
Karateには明確な長所があります。テストは平易な英語に近い形で読めるため、Javaに精通していない人にとっての障壁が低くなります。ファジーマッチャーやeachを含む組み込みのJSONマッチングは、多くのアサーションの定型コードを不要にします。すべてがGit下のテキストファイルに存在するため、テストはソースコードのようにレビューや差分比較が可能です。また、HTTP以上のものをカバーしているため、チームは後でツールを切り替えることなくモックやパフォーマンステストを追加できます。
トレードオフも存在します。KarateはJVM上で動作するため、基本的なこと以上のことを行うにはJavaのインストールとJVMエコシステムへの習熟度が必要です。DSLはそれ自体が学習対象です。構文は読みやすいですが、正しいマッチャーや再利用パターンを記述するには練習が必要です。再利用可能なロジック、カスタムヘルパー、複雑なセットアップは、しばしばJavaScript関数やJavaインターオップへと引き戻されます。また、テストはコードであるため、チームの非開発者は通常、助けなしにはそれらを作成または編集できません。
これらはKarateの欠点ではありません。これはコードファーストなフレームワークの特性です。問題は、その特性があなたのチームがどのように作業したいかに合致するかどうかです。
Karate vs コード不要のアプローチ（Apidog）
KarateはコードベースでGitネイティブです。フィーチャーファイルを記述し、コミットし、ビルドツールまたはjarから実行します。これは、アプリケーションの隣にあるバージョン管理下にテストを置き、JVMに慣れているエンジニアに適しています。
Apidogは、同じ目標に対し視覚的でコード不要のアプローチを採用しています。UIでテストシナリオを構築し、リクエストを連結し、DSLを記述するのではなくクリックでアサーションを追加します。APIライフサイクル全体（設計、デバッグ、モック、ドキュメント）が1箇所に集約されているため、テストはすでに定義したエンドポイントとスキーマを再利用できます。これにより、Javaプロジェクトを管理したくないQAエンジニアやプロダクト担当者にとっての障壁が低くなります。
視覚的なスイートはUIに縛られることはありません。ApidogはApidog CLIを通じてCIでヘッドレスに実行されるため、コード不要のスイートであっても自動化されたパイプラインに適合します。Nodeでインストールします。
npm install -g apidog-cli
次に、保存されたシナリオまたはスイートをIDでトリガーし、環境を指定し、レポート形式を選択します。
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,json,junit
-tフラグはシナリオ、フォルダ、またはスイートをターゲットとし、-eは環境を選択し、-rは1つ以上のレポーター（cli、html、json、junit）を選択します。データ駆動型実行の場合、-d（または--iteration-data）はデータファイルのパスまたはテストデータIDを取ります。CLIはヘッドレスで、Nodeを実行できる任意のCIステップで動作します。保存されたApidogシナリオを実行するものであり、インタラクティブなリクエスト送信者やロードジェネレーターではありません。CI/CDのためのApidog CLIで完全なチュートリアルを、Apidog CLI vs Newmanで別のランナーとの比較をご覧ください。
どちらのアプローチも、CIでヘッドレスに実行される自動化されたAPIテストを生成します。違いは作成スタイルにあります。KarateはGitでDSLを記述することを求めますが、ApidogはパイプラインにもエクスポートできるUIでのクリック操作を求めます。
選択方法
チームに開発者が多く、JVMに慣れており、アプリケーションのすぐ隣でコードとしてバージョン管理されたテストを望む場合はKarateを選択してください。プレーンテキストのフィーチャーファイルと組み込みのJSONマッチングは、エンジニアがテストスイートをエンドツーエンドで所有する場合に効果を発揮します。
作成者にQAやプロダクト担当者が含まれる場合、既存の設計およびドキュメントワークフローにテストを連携させたい場合、またはAPIチェックを実行するためにJavaビルドを維持したくない場合は、Apidogのようなコード不要のツールを選択してください。CLIを通じてCIカバレッジも引き続き得られます。
一部のチームは両方を運用しています。コードで所有する深いリグレッションスイートにはKarateを、非開発者も拡張できる広範で迅速なカバレッジには視覚ツールを使用します。まだ選択肢を検討している場合は、API自動化テストフレームワークの選択方法の概要で決定基準が説明されています。
よくある質問
Karateを使用するためにJavaを知る必要がありますか？ いいえ、基本的なAPIテストを記述するためには必要ありません。フィーチャーファイルはGherkin DSLを使用し、KarateにはHTTPとアサーションのステップが組み込まれています。テストを実行するにはJavaをインストールしておく必要がありますが、カスタムヘルパーや複雑な再利用が必要になった場合には、ある程度のJavaまたはJavaScriptの知識が役立ちます。
KarateはCucumberとどう違いますか？ どちらもGherkinのGiven/When/Then構文を使用します。Cucumberでは、各ステップをサポートするためにステップ定義コードを記述します。KarateはAPIテストステップをあらかじめ提供するため、標準的なHTTPテストのために維持するグルーコードはありません。
KarateはMavenやGradleなしで実行できますか？ はい。プロジェクトのリリースからスタンドアロンのkarate.jarをダウンロードし、java -jar karate.jar <path>でフィーチャーファイルを直接実行できます。ビルドツールなしでタグ、並行スレッド、カスタム出力ディレクトリをサポートしています。
#stringや#[10]という構文は何を意味しますか？ それらはKarateのファジーマッチャーです。#stringはフィールドが任意の文字列であることをアサートし、#numberは数値であることを、#[10]は長さ10のJSON配列であることをアサートします。これにより、生成された値をハードコーディングすることなくレスポンスの形状を検証できます。
コード不要のAPIテストはCIでも実行できますか？ はい。Apidogのような視覚ツールは、保存されたシナリオをApidog CLIにエクスポートします。Apidog CLIはヘッドレスであり、Nodeが実行できる任意のCIステップで動作します。したがって、UIでテストを作成しても、自動化されたパイプライン実行を得ることができます。