クラウドランナーテストの生成 REST API

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：16分

    • 自動テストフレームワーク (ATF) のクラウドランナーで実行されるテストジョブの生成を管理します。

    Cloud Runner テスト生成 API には ATF Test Generator and Cloud Runner (sn_atf_tg) プラグインが必要です。この API で利用可能なメソッドは now 名前空間で実行され、REST API エクスプローラーの API 名である ATF のワンクリック回帰テストを使用して呼び出すことができます。この API にアクセスするには、admin ロールが必要です。

    この API は、次のタスクに使用できます。
    • テスト生成ジョブを開始します。
    • テスト生成ジョブの進行状況を確認します。
    • テスト生成ジョブをキャンセルします。

    Cloud Runner Test Generation API は、クラウドランナーテストランナー REST API および クラウドランナーテスト ユーザー REST API と組み合わせて使用できます。たとえば、テスト生成 API を呼び出してテストを実行し、ブラウザーオーケストレーションキュー (Cloud Runner TEST Generation API) でテストの進行状況を取得して、合格または失敗したテストの数を確認できます。

    この API のサーバー API リファレンス ドキュメントを表示するには、「 クラウドランナー TestGenerationApi – スコープ付き、グローバル」を参照してください。

    クラウドランナーテストの生成:GET /now/sn_atf_tg/test_generation_progress

    指定されたブラウザーオーケストレーションキュー (BOQ) レコードに対して生成された各テストのステータスを提供します。

    URL 形式

    デフォルト URL:GET /api/now/sn_atf_tg/test_generation_progress

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    なし
    表 : 2. クエリパラメータ
    名前 説明
    snboqId 必須。進捗状況を取得するテスト生成ジョブの BOQ レコードsys_id。

    データタイプ：文字列

    テーブル:BOQ [sn_atf_tg_sn_boq]
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 BOQ ジョブの進捗状況が正常に取得されました。
    400 BOQ レコードステータスの取得中にエラーが発生しました。次のメッセージのいずれかを返します。
    • BOQ ID が渡されませんでした:BOQ ID が指定されていません。BOQ ID を要求本文に追加します。
    • BOQ レコードが見つかりません:Sys ID が無効です。BOQ レコードの sys_id が有効であり、レコードが存在することを確認します。
    403 エンドポイントへのユーザーアクセスの許可中にエラーが発生しました。ユーザーに admin ロールがあることを確認します。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    結果 生成されたテストジョブの進行状況の結果、または要求が失敗した理由を説明するメッセージを含むオブジェクト。

    データタイプ: オブジェクト

    "result": { 
    "testsSucceeded": Number, 
    "testsFailed": Number, 
    "testsPending": Number, 
    "testsInProgress": Number, 
    "testsSkipped": Number 
  } 
}

    または：

    {
  "result": { 
    "message": "String" 
  } 
}
    result.message テスト生成の進行状況を取得できない理由を詳述したエラーメッセージ。正常な応答ではメッセージパラメーターは返されません。

    データタイプ：文字列
    result.testsSucceeded 合格した生成済みテストの数。

    データタイプ：数値
    result.testsFailed 失敗した生成済みテストの数。

    データタイプ：数値
    result.testsPending 生成されたテストを待機しているユースケースの数。

    データタイプ：数値
    result.testsInProgress テストが作成されるユースケースの数。

    データタイプ：数値
    result.testsSkipped ジョブのキャンセルによりスキップされたテストの数。

    データタイプ：数値

    cURL 要求

    次の GET 呼び出しは、snboqId 1234 に関連付けられた生成されたテストに関する進行状況情報を返します。

    curl "https://instance.service-now.com/api/now/sn_atf_tg/test_generation_progress?snboqId=1234" \ 
