Step CI で手軽に API をテストする
3-shake Advent Calendar 2022 の 1 日目です。
株式会社スリーシェイクのメンバーが各々自由に技術・非技術ネタを投稿していきます。
1 日目のこの記事では、 Step CI という API テストツールが最高だったので紹介します。
概要
Step CI は API をテストするためのシンプルなオープンソースのコマンドラインツールです。
REST はもちろん、 GraphQL や gRPC などその他様々な種類の API に対応しています。
stepci CLI をインストールして簡単な YAML ファイルを作成するだけで API のテストを実行することができます。
実行イメージ
検証環境
リポジトリ
この記事内で使用しているサンプルコードは以下のリポジトリで管理しています。
使い方
1. インストール
stepci CLI をインストールします。
npm もしくは yarn を使ってインストールすることができます。
$ npm install -g stepci
# or
$ yarn global add stepci
2. ワークフローを定義する
ワークフローを定義する YAML 形式のファイルを作成します。
下記は https://jsonplaceholder.typicode.com/posts/2 に GET リクエストを送信し、レスポンスの内容を検証するワークフローのサンプルです。
version: "1.1"
name: Validating JSON
# ワークフローの設定
config:
# HTTP クライアントの設定
http:
# テストする API のベース URL
baseURL: https://jsonplaceholder.typicode.com
# 環境変数
env:
postId: 2 # ${{env.postId}} のように使うことができる
# テスト
tests:
example:
steps:
- name: GET request
http:
# リクエストするパス
# フルで指定してもいい (config.http.baseURL とは異なる URL を指定するときなど)
# 例) url: https://jsonplaceholder.typicode.com/posts/${{env.postId}}
url: /posts/${{env.postId}}
# HTTP メソッド
method: GET
# 検証
check:
# ステータスコード
status: 200
# レスポンスヘッダ
headers:
Content-Type: application/json; charset=utf-8
# JSON の内容
jsonpath:
$.id: ${{env.postId}}
$.userId: 1
レスポンスの検証では正規表現を使用したりその他様々なマッチャを使用することも可能です。
# ...省略
tests:
example:
steps:
- name: GET request
http:
# ...省略
check:
# `/` で囲むと正規表現を使用できる
status: /^20/
# 様々なマッチャを複数使用できる
jsonpath:
$.userId:
- isNumber: true # userId が数値であることを検証
- lt: 999 # userId が 999 未満であることを検証
ここで記述している設定以外にも多数の設定項目やマッチャが用意されています。
詳細については以下のドキュメントをご参照ください。
3. テストを実行する
stepci run <ワークフローファイル> のように実行することで API テストが実行されます。
$ stepci run ./workflow.yml
実行イメージ
かんたん！
上記で紹介したサンプルコードは単一のステップを含む単一のテストしか実行していませんが、複数のステップを含む複数のテストを実行するワークフローを作成することも可能です。
version: "1.1"
name: Multiple tests
tests:
example1:
steps:
- name: Step 1
# ...省略
- name: Step 2
# ...省略
example2:
steps:
# ...省略
使用データの収集について
stepci CLI は実行時にデフォルトで Node.js のバージョンや CLI のバージョンなどといった匿名の使用データを収集します。
収集を無効にしたい場合は STEPCI_DISABLE_ANALYTICS 環境変数を設定してください。
# 値はなんでもいい
$ export STEPCI_DISABLE_ANALYTICS=1
詳しくは以下のドキュメントをご参照ください。
GitHub Actions で実行する
Step CI では GitHub Actions 上で実行するためのアクションも用意されています。
下記は workflow.yml を読み込んで Step CI を実行するワークフローのサンプルです。
name: api test
on:
push:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: stepci/stepci@main
env:
STEPCI_DISABLE_ANALYTICS: "1" # データの収集を無効にする場合は設定する
with:
workflow: workflow.yml # ワークフローファイルを指定
ライブラリとして使う
@stepci/runner を使うことで Step CI をライブラリとして使用することも可能です。
ちゃんと TypeScript もサポートされています ( ありがたい ) 。
1. インストール
npm もしくは yarn を使ってインストールすることができます。
$ npm install --save-dev @stepci/runner
# or
$ yarn add --dev @stepci/runner
2. サンプルコード
runFromFile を使うとワークフローをファイルから読み込んで実行します。
下記は workflow.yml を読み込んで Step CI による API テストを実行するサンプルコードです。
import { runFromFile } from '@stepci/runner';
runFromFile("./workflow.yml").then(console.log);
// => {
// workflow: {
// version: '1.1',
// name: 'Validating JSON',
// config: { http: [Object] },
// env: { postId: '2' },
// tests: { example: [Object] }
// },
// result: {
// tests: [ [Object] ],
// timestamp: 2022-11-26T00:27:43.634Z,
// passed: true,
// duration: 93,
// co2: 0.00009952956000000001
// },
// path: './workflow.yml'
// }
また、 run を使うとファイルを用意せずにワークフロー定義の JSON を直接渡すことができます。
より柔軟に設定をしたい場合に便利です。
import { run } from '@stepci/runner';
const workflow = {
version: "1.1",
name: "Validating JSON",
config: {
http: { baseURL: "https://jsonplaceholder.typicode.com" },
},
env: { postId: "2" },
tests: {
example: {
steps: [
{
name: "GET request",
http: {
url: "/posts/${{env.postId}}",
method: "GET",
check: {
status: 200,
headers: { "Content-Type": "application/json; charset=utf-8" },
jsonpath: { "$.id": "${{env.postId}}", "$.userId": 1 },
},
},
},
],
},
},
};
run(workflow).then(console.log)
// => {
// workflow: {
// version: '1.1',
// name: 'Validating JSON',
// config: { http: [Object] },
// env: { postId: '2' },
// tests: { example: [Object] }
// },
// result: {
// tests: [ [Object] ],
// timestamp: 2022-11-26T00:27:43.598Z,
// passed: true,
// duration: 131,
// co2: 0.00009952956000000001
// },
// path: undefined
// }
ユニットテストフレームワークと統合する
上述した @stepci/runner を使うことで Step CI を Jest や Vitest などといったユニットテストフレームワークと統合することも可能です。
下記は Vitest で Step CI による API テストを実行するサンプルコードです。
import { run, runFromFile } from "@stepci/runner";
import { expect, it } from "vitest";
it("from file", async () => {
const { result } = await runFromFile("./workflow.yml");
expect(result.passed).toBe(true);
});
it("from config", async () => {
const workflow = {
version: "1.1",
name: "Validating JSON",
config: {
http: { baseURL: "https://jsonplaceholder.typicode.com" },
},
env: { postId: "2" },
tests: {
example: {
steps: [
{
name: "GET request",
http: {
url: "/posts/${{env.postId}}",
method: "GET",
check: {
status: 200,
headers: { "Content-Type": "application/json; charset=utf-8" },
jsonpath: { "$.id": "${{env.postId}}", "$.userId": 1 },
},
},
},
],
},
},
};
const { result } = await run(workflow);
expect(result.passed).toBe(true);
});
その他
他にも Step CI は様々な機能をサポートしています。
Examples にサンプルの YAML ファイルが豊富に用意されているため、参考にしてみてください。
例えば次のようなものが用意されています。
他にも Open API 定義からワークフローを自動生成したり、 csv ファイルからテストデータを読み込んだり、ダミーデータを使用したりなど、とにかく機能が豊富すぎて紹介しきれないので詳細については公式ドキュメントをご参照ください。
まとめ
使い方が非常にシンプルかつ機能も豊富なのでめちゃくちゃ良いです。
とにかく導入が楽ですぐ始められるので、手軽に API テストを導入したいときに最適なのではないのでしょうか。
明日は @nwiizo さんの 「セキュア・バイ・デザイン」を読んで自分が何番目の豚かを考える。 です。わくわく。
Discussion