Apidogを使用してAPIテストを行う際、APIパラメータの値を固定せず、毎回手動でデータを変更するのも避けたい場合があります。そんなとき、パラメータの値が自動的に変化し、実際のシナリオのデータ要件に合致することを希望するでしょう。たとえば、ランダムに生成される数値、文字列、タイムスタンプ、あるいは境界値のデータが必要になる場合があります。
このようにデータを動的に生成する必要があるシーンでは、Apidogの「動的値」機能を活用できます。これは、APIパラメータに対して、列挙値、オフセット時間、住所、など、様々なタイプのデータを動的に生成します。簡単なビジュアル操作を通じて、数回のクリックで必要なデータタイプを挿入でき、スクリプトを一切書く必要はありません。
この記事では、実際のシナリオを交えて、Apidogでの「動的値」の使用方法を詳しく紹介します。始める前に、Apidogが最新バージョンに更新されていることを確認してください。
動的値の使用方法は?
RequestパラメータやRequestボディには、「魔法の杖」アイコンに似たものがあります。それをクリックすると、必要な動的値を選択できます。
動的値の文法はどのようになっていますか?
Apidogの新バージョンの動的値はFaker.jsに基づいており、文法が調整されています。基本的な構成は以下の通りです:
{{$動的値型}}
{{$ が動的値の開始を示す識別子で、その後に続くのがFaker.jsの具体的な生成関数です。ただし、fakerというプレフィックスは省略されています。例えば、人名を生成するための表現は次のように書きます:
- Faker.js: faker.person.fullName()
- Apidog: {{$person.fullName}}
「魔棒」アイコンをクリックすることで動的値を選択することもできますし、{{$ を手動で入力することでオートコンプリートをトリガーし、適切な動的値を選ぶこともできます。
旧バージョンの動的値は {% mock 'name' %} という形式を使用していますが、この構文形式は現在も互換性があります。ただし、今後徐々に廃止される予定です。Apidogを最新バージョンにアップグレードして、新バージョンの構文構造を使用することをお勧めします。旧バージョンと比べ、新しいバージョンの方がよりクリアで分かりやすいです。
新しいバージョンのApidog動的値機能で追加された主なデータタイプは以下の通りです:
- 日付/時間:多様な日付と時間フォーマットを含み、時間オフセットやタイムゾーン処理などの複雑な時間操作を可能にするより強力な時間制御機能。
- 補助関数:正規表現、インクリメント、列挙など、データ生成に使用されるさまざまな処理関数を提供。
- 航空会社:航空会社名やコードを生成するための新しいデータ。
- 動物:動物名や種のMockデータの生成を追加。
- ビジネス:製品カテゴリ、素材、価格など、ビジネス関連の新しいデータ。
- 会社:会社名やスローガンに関連するデータを提供。
- データベース:データベーステーブル名、フィールド名などのデータ生成の追加。
- 金融:クレジットカード番号や金額など、財務関連のデータ生成の追加。
- Git:ブランチ名、コミット情報など、Git関連のデータの追加。
- 音楽:曲名、アーティスト名など、音楽関連データの生成の追加。
- 科学:化学元素や単位記号など、科学関連のデータの追加。
- システム:システムのファイルパス、ファイル名などの関連情報の生成を提供。
- 車両:車両ブランドやメーカーなどの情報生成の追加。
- その他の多く...
一般的な動的値
「動的値」の構文構造を理解した後、ここでは一般的な動的値タイプを詳しく紹介し、実際のRequest例と生成された結果を提供して、動的値をよりよく理解し、応用できるようにします。
ID値
ユーザーや注文などのリソースを作成する際には、通常、UUIDやその他のタイプのID値のように、各リクエストで一意性を確保するためのユニークな識別子が必要です。
Request例:
{
"userId": "{{$string.uuid}}"
}
結果:
{
"userId": "d0491595-e105-4651-9eb9-604b210f8245"
}
各Requestでは、ユーザーIDとしてユニークなUUIDが生成され、データの重複や衝突がないように確保されます。
列挙値
列挙値は、事前に定義された選択肢の中からランダムに値を選択するために使用されます。これは、異なる状態やオプションを正しく処理できるかどうかをテストするのに適しています。
Request例:
{
"status": "{{$helpers.arrayElement(['available','pending','sold'])}}"
}
結果:
{
"status": "sold"
}
各Requestで ['available','pending','sold'] という3つの選択肢からランダムに1つの値が選ばれます。
ブール値
ブール型データをテストする必要があるシナリオでは、例えばユーザー権限の検証のように、true または false 値を動的に生成します。
Request例:
{
"isAdmin": {{$datatype.boolean}}
}
結果:
{
"isAdmin": false
}
ランダムに true または false を生成し、通常は異なる権限のロジックをテストするために使用されます。
現在の時間
API Requestで現在の時間またはタイムスタンプを生成することができ、作成時間やイベント記録など、現在の時間に関連するシーンに適しています。
Request例(現在の時間を生成):
{
"createdTime": "{{$date.now}}"
}
結果:
{
"createdTime": "2024-10-08 13:59:43"
}
Request例(現在のタイムスタンプを生成):
{
"createdTime": "{{$date.timestamp}}"
}
結果:
{
"createdTime": "1728367292"
}
このフィールドは現在のUnixタイムスタンプを生成し、各Requestごとに現在の時間に基づいて動的に変化します。
時間タイプの動的値を使用する際には、タイムゾーンの選択をサポートしています。
デフォルトのタイムゾーンは「(UTC)モンロビア、レイキャビク」であり、「プロジェクト設定 -> Mock設定 -> 時間設定」でデフォルトのタイムゾーンを変更できます。
オフセット時間
現在の時間を生成するだけでなく、現在の時間を基準にしたオフセット時間(例えば、未来の数時間や過去の数日)を生成することもできます。これは、予約時間や注文の有効期限などのシナリオをシミュレーションするのに適しています。
Request例 1:未来1時間の時間を生成
{
"deliveryTime": "{{$date.now|addHours(1)}}"
}
結果:
{
"deliveryTime": "2024-10-14 12:02:07"
}
Request例 2:次の月曜日の日付を生成
{
"nextMonday": "{{$date.now|nextMonday}}"
}
結果:
{
"nextMonday": "2024-10-14 10:41:42"
}
Request例 3:先月の最終日の日付を生成
{
"lastDayOfLastMonth": "{{$date.now|subMonths(1)|endOfMonth}}"
}
- now:現在の日付と時間を示します。
- subMonths(1):現在の時間から1ヶ月前に戻ります。
- endOfMonth:その月の最終日を取得します。
結果:
{
"lastDayOfLastMonth": "2024-09-30 23:59:59"
}
Request例 4:翌月の初日を生成
{
"firstDayNextMonth": "{{$date.now|addMonths(1)|startOfMonth}}"
}
- now:現在の日付と時間を示します。
- addMonths(1):現在の時間から1ヶ月先に進みます。
- startOfMonth:その月の初日を取得します。
結果:
{
"firstDayNextMonth": "2024-11-01 00:00:00"
}
フォーマット時間
動的値を使用してカスタムフォーマットの時間を生成することができます。指定されたフォーマットに従って、要求に適合する時間文字列を取得できます。一般的な時間フォーマットには、年、月、日、時間、分、秒などが含まれ、以下のフォーマット記号を使用することができます:
- yyyy:4桁の年
- MM:2桁の月
- dd:2桁の日
- HH:2桁の時間
- mm:2桁の分
- ss:2桁の秒
Request例 1:フォーマットされた現在の時間を生成
{
"formattedTime": "{{$date.now|format('yyyy-MM-dd HH:mm:ss')}}"
}
結果:
{
"formattedTime": "2024-10-09 12:08:42"
}
Request例 2:現在の日付を生成(年-月-日)
{
"currentDate": "{{$date.now|format('yyyy-MM-dd')}}"
}
結果:
{
"currentDate": "2024-10-09"
}
Request例 3:カスタムフォーマットされた時間を生成
{
"customFormatTime": "{{$date.now|format('yyyy/MM/dd HH:mm')}}"
}
結果:
{
"customFormatTime": "2024/10/09 12:16"
}
さらに多くの日付/時間設定
上記に示した時間生成の動的値の式以外にも、Apidogには他にも多くの日付関数が組み込まれています。これらの関数を利用して任意の時間点の日付を生成でき、複雑なシナリオの要件にも対応できます。以下の図に示すように、上下にスクロールして確認できます:
住所
ランダムな住所データの生成をサポートし、ユーザーが入力する実際の住所のシミュレーションを支援します。
Request例(都市を生成):
{
"city": "{{$location.city}}"
}
結果:
{
"city": "秋田市"
}
「都道府県/市区町村」の形式の住所を生成したい場合、複数の「動的値式」を組み合わせて実現できます。ただし、組み合わせた住所の各部分はランダムに生成されるため、2次連動を実現することはできず、ある部分の住所情報に基づいて関連する次のレベルの情報を自動的にマッチすることはできません。例:
{
"shippingAddress": "{{$location.state}}{{$location.city}}{{$location.county}}{{$location.streetAddress}}{{$location.secondaryAddress}}"
}
画像
ファイルアップロードや画像処理のAPIで、ランダムな画像URLを生成してテストをシミュレーションすることができます。
Request例(ランダムに画像のURLを生成し、画像の幅と高さを300x300に指定):
{
"profileImage": "{{$image.url(width=300,height=300)}}"
}
結果:
{
"profileImage": "https://loremflickr.com/300/300?lock=8851134520359029"
}
銀行カード番号
ランダムな銀行カード番号を生成し、長さを設定することができます。これは、支払いシステムやその他の金融取引が関わるシナリオテストによく使用されます。
Request例(19桁の銀行カード番号を生成):
{
"bankCard": "{{$finance.accountNumber(length=19)}}"
}
結果:
{
"bankCard": "6962717965512801819"
}
正規表現
動的値では、正規表現を使用して特定のルールに適合するデータを生成することもできます。例えば、特定のフォーマットに合ったカスタムコードや識別子を生成する場合です。
Request例:
{
"customCode": "{{$helpers.fromRegExp('/[A-Z]{2}[0-9]{4}[a-z]{2}/')}}"
}
結果:
{
"customCode": "IF0532sf"
}
正規表現 /[A-Z]{2}[0-9]{4}[a-z]{2}/ は、2つの大文字、4つの数字、2つの小文字を含む指定フォーマットのコードを生成しました。
その他の境界条件
上記の一般的なデータタイプのほかに、「動的値」機能は他の境界条件データの生成もサポートしており、入力データが極端なケースをテストする必要がある場合に適しています。
Request例:
{
"boundaryValue": {{$helpers.rangeToNumber(min=1,max=100)}}
}
結果:
{
"boundaryValue": 16
}
ここでは1から100の間のランダムな整数を生成しており、数量や範囲などのパラメータの境界テストに使用できます。
まとめ
以上がApidog動的値の紹介と使い方です。さまざまなテストシナリオで使用でき、簡単なビジュアル操作や特定の構文を使用して必要なデータタイプを挿入することができます。より多くの使用方法については、ヘルプドキュメントの「動的値」モジュールや「動的値式」モジュールを参照してください。