API シナリオテストツール runn 導入記 — なぜ "runn" を選んだのか？
参考になった
9
株式会社テックドクター / 筧礼矢
メンバー / バックエンドエンジニア / 従業員規模: 11名〜50名 / エンジニア組織: 11名〜50名
| 利用機能 | ツールの利用規模 | ツールの利用開始時期 |
|---|---|---|
runn run のコマンド | 10名以下 | 2025年3月 |
| 利用機能 | runn run のコマンド |
|---|---|
| ツールの利用規模 | 10名以下 |
| ツールの利用開始時期 | 2025年3月 |
導入の背景・解決したかった問題
導入背景
ツール導入前の課題
runn 導入以前では、次のような課題がありました。
- API をリリースする予定で、 API の品質はできるだけ担保しておきたかったです。
- API テストや API シナリオテストはまだ導入しておらず、具体的な方法論やツールの選定も未定でした。
- 複数リポジトリの動作確認をする結合テストも未導入でした。
どのような状態を目指していたか
「高速かつ効率的な API テスト環境の確立」を目標としていました。
- 網羅的な API シナリオテストの実現: ビジネスフローを模倣したシナリオ全体をテストし、API間の不具合を早期に発見すること。
- コードベースでのテスト管理: テストコードを Git で管理し、開発しやすい環境とメンテナンスのしやすさを図ること。
- CI/CD パイプラインとのシームレスな統合: テストプロセスを自動化し、CI/CD に組み込むことで、コード変更の度に品質チェックが実行されるようになること。
比較した軸
ツール選定では、課題と目標を踏まえ、以下の点を重視しました。
- API シナリオテストへの特化度: 複数 API 連携シナリオ記述の効率と柔軟性。
- コードベースでの管理の容易性: Git 管理、バージョン管理、レビューのしやすさ。
- CI/CD との連携: 自動テストの CI/CD 組み込み可否。
- デバッグの容易性: テスト失敗時の原因特定しやすさ。
- 学習コストと拡張性: 習得のしやすさ、将来的な機能拡張性。
選定理由
比較検討の結果、runn の導入を決定しました。
Postman は GUI が優れるものの、複雑なシナリオや Git 管理に課題がありました。Tavern は YAML 記述でコード管理向きでしたが、当時の Pytest 対応や特殊構文に懸念がありました。
これに対し、runn は重視した要件を全て満たしていました。
- API シナリオテストに特化した設計: 課題解決に直結。
expr-langによる柔軟な記述: 強力なテストシナリオ作成が可能。- DB アクセス機能: テスト信頼性やデバッグの容易性を大幅に向上。
- CI/CD との高い親和性: スムーズな CI/CD 統合。
- 高速な実行性能と優れたデバッグ機能: テスト実行高速化とデバッグ効率化。
これらの要素が、runn が選択として適切であると感じました。
導入の成果
改善したかった課題はどれくらい解決されたか
runn 導入により、解決を目指していた課題は大いに改善されました。
- APIシナリオテストの確立: 複雑なフローの網羅的なテストが実現し、API 間の連携不具合も見つかるようになりました。
- 複数リポジトリの連携: 今まで認証・認可部分 (Keycloak) と Backend の連携テストはできていませんでしたが、今回の導入によって連携されるようになりました。
- テストコードの Git 管理および CI/CD 統合: runn の YAML ベースの記述とシンプルなコマンド実行により CI/CD 連携が実現し、コードの変更や定期的なタイミングで自動的に品質チェックが行われるようになりました。
どのような成果が得られたか
runn 導入から約3ヶ月で、具体的な成果を確認しています。
- APIのバグを3件以上発見: 開発初期段階でバグを複数発見し、本番障害防止と手戻り工数削減に成功しました。特に印象的だったのは、ユーザー削除のエンドポイントの開発でのバグでした。これは Keycloak でユーザー削除したときに発生するイベントから BE でユーザーを削除するという処理で、イベントを受け取ったがユーザーを削除できていないというバグがありました。これは runn で API を叩き、 DB を直接見ることでバグを発見することができました。
- 開発効率の向上: 自動化されたテストが品質を保証するため、開発者は安心して開発に取り組めるようになりました。
- テストコードの可読性・保守性の改善: YAML 形式のテストシナリオは理解しやすく、チーム全体での共有とメンテナンスが容易になりました。
導入時の苦労・悩み
runnは優れていますが、導入初期に課題もありました。
- runn および expr-lang の学習コスト: 独自の概念や構文（例:
dump: "'Hello World!'"）に慣れるまで時間がかかりました。特に expr-lang の強力な機能と柔軟性を理解し、効果的に活用できるようになるまでに約1週間程度の期間を要しました。 - runner, steps などの構文の仕様理解: CI/CD に組み込むときにカスタムランナーを用いていますが、その仕様を理解するのに時間がかかりました。
- expr-lang の利用範囲の制約: vars ブロック内での使用制限など、一部柔軟な変数操作が困難なケースもありました。
これらの課題は実践を通じて解消することができました。
導入に向けた社内への説明
上長・チームへの説明
runn 導入提案では、上長およびチームに対し、以下の点を中心に説明しました。
- 「なぜ runn を選ぶのか」: Postman/Tavern との比較で runn の技術的優位性（特化設計、DB 連携、柔軟性、高速性）を力説し、コード管理・CI/CD 連携への適合性を説明しました。
- 費用対効果: runn が無償である点を強調し、バグ早期発見による手戻り削減、自動化によるテスト工数削減、開発サイクル高速化のメリットを提示しました。
- 満たすべき条件: システム変更の工数の低さ、拡張性、チーム内でのメンテナンス可能性といった要件に対し、runn の柔軟な対応ができることを説明しました。
活用方法
runn は開発サイクルに統合され、チームおよび個人で利用されています。
- CI/CD パイプラインでの自動実行: PR のマージ時に API シナリオテストを自動実行し、品質ゲートとして機能しています。
- 開発中のローカルでのデバッグ: API 実装や変更時に runn でシナリオテストを実行し、
--debugフラグで詳細確認しながら開発を進めています。 - 定期的な品質チェック: 全シナリオテストを定期的に実行し、API の品質維持や問題の早期発見に貢献しています。
よく使う機能
runn の多機能性の中から、特に頻繁に活用している主要機能は以下の通りです。
expr-langによる柔軟な式評価: YAML での変数定義やアサーションを柔軟に行い、動的なデータ連携も容易に実現。steps: ... - desc: Set Default Headers bind: default_header: Accept: '"application/json"' Cookie: join(["access_token=", access_token_with_user_id ?? access_token])steps: ... - ... test: | current.res.status == 403 && hasSuffix(current.res.body.error.message, "Access denied")--debugフラグ: テスト実行時の詳細表示で、シナリオ作成や不具合デバッグを強力に支援。DB への直接アクセス: API 検証に加えて、DB への直接クエリで網羅的な検証が可能。
desc: Get Template Version runners: db: spanner://test-project/test-instance/test-database if: included vars: template_id: "{{ parent.vars.template_id}}" steps: - desc: Get Template Version db: query: | SELECT * FROM `TemplateVersions` WHERE `TemplateId` = '{{ vars.template_id }}' ORDER BY `Version` DESC LIMIT 1; test: | len(current.rows) > 0 && current.rows[0].TemplateId == vars.template_id && current.rows[0].TemplateVersionId != null bind: template_version_id: current.rows[0].TemplateVersionId template_id: current.rows[0].TemplateIdincludes機能: 共通テスト手順のモジュール化と再利用で、テストコードの重複排除と保守性を向上。steps: - desc: Get test user id include: path: ../api/auth/me.yml vars: token_identifier: test-user-1 test: | current.res.body.name == "Test" && current.res.body.user_id != null bind: user_id: current.res.body.user_id
ツールの良い点
runn を導入して特に実感している良い点は、以下の通りです。
- API シナリオテストに特化した設計: 複雑な API 連携テストを効率的に実行可能。
- 高い柔軟性:
expr-langや DB アクセス、Go ヘルパーで柔軟なテストシナリオを記述できる。 - CI/CD との高い親和性: YAML ベース記述とコマンド実行で CI/CD 組み込みが容易。
- 高速な実行性能: Go 言語による開発でテスト実行処理が速い。具体的には、ローカル環境で20件のシナリオ(認証・DB アクセス含め)のテストを約30秒で完了できている。
- 費用対効果の高さ: 無償でありながら、高いテスト品質と開発効率向上を実現できている。
ツールの課題点
runn は優れていますが、運用していく中でいくつかの課題も感じました。
- 複雑なシナリオの YAML 記述: 非常に複雑な条件分岐やループ処理などを含むシナリオを全てYAML で表現しようとすると、記述が長くなり、可読性やメンテナンス性が低下する可能性があります。その場合は、 Go ヘルパーの活用 などを検討する必要があります。当プロダクトでは runn を GO からの呼び出しをしないで組んだため、 GO ペルパーを組み込む際は少し工数がかかってしまいます。
- GUI 不足による一部操作の非効率性: CLI ベースのツールであるため、テストシナリオの視覚的な作成や、テスト結果の詳細な分析において、GUI ツール（例: Postman）のような直感的な操作ができない場合があります。CDP (Chrome DevTools Protocol) が使えるので、そこでカバーできる点もあります。
- CDP 処理のオプション不足: CDP を扱う上で chromedp というツールを使っていますが、ランブック (runn でテストする YAML ファイル) 内で chromedp に対して細かいオプションをつけて実行することができませんでした。これは、 CI/CD 上での CDP でバグがあり、それをローカルで再現することができないというケースがありました。
これらの課題はありますが、ツールのメリットを活かしつつ、運用でカバーできる点も多いと考えています。
ツールを検討されている方へ
API の品質保証や CI/CD への API テスト統合をご検討であれば、runn は強力な選択肢となり得ると思います。
特に、以下のようなチームにとっては、きっと良い影響をもたらすと考えています。
- API シナリオテスト導入を検討中で、ツール選定に悩んでいるチーム。
- UI テストの実行速度やメンテナンスコストに課題を抱えているチーム。
- テストコードの Git 管理と CI/CD 組み込みを企図しているチーム。
- API テストにおいてデータベース連携も視野に入れているチーム。
学習コストは決して低くはないかもしれませんが、その先に得られる品質向上と開発効率のメリットは大いにあると思います。ぜひ一度 runn の導入をご検討されてはいかがでしょうか。
ご検討される際には、弊社の記事: API シナリオテストツール Postman・Tavern・runn 徹底比較 – 私が runn を選んだ理由 も参考になるかと思います。
今後の展望
今後も runn を活用して、API の品質向上に向けて取り組んでいきたいと思います。
- テストカバレッジの向上: 現在テストできている API が 3 割程度なので、8 割ほどまであげていきたいです。具体的には、データのダウンロードやデータ管理の機構といった主要なビジネスロジックに関わる API から優先的にテストシナリオを拡充し、段階的にカバレッジを向上させていく計画です。
- 他プロダクトへの runn 横展開: まだ 1 つのプロダクトでしか runn を使用していないため、横展開していきたいと思います。
株式会社テックドクター / 筧礼矢
メンバー / バックエンドエンジニア / 従業員規模: 11名〜50名 / エンジニア組織: 11名〜50名
よく見られているレビュー
株式会社テックドクター / 筧礼矢
メンバー / バックエンドエンジニア / 従業員規模: 11名〜50名 / エンジニア組織: 11名〜50名