--request GET \ 
--header "Accept:application/json" \ 
--user "username":"password"

    出力:

    { 
  "result": { 
    "testsSucceeded": 0, 
    "testsFailed": 0, 
    "testsPending": 0, 
    "testsInProgress": 0, 
    "testsSkipped": 161 
  } 
}

    次の例では、BOQ ID が渡されない場合に 400 エラーメッセージを返します。

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_generation_progress" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    応答：

    {
  "result": {
    "message": "No SNBOQ ID passed in, add snboqId to request body"
  }
}

    次の例では、無効な BOQ ID が渡されると、400 エラーメッセージが返されます。

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_generation_progress?snboqId=invalid_sys_id" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    応答：

    {
  "result": {
    "message": "Invalid SNBOQ sys_id passed in"
  }
}

    クラウドランナーテストの生成:POST /now/sn_atf_tg/cancel_test_generation

    テスト生成ジョブとそれに関連する更新セットレコードを完了ステータスに設定します。実行中の生成されたすべてのテストのルートトラッカーをキャンセルします。キャンセル時にテストジョブが進行中の場合、このメソッドは生成された進行中のテストレコードをスキップに設定します。

    ビジネスルールまたはアクセス制御ルール (ACL) の問題により、テストは自動的に失敗またはキャンセルされる可能性があります。失敗したテストまたはキャンセルされたテストの詳細については、生成されたテストテーブルを参照してください。

    URL 形式

    デフォルト URL:POST /api/now/sn_atf_tg/cancel_test_generation

    サポートされている要求パラメーター

    表 : 7. パスパラメーター
    名前 説明
    なし
    表 : 8. クエリパラメータ
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    snboqId 必須。キャンセルするブラウザーオーケストレーションキュー (BOQ) レコードのSys_id。

    データタイプ：文字列

    テーブル:BOQ [sn_atf_tg_sn_boq]

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 10. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 12. ステータスコード
    ステータスコード 説明
    200 BOQ ジョブが正常にキャンセルされました。
    400 ジョブのキャンセル中にエラーが発生しました。次のメッセージのいずれかを返します。
    • BOQ ID が渡されませんでした:BOQ ID が指定されていません。BOQ ID を要求本文に追加します。
    • BOQ レコードが見つかりません:Sys ID が無効です。BOQ レコードの sys_id が有効であり、レコードが存在することを確認します。
    403 エンドポイントへのユーザーアクセスの許可中にエラーが発生しました。ユーザーに admin ロールがあることを確認します。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    結果 キャンセル要求の結果を含むオブジェクト。

    データタイプ: オブジェクト

    "result": { 
    "message": "String"
}
    result.message テストのキャンセルが成功したかどうかを示すメッセージ。

    データタイプ：文字列

    cURL 要求

    次の要求は、指定された BOQ レコードのテスト生成ジョブをキャンセルします。

    curl "http://instance.service-now.com/api/now/sn_atf_tg/cancel_test_generation" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{\"snboqId\":\"<sys_id of BOQ record>\"}" \ 
--user "username":"password"

    応答本文は、キャンセルの成功メッセージを返します。

    { 
  "result": { 
    "message": "success" 
  } 
}

    次の例では、BOQ ID が渡されない場合に 400 エラーメッセージを返します。

    curl "http://instance.service-now.com/api/now/sn_atf_tg/cancel_test_generation" \
--request POST \
--header "Accept:application/json" \
--user "username":"password"

    応答：

    {
  "result": {
    "message": "No SNBOQ ID passed in, add snboqId to request body"
  }
}

    次の例では、無効な BOQ ID が渡されると、400 エラーメッセージが返されます。

    curl "http://instance.service-now.com/api/now/sn_atf_tg/cancel_test_generation" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"snboqId\":\"invalid_sys_id\"}" \
--user "username":"password"

    応答：

    {
  "result": {
    "message": "No SNBOQ ID passed in, add snboqId to request body"
  }
}

    クラウドランナーテストの生成:POST /now/sn_atf_tg/test_generation

    ブラウザーオーケストレーションキュー (BOQ) [sn_atf_tg_sn_boq] テーブルにレコードを挿入して、テストジョブを開始します。

    URL 形式

    デフォルト URL:POST /api/now/sn_atf_tg/test_generation

    サポートされている要求パラメーター

    表 : 13. パスパラメーター
    名前 説明
    なし
    表 : 14. クエリパラメータ
    名前 説明
    なし
    表 : 15. 要求本文パラメーター (XML または JSON)
    名前 説明
    カタログエンコードクエリ テストを生成するカタログアイテムを指定するエンコードされたクエリ。空の文字列は、デフォルトですべてのカタログアイテムに設定されます。エンコードされたクエリの形成の詳細については、「 Encoded query strings」を参照してください。

    データタイプ：文字列
    メール テストの生成が完了したときにアラートを送信するメールアドレス。

    データタイプ：文字列
    最大テスト数 生成する全体的なテストの数。

    指定できる値:1 〜 9999 の任意の数値。

    データタイプ：数値

    デフォルト:9999
    アイテムごとの最大テスト数 カタログアイテムごとに生成するテストの数。

    指定できる値:1 〜 10 の任意の数。

    データタイプ：数値

    デフォルト値：10
    maxTestCountPerTable テーブルごとに生成するテストの数。

    指定できる値:1 〜 10 の任意の数。

    データタイプ：数値

    デフォルト値：10
    scopeForGeneratingTest separateUpdateSetPerScope が false に設定されている場合は必須です。生成されたすべてのテストを配置するスコープのSys_id。

    データタイプ：文字列
    separateUpdateSetPerScope 生成されたテストをそれぞれのスイート、更新セット、およびスコープに分割するか、またはテストを 1 つのスイート、更新セット、およびスコープに配置するかを示すフラグ。
    有効な値：
    • true:テストは、各テーブルまたはカタログアイテムのスコープに従って、それぞれのスイートと更新セットに配置されます。
    • false:生成されたすべてのテストは、同じスイート、更新セット、およびスコープに配置されます。false の場合、要求に scopeForGeneratingTests が必要です。

    データタイプ：ブーリアン

    デフォルト：true
    テストスイート オプション。テスト生成によって作成するテストスイートの名前を設定します。

    データタイプ：文字列

    デフォルト:ATF によって生成されたスイート - <time_stamp>
    テーブルエンコードクエリ テストを生成するテーブルを指定するエンコードされたクエリ。空の文字列は、デフォルトですべてのテーブルに設定されます。エンコードされたクエリの形成の詳細については、「 Encoded query strings」を参照してください。

    データタイプ：文字列
    userEncodedQuery テストを生成するユーザーを指定するエンコードされたクエリ。空の文字列入力は、デフォルトですべてのテーブルに設定されます。エンコードされたクエリの形成の詳細については、「 Encoded query strings」を参照してください。

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 16. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 17. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 18. ステータスコード
    ステータスコード 説明
    200 テスト生成 BOQ ジョブが正常に挿入されました。エラーは、処理中に BOQ レコードログに表示されます。[すべての入力] では、デフォルトですべてのテーブルとサービスカタログアイテムに対して最大数のテストが生成されます。
    403 エンドポイントへのユーザーアクセスの許可中にエラーが発生しました。ユーザーに admin ロールがあることを確認します。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    結果 要求の結果を含むオブジェクト。
    
  "result": { 
    "snboqId": String
  }

    データタイプ: オブジェクト
    result.snboqId テスト生成の開始時にsn_atf_tg_sn_boqテーブルに挿入されるレコードのSys_id。

    データタイプ：文字列

    cURL 要求

    次の要求例では、要求パラメーターなしでインスタンスで新しいテストジョブを開始し、BOQ テーブルにジョブを挿入します。

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_generation" \ 
--request POST \ 
--header "Accept:application/json" \ 
--user "username":"password"

    応答本文：

    { 
  "result": { 
    "snboqId": <sys_id of newly inserted BOQ record> 
  } 
}

    次の要求例では、最大テスト数が 2 の新しいテストジョブを開始し、テストをインシデントテーブルにフィルタリングしてから、ジョブを BOQ テーブルに挿入します。

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_generation" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{\"maxTestCount\":\"2\",\"tableEncodedQuery\":\"name=incident\",\"testSuite\":\"Suite123\"}" \ 
--user "username":"password"

    応答本文：

    { 
  "result": { 
    "snboqId": <sys_id of newly inserted BOQ record> 
  } 
}