Hurlの使い方完全ガイド【インストールから応用まで】
APIのテストや開発において、HTTPリクエストの確認は避けて通れません。あなたは日々、curlコマンドを複雑に組み合わせてリクエストを送信したり、PostmanやInsomniaのようなGUIツールで手動テストを繰り返したりしていませんか?
これらの方法は、時には時間を浪費し、テストの再現性を損なうことがあります。特に、複数のリクエストを連続して実行するシナリオや、レスポンスの内容を厳密に検証する回帰テストでは、手作業の限界を感じる場面も多いでしょう。
しかし、もし、これらの手間を劇的に削減し、シンプルかつ高速にHTTPリクエストの実行とテストを自動化できるツールがあったらどうでしょうか?
本記事では、そんな課題を解決する強力なコマンドラインツール「Hurl」を徹底的に解説します。Hurlを導入することで、あなたはテキストファイル一つでHTTPセッションを定義し、APIの動作確認から本格的なテストまでを効率的に行えるようになります。
Hurlとは — 30秒で分かる概要・誕生した背景
Hurlは、シンプルなテキストファイルを使ってHTTPリクエストを定義・実行・テストするためのコマンドラインツールです。Rustで書かれており、そのHTTPエンジンは信頼性の高いlibcurlによって動いています。
Hurlの最大の特徴は、HTTPリクエストとレスポンスのアサート(検証)を、非常に読みやすいプレーンテキスト形式で記述できる点です。これにより、開発者は複雑なスクリプトを書くことなく、APIの動作確認やテストを高速に実行できます。
例えば、以下のようなシナリオを考えてみましょう。
- ログインAPIにリクエストを送り、認証トークンをキャプチャする。
- キャプチャしたトークンを使い、保護されたAPIにアクセスする。
- レスポンスのHTTPステータスコードやJSONボディが期待通りであることを検証する。
Hurlは、このような一連のHTTPセッションを、一つの.hurlファイル内に記述できます。
Hurlが誕生した背景
Hurlは、既存のcurlコマンドの強力さを維持しつつ、より宣言的でテストに適した形式を提供するために生まれました。curlは非常に柔軟ですが、複数のリクエストを連結したり、レスポンスを検証したりするには、シェルスクリプトや他のツールとの組み合わせが必要でした。
Hurlは、これらの課題を解決し、APIの動作確認やCI/CDパイプラインでの自動テストを容易にすることを目的としています。開発者はHurlを使うことで、HTTPリクエストの記述、実行、テスト、そして結果のレポート作成までを一貫して行えるのです。
インストール方法 — OS別コマンド
Hurlのインストールは非常に簡単です。公式サイトからバイナリをダウンロードするか、各OSのパッケージマネージャー、またはRustのパッケージマネージャーcargoを使ってインストールできます。
macOS / Linux の場合
macOSではHomebrew、Linuxではcargoまたはバイナリダウンロードが一般的です。
Homebrew (macOS)
Homebrewを使っている場合、以下のコマンドでHurlをインストールできます。
brew install hurl
Cargo (macOS / Linux 共通)
Rustがインストールされている環境であれば、cargoコマンドを使ってHurlをインストールできます。
cargo install hurl
バイナリのダウンロード (macOS / Linux 共通)
GitHubのリリースページから、お使いのOSとアーキテクチャに合ったバイナリをダウンロードし、PATHの通ったディレクトリに配置することも可能です。
- HurlのGitHubリリースページにアクセスします。 https://github.com/Orange-OpenSource/hurl/releases
- 最新バージョンのアセットから、
hurl-x.x.x-x86_64-apple-darwin.tar.gz(macOS) やhurl-x.x.x-x86_64-unknown-linux-gnu.tar.gz(Linux) などをダウンロードします。 - ダウンロードしたファイルを解凍し、
hurl実行ファイルを/usr/local/binなどのPATHが通っているディレクトリに移動させます。
# 例: Linuxの場合
wget https://github.com/Orange-OpenSource/hurl/releases/download/x.x.x/hurl-x.x.x-x86_64-unknown-linux-gnu.tar.gz # x.x.x はバージョン番号
tar -xzf hurl-x.x.x-x86_64-unknown-linux-gnu.tar.gz
sudo mv hurl-x.x.x-x86_64-unknown-linux-gnu/bin/hurl /usr/local/bin/
Windows の場合
Windowsでは、WSL2(Windows Subsystem for Linux 2)を使うか、cargo、またはバイナリをダウンロードしてインストールできます。
WSL2 を利用する
WSL2が有効になっている場合、Linuxのインストール方法と同様にHomebrewやCargoを使ってHurlをインストールできます。これが最も推奨される方法です。
Cargo (Windows)
Rustがインストールされている環境であれば、cargoコマンドを使ってHurlをインストールできます。
cargo install hurl
バイナリのダウンロード (Windows)
GitHubのリリースページから、お使いのWindows環境に合ったバイナリをダウンロードし、PATHの通ったディレクトリに配置します。
- HurlのGitHubリリースページにアクセスします。 https://github.com/Orange-OpenSource/hurl/releases
- 最新バージョンのアセットから、
hurl-x.x.x-x86_64-pc-windows-msvc.zipなどをダウンロードします。 - ダウンロードしたファイルを解凍し、
hurl.exeをCドライブのProgram FilesなどのPATHが通っているディレクトリに移動させます。
インストール確認
インストールが完了したら、以下のコマンドでバージョンを確認してみましょう。
hurl --version
バージョン情報が表示されれば、Hurlのインストールは成功です。
基本的な使い方 — 最低限これだけ知れば使えるコマンド3〜5個
Hurlは、.hurlという拡張子のテキストファイルにHTTPリクエストを記述し、それを実行することで動作します。ここでは、Hurlの基本的な使い方をステップバイステップで見ていきましょう。
1. シンプルなGETリクエストを実行する
まず、hello.hurlというファイルを作成し、以下の内容を記述します。
# hello.hurl
GET https://example.com
このファイルは、https://example.comに対してGETリクエストを送ることを定義しています。
次に、このHurlファイルを実行します。
hurl hello.hurl
Hurlは指定されたURLにリクエストを送信し、レスポンスの内容を標準出力に表示します。デフォルトでは、レスポンスのステータスコード、ヘッダー、ボディが出力されます。
2. HTTPステータスコードを検証する
APIテストにおいて、レスポンスのHTTPステータスコードは非常に重要です。Hurlでは、HTTPキーワードを使ってステータスコードを簡単にアサート(検証)できます。
get_status.hurlというファイルを作成し、以下の内容を記述してください。
# get_status.hurl
GET https://httpbin.org/status/200
HTTP 200
このHurlファイルは、https://httpbin.org/status/200にGETリクエストを送り、レスポンスのステータスコードが200であることをアサートします。
実行してみましょう。
hurl get_status.hurl
ステータスコードが200であれば、テストは成功し、Hurlは正常終了します。もしHTTP 200をHTTP 404などに変更して実行すると、アサートが失敗し、Hurlはエラーを報告します。
3. JSONレスポンスの値を検証する
REST APIではJSON形式のレスポンスが一般的です。Hurlは、JSONPathを使ってJSONボディの特定の値や構造を検証できます。
get_json.hurlというファイルを作成し、以下の内容を記述します。ここではhttps://httpbin.org/jsonという、ダミーのJSONレスポンスを返すサービスを利用します。
# get_json.hurl
GET https://httpbin.org/json
HTTP 200
[Asserts]
jsonpath "$.slideshow.author" == "Yours Truly"
jsonpath "$.slideshow.title" == "Sample Slide Show"
jsonpath "$.slideshow.slides" count == 2
[Asserts]セクションで、複数の検証ルールを定義しています。
jsonpath "$.slideshow.author" == "Yours Truly":slideshowオブジェクトのauthorプロパティが"Yours Truly"であるかを検証します。jsonpath "$.slideshow.title" == "Sample Slide Show":slideshowオブジェクトのtitleプロパティが"Sample Slide Show"であるかを検証します。jsonpath "$.slideshow.slides" count == 2:slideshowオブジェクトのslides配列の要素数が2であるかを検証します。
実行コマンドはこれまでと同じです。
hurl get_json.hurl
これらのアサートがすべて成功すれば、テストはパスします。JSONPathは、複雑なJSON構造から必要な情報を抽出・検証するのに非常に強力です。
4. リクエストヘッダーとPOSTリクエストを送信する
Hurlでは、リクエストヘッダーの追加や、POSTリクエストのボディ送信も簡単です。
post_data.hurlというファイルを作成し、以下の内容を記述します。
# post_data.hurl
POST https://httpbin.org/post
Content-Type: application/json
X-Custom-Header: Hurl-Test-Value
{
"name": "Hurl User",
"email": "hurl@example.com"
}
HTTP 200
[Asserts]
jsonpath "$.headers.Content-Type" == "application/json"
jsonpath "$.headers.X-Custom-Header" == "Hurl-Test-Value"
jsonpath "$.json.name" == "Hurl User"
このHurlファイルでは、以下の処理を行っています。
POST https://httpbin.org/post: POSTリクエストをhttps://httpbin.org/postに送信します。Content-Type: application/json: リクエストヘッダーにContent-Typeを追加しています。X-Custom-Header: Hurl-Test-Value: カスタムヘッダーX-Custom-Headerを追加しています。- JSON形式のボディ:
{ "name": "Hurl User", "email": "hurl@example.com" }をリクエストボディとして送信します。 HTTP 200: ステータスコードが200であることをアサートします。[Asserts]セクション: レスポンスボディ(httpbin.org/postは送られたリクエスト情報をJSONで返す)から、送信したヘッダーやJSONボディが正しく受け取られたかを検証しています。
実行してみましょう。
hurl post_data.hurl
このように、Hurlはリクエストヘッダーの指定や様々なリクエストボディの送信、そしてそれらの検証を直感的に行えます。
便利な使い方・応用例 3選 — 実際の開発シーンに落とし込む
Hurlの真価は、単一のリクエスト実行だけでなく、より複雑なシナリオを扱う能力にあります。ここでは、実際の開発シーンで役立つ応用例を3つ紹介します。
1. リクエストの連鎖と値のキャプチャ
多くのAPIでは、認証やセッション管理のために、前のリクエストのレスポンスから値(トークンなど)を抽出し、次のリクエストで使用する必要があります。Hurlの[Captures]機能を使うと、このプロセスを簡単に行えます。
例えば、ユーザーログインAPIで認証トークンを取得し、そのトークンを使って保護されたリソースにアクセスするシナリオを考えてみましょう。
auth_flow.hurlというファイルを作成します。
# auth_flow.hurl
# 1. ログインAPIにリクエストを送信し、認証トークンをキャプチャする
POST https://api.example.com/login
Content-Type: application/json
{
"username": "testuser",
"password": "password123"
}
HTTP 200
[Captures]
auth_token: jsonpath "$.token" # レスポンスのJSONから`token`の値をキャプチャし、`auth_token`変数に格納
# 2. キャプチャしたトークンをAuthorizationヘッダーに含めて、保護されたAPIにアクセスする
GET https://api.example.com/data/protected
Authorization: Bearer {{auth_token}} # キャプチャした`auth_token`変数をここで利用
HTTP 200
[Asserts]
jsonpath "$.message" == "Protected data accessed successfully."
このHurlファイルでは、以下の手順が実行されます。
- 最初のPOSTリクエストで、
https://api.example.com/loginにユーザー名とパスワードを送信します。 - レスポンスが
HTTP 200であることを確認後、[Captures]セクションでjsonpath "$.token"を使って、レスポンスJSONのtokenプロパティの値をauth_tokenという変数に格納します。 - 2つ目のGETリクエストでは、
Authorization: Bearer {{auth_token}}というヘッダーを追加しています。ここで{{auth_token}}のように二重波括弧を使うことで、前のリクエストでキャプチャした変数の値を参照しています。 - 保護されたAPIからのレスポンスが
HTTP 200であり、特定のメッセージが含まれていることを検証します。
このように、Hurlは複数のリクエストを連結し、動的な値を受け渡すことで、実際のユーザー操作に近いAPIフローをテストできます。
2. パフォーマンス計測とテスト
Hurlは、単なる機能テストだけでなく、APIのパフォーマンスを計測し、特定のリクエストが許容される時間内に完了するかをテストする用途にも使えます。durationアサートを使用することで、レスポンスタイムの検証が可能です。
performance_test.hurlというファイルを作成します。
# performance_test.hurl
GET https://api.example.com/products # 負荷がかかる可能性のあるエンドポイント
HTTP 200
[Asserts]
duration < 500 # レスポンス時間が500ミリ秒未満であることをアサート
このHurlファイルでは、https://api.example.com/productsというエンドポイントにGETリクエストを送信し、レスポンスのステータスコードが200であることを確認します。さらに、duration < 500というアサートにより、リクエストの完了までにかかった時間が500ミリ秒(0.5秒)未満であることを検証しています。
このテストを実行すると、もしAPIの応答が遅すぎた場合、Hurlはエラーを報告します。これは、CI/CDパイプラインに組み込むことで、APIのパフォーマンス劣化を早期に検知するために非常に有用です。
Hurlには、テスト結果をJUnit、TAP、HTML形式で出力するオプションもあります。例えば、JUnit形式でレポートを出力するには、--report-junitオプションを使用します。
hurl --test --report-junit report.xml performance_test.hurl
--testオプションは、Hurlファイルをテストとして実行し、結果をレポートに含めるよう指示します。--report-junit report.xmlは、JUnit形式のレポートをreport.xmlというファイルに出力します。
3. GraphQL APIのテスト
Hurlは、REST APIだけでなく、GraphQL APIのテストにも対応しています。GraphQLクエリをHurlファイル内に直接記述し、JSONPathでレスポンスを検証できます。
graphql_query.hurlというファイルを作成します。
# graphql_query.hurl
POST https://api.example.com/graphql
Content-Type: application/json
```graphql
query GetUserById($id: ID!) {
user(id: $id) {
name
email
}
}
{ "operationName": "GetUserById", "variables": { "id": "123" } } HTTP 200 [Asserts] jsonpath "$.data.user.name" == "Alice" jsonpath "$.data.user.email" matches /@example.com$/ # メールアドレスのドメインを正規表現で検証
このHurlファイルでは、以下の処理を行っています。
1. `POST https://api.example.com/graphql`: GraphQLエンドポイントにPOSTリクエストを送信します。
2. `Content-Type: application/json`: GraphQLリクエストの標準的な`Content-Type`を指定します。
3. ````graphql ... `````ブロック: ここにGraphQLクエリを直接記述します。HurlはこれをGraphQLクエリとして認識し、JSONボディの一部として送信します。
4. 続くJSONブロック: GraphQLリクエストの`operationName`や`variables`といったメタデータを定義します。
5. `HTTP 200`: ステータスコードが`200`であることをアサートします。
6. `[Asserts]`セクション: レスポンスのJSONボディから、`data.user.name`が`"Alice"`であることや、`data.user.email`が特定の正規表現にマッチすることなどを検証します。
Hurlのこの機能により、GraphQL APIの動作確認や回帰テストも、他のAPIと同様にシンプルかつ一貫した方法で実施できます。
## 他ツールとの組み合わせ — 相性のよいツールと組み合わせ方
Hurlは単体でも強力ですが、他の開発ツールと組み合わせることで、その真価をさらに発揮します。
### 1. CI/CDツール (GitHub Actions, GitLab CI/CD, Jenkinsなど)
HurlはCI/CDパイプラインに組み込むのに非常に適しています。Hurlファイルはテキストベースであるため、Gitなどのバージョン管理システムで管理しやすく、変更履歴も追跡しやすいです。
CI/CDパイプラインにHurlテストを組み込むことで、コードがコミットされるたび、またはデプロイ前に自動的にAPIテストを実行できます。これにより、APIの回帰バグを早期に発見し、開発プロセス全体の品質を向上させることが可能です。
Hurlは、JUnit、TAP、HTML形式のテストレポートを生成できます。これらのレポートは、CI/CDツールと統合し、テスト結果の可視化や通知に活用できます。
**GitHub Actionsでの利用例:**
```yaml
# .github/workflows/api-test.yml
name: API Tests with Hurl
on: [push, pull_request]
jobs:
hurl_api_test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Hurl
run: curl -sL https://raw.githubusercontent.com/Orange-OpenSource/hurl/master/install.sh | bash
- name: Run Hurl Tests
run: hurl --test --report-junit hurl-report.xml tests/*.hurl # testsディレクトリ内の全ての.hurlファイルを実行
- name: Upload Test Report
uses: actions/upload-artifact@v4
if: always() # テストが失敗してもレポートをアップロード
with:
name: hurl-test-report
path: hurl-report.xml
このGitHub Actionsのワークフローでは、以下の処理が行われます。
actions/checkoutでリポジトリのコードをチェックアウトします。Install HurlステップでHurlをインストールします(install.shスクリプトを利用)。Run Hurl Testsステップで、tests/ディレクトリ内のすべての.hurlファイルをテストとして実行し、hurl-report.xmlというJUnit形式のレポートを生成します。Upload Test Reportステップで、生成されたレポートをアーティファクトとしてアップロードします。これにより、CI/CDの実行結果画面からレポートをダウンロード・確認できます。
2. バージョン管理システム (Git)
Hurlファイルはプレーンテキストであるため、Gitなどのバージョン管理システムとの相性が抜群です。テストケースの変更履歴を追跡したり、ブランチ間でテストケースをマージしたりすることが容易になります。
APIの仕様変更に合わせてテストケースを更新する際も、コードレビューを通じて変更内容を確認できるため、チーム開発における品質管理にも貢献します。
3. コンテナ技術 (Docker)
Hurlは単一のバイナリとして提供されるため、Dockerコンテナ内で実行するのも非常に簡単です。HurlをDockerイメージに含めることで、テスト環境の構築を標準化し、環境依存の問題を排除できます。
例えば、Dockerfileを作成してHurlを含むイメージをビルドし、そのイメージを使ってCI/CDパイプラインでテストを実行することが可能です。
# Dockerfile
FROM alpine:latest
WORKDIR /app
# Hurlのダウンロードとインストール
RUN apk add --no-cache curl && \
curl -sL https://raw.githubusercontent.com/Orange-OpenSource/hurl/master/install.sh | bash
# Hurlの実行ファイルをPATHに追加 (もしinstall.shがPATHに追加しない場合)
ENV PATH="/root/.cargo/bin:$PATH"
# Hurlファイルをコンテナにコピー
COPY . .
# Hurlテストを実行するコマンド (エントリポイントやCMDとして設定)
CMD ["hurl", "--test", "--report-junit", "hurl-report.xml", "tests/*.hurl"]
このDockerfileを使えば、どこでも同じ環境でHurlテストを実行できるようになります。
よくある設定・カスタマイズ — dotfilesや設定ファイルの例
Hurl自体には、~/.hurlrcのような専用のグローバル設定ファイルはありません。しかし、コマンドラインオプションや環境変数、そしてHurlファイル内の記述によって、実行時の挙動を柔軟にカスタマイズできます。
1. コマンドラインオプションによるカスタマイズ
Hurlは多くのコマンドラインオプションを提供しており、実行時に動的に設定を変更できます。
変数の定義 (--variable)
Hurlファイル内で使用する変数を、コマンドラインから渡すことができます。これにより、環境ごとに異なる値(APIキー、ベースURLなど)をHurlファイルにハードコードせずに利用できます。
config_test.hurlというファイルを作成します。
# config_test.hurl
GET {{base_url}}/status/200
HTTP 200
このHurlファイルでは、{{base_url}}という変数が使われています。これをコマンドラインから渡します。
hurl --variable base_url=https://httpbin.org config_test.hurl
これにより、Hurlはhttps://httpbin.org/status/200にリクエストを送信します。
プロキシ設定 (--proxy)
特定のプロキシサーバーを経由してリクエストを送信したい場合、--proxyオプションを使用します。
hurl --proxy http://localhost:8080 my_request.hurl
タイムアウト設定 (--connect-timeout, --timeout)
接続タイムアウトやリクエスト全体のタイムアウトを設定できます。
# 接続タイムアウトを5秒、リクエスト全体のタイムアウトを30秒に設定
hurl --connect-timeout 5 --timeout 30 my_request.hurl
詳細な出力 (--verbose, --very-verbose)
デバッグ時など、より詳細な情報(リクエストヘッダー、レスポンスヘッダーなど)を確認したい場合は、--verboseや--very-verboseオプションを使用します。
hurl --verbose my_request.hurl
2. 環境変数によるカスタマイズ
一部のHurlの挙動は、環境変数によっても制御できます。例えば、CURL_CA_BUNDLE環境変数を設定することで、カスタムのCA証明書バンドルを使用できます。これは、自己署名証明書を使用している内部APIなどをテストする際に役立ちます。
# 環境変数を設定してHurlを実行
CURL_CA_BUNDLE=/path/to/my/custom-ca-bundle.pem hurl my_secure_request.hurl
3. Hurlファイル内での設定
Hurlファイル内でも、[Options]セクションを使って一部の設定を定義できます。例えば、リクエストのタイムアウトやリダイレクトの挙動などを指定できます。
# options_example.hurl
[Options]
timeout: 10 # このリクエストのタイムアウトを10秒に設定
follow-redirect: false # リダイレクトを自動的に追跡しない
GET https://example.com/redirect
HTTP 302 # リダイレクトを追跡しないので302をアサート
この例では、timeoutを10秒に、follow-redirectをfalseに設定しています。follow-redirect: falseとすることで、リダイレクトが発生してもHurlは自動的に新しいURLにリクエストを送りません。その結果、リダイレクトのステータスコード(例: 302 Found)を直接検証できます。
これらのカスタマイズ方法を組み合わせることで、様々なテストシナリオや環境に対応できる柔軟なHurlテストを作成できます。
今日からできる実行プラン — 3ステップで始める
Hurlをあなたの開発ワークフローに組み込むための、簡単な3ステップをご紹介します。
ステップ1: Hurlをインストールする
まずは、お使いのOSにHurlをインストールしましょう。本記事の「インストール方法」セクションを参考に、最も手軽な方法を選んでください。
例えば、macOSユーザーであれば、以下のコマンドを実行するだけです。
brew install hurl
インストール後、hurl --versionを実行して、Hurlが正しくインストールされているかを確認してください。
ステップ2: シンプルなGETリクエストを試す
Hurlの基本を体験するために、first_request.hurlというファイルを作成し、以下の内容を記述してみましょう。
# first_request.hurl
GET https://httpbin.org/get
HTTP 200
[Asserts]
jsonpath "$.headers.Host" == "httpbin.org"
このファイルは、https://httpbin.org/getにGETリクエストを送信し、ステータスコードが200であることをアサートします。さらに、レスポンスのJSONボディに含まれるheaders.Hostがhttpbin.orgであることを検証します。
このHurlファイルを実行してください。
hurl first_request.hurl
Hurlがリクエストを正常に実行し、アサートがすべてパスすることを確認しましょう。これにより、Hurlの基本的な動作とアサートの仕組みを理解できます。
ステップ3: 既存のAPIエンドポイントでテストケースを作成する
次に、あなたが現在開発している、または利用しているAPIのいずれかのエンドポイントを使って、Hurlテストを作成してみましょう。
例えば、ユーザー情報取得APIがある場合、以下のようなuser_api.hurlファイルを作成できます。
# user_api.hurl
GET https://your-api.com/users/123
Authorization: Bearer YOUR_AUTH_TOKEN # 必要であれば認証トークンを追加
HTTP 200
[Asserts]
jsonpath "$.id" == 123
jsonpath "$.name" == "John Doe"
jsonpath "$.email" matches /@your-api.com$/
https://your-api.comやYOUR_AUTH_TOKENの部分は、あなたのAPIに合わせて置き換えてください。
このテストを実行し、APIが期待通りに動作していることをHurlで検証してみましょう。もしエラーが発生した場合は、Hurlの出力を見て、どの部分でアサートが失敗したかを確認し、HurlファイルやAPIの実装を修正してください。
この3ステップを実践することで、Hurlの基本的な使い方をマスターし、あなたのAPI開発・テストプロセスにHurlを組み込む第一歩を踏み出せるはずです。
Hurlは、そのシンプルさと強力な機能により、API開発者の強力な味方となるでしょう。ぜひ今日からHurlを活用し、より効率的で信頼性の高いAPIテストを実現してください。
参考文献
- Hurl 公式ドキュメント
- Hurl GitHubリポジトリ
- Testing HTTP APIs with Hurl - GitHub Discussions
- Hurl: A Command Line Tool for Testing HTTP Requests - Blog Post by Denis-G
- httpbin.org - HTTP Request & Response Service