Gaugeで学ぶ実行可能ドキュメントの価値

gaugeで学ぶ実⾏可能ドキュメントの価値 シンプレクス株式会社 清家蒼⼀朗 JJUG CCC 2022 Fall 1

Learning Outcome • 実⾏可能ドキュメントとは • gaugeを使ったドキュメント作成⽅法 • 新しいアイデアをチームに導⼊するステップ 2

Agenda • ⾃⼰紹介/シンプレクスについて • 現場の課題 • 実⾏可能ドキュメント • gaugeの推しポイント • gauge導⼊に際して • まとめ 3

⾃⼰紹介 清家蒼⼀朗 Soichiro Seike 所属 シンプレクス株式会社 開発担当 ⾦融商品取引プロダクトチーム 使⽤する Java 技術要素 JavaScript(React.js, TypeScript) AWS 4

シンプレクスについて 1997年創業のITコンサルティング企業 IT戦略から開発、運⽤まで⼀気通貫で担い、トータルソリューションを提供 して います 創業当時より ⾦融フロント・ミドル領域 に強みを持ち、市場業務、リテール⾦融 業務に多数の実績 2013年より 保険領域 にビジネス拡⼤し、現在に⾄るまで実績多数 各種領域で ⾃社パッケージ・フレームワーク・ライブラリの開発・活⽤ により業 界知識集約・⽣産性向上を図っています 近年は⾮⾦融領域へもビジネスを展開しています 5

所属チームのプロダクトについて • toB向けの⾦融商品取引プロダクト • シンプレクスの蓄積してきた業務知識、お客様の課題ヒアリングをベースに、 より良いプロダクトを⽬指し、チームをスケールさせながら機能アップデート を進めている 6

現場の課題 機能仕様調査に潜むムダ 7

チーム内の仕様確認 A機能って、Bの状況の場合は、Cという動きになりますよね？ という問い合わせが来たんですけど、ドキュメントには記載がなく て、、 誰かわかりますか？ 基本はそうだね。 でも、BかつDの状況だと、Cという動きにはならなかったような。。 最近A機能って仕様変更あったような。。今も本当に記憶通り動く かな？ テスト環境で再現した方が確実な回答ができるね。 8

チーム内の仕様確認 【課題】 ・詳細な仕様知識の属人化 ・信頼できる情報の欠如 正確な仕様を迅速に把握するために A機能って、Bの状況の場合は、Cという動きになりますよね？ もっと改善できることがあるのでは？ という問い合わせが来たんですけど、ドキュメントには記載がなく て、、 誰かわかりますか？ 基本はそうだね。 でも、BかつDの状況だと、Cという動きにはならなかったような。。 最近A機能って仕様変更あったような。。今も本当に記憶通り動く かな？ テスト環境で再現した方が確実な回答ができるね。 9

チーム内の仕様確認 【課題】 ・詳細な仕様知識の属人化 ・信頼できる情報の欠如 正確な仕様を迅速に把握するために A機能って、Bの状況の場合は、Cという動きになりますよね？ もっと改善できることがあるのでは？ という問い合わせが来たんですけど、ドキュメントには記載がなく て、、 誰かわかりますか？ 信頼できる形式知が必要 基本はそうだね。 でも、BかつDの状況だと、Cという動きにはならなかったような。。 最近A機能って仕様変更あったような。。今も本当に記憶通り動く かな？ テスト環境で再現した方が確実な回答ができるね。 10

Executable Documentation (実⾏可能なドキュメント) 11

実⾏可能ドキュメント ⾮エンジニアが理解できる⾔語での仕様記述と、 実⾏可能なテストコードがセットになったドキュメント 12

実⾏可能ドキュメント ⾮エンジニアが理解できる⾔語での仕様記述と、 実⾏可能なテストコードがセットになったドキュメント ドキュメントと実際の振る舞いに差が⽣まれたことを検知できる 13

実⾏可能ドキュメントに期待すること • ドキュメントの読者が情報の劣化を⼼配することなく、読むこ とができる • 開発者はメンテナンスされなくなるかもしれない不安から解 放されて有益な形式知を作成できる 14

gauge 15

gaugeについて • ThoughtWorks社製OSSの実⾏可能ドキュメント作成フ レームワーク。 • Markdownで⾃由に記述が可能。 • Java、Ruby、Javascript、C#、Pythonで記述可能。 16

gaugeについて Spec(仕様書) 先頭の⽂字列を*にすると、テストケースとして 認識される ※発表向けのサンプルコードです 17

gaugeについて Step(テストコード) テストケースをどのように実現するか は⾃由。 ※発表向けのサンプルコードです 18

gaugeの使いやすいポイント ①: 形式的な書き⽅/読み⽅を強制されず、導⼊のハードルが 低い ②: ビルドツールへの統合プラグインが開発されており、継続的 なテストを⾏う環境の構築がしやすい 19

gaugeの使いやすいポイント ①: 形式的な書き⽅/読み⽅を強制されず、導⼊のハードルが 低い ②: ビルドツールへの統合プラグインが開発されており、継続的 なテストを⾏う環境の構築がしやすい 20

gaugeの使いやすいポイント 例えばCucumberのfeatureファイル ※発表向けのサンプルコードです 21

gaugeの使いやすいポイント gaugeのmarkdown 機能の概要/目的、入出力バリエーションの網羅 度を表現するテーブルなども自由に記載可能。 ※発表向けのサンプルコードです 22

gaugeの使いやすいポイント htmlドキュメント⽣成 プラグインを使えば、目次を含めたhtmlドキュメント を生成できる ※発表向けのサンプルコードです 23

gaugeの使いやすいポイント htmlドキュメント⽣成 ※発表向けのサンプルコードです 24

gaugeの使いやすいポイント ①: 形式的な書き⽅/読み⽅を強制されず、導⼊のハードルが 低い ②: ビルドツールへの統合プラグインが開発されており、継続的 なテストを⾏う環境の構築がしやすい 25

gaugeの使いやすいポイント 各種ビルドツールから実⾏可能 26

gaugeの使いやすいポイント Dockerでのイメージ提供 27

シンプレクスでの継続的テスト & ドキュメントの⽣成環境 ビルド結果のDocumentを配置し、 静的ホスティング S3 テスト環境 gaugeで記述した仕様に従い REST APIのテストを実⾏ Jenkinsおよびびそのロゴは、LF CHARITIES, INC.の⽶国及びその他の国における登録商標または商標です。 Mavenおよびそのロゴは、Apache Software Foundationの⽶国及びその他の国における登録商標または商標です。 gaugeおよびそのロゴは、ThoughtWorks Inc.の⽶国及びその他の国における登録商標または商標です。 28

なぜREST APIをテスト対象にしたのか 理想的な⾃動テストのピラミッド UI Test Integration Test 上に行くほど ・メンテコストは高い ・ユーザに近いテスト ・実行速度は遅い Unit Test 29

なぜREST APIをテスト対象にしたのか チームの⾃動テストのピラミッド UI Test 上に行くほど ・メンテコストは高い ・ユーザに近いテスト ・実行速度は遅い Unit Test 30

なぜREST APIをテスト対象にしたのか チームの⾃動テストのピラミッド UI Testは少数にとどめなければ メンテコストの方が高くなる。 REST APIをテストできるようにし、 ドキュメンテーションすることにした。 UI Test 上に行くほど ・メンテコストは高い ・ユーザに近いテスト ・実行速度は遅い Unit Test 31

REST-assuredについて REST-assured JavaでREST APIのテストを簡潔に記述するための OSSフレームワーク 32

REST-assuredについて REST APIの実行、assertまでを Given/When/Thenで記述可能 ※発表向けのサンプルコードです 33

gaugeの導⼊に際して 新しいアイデアをチームで試すには︖ 34

gaugeの導⼊に際して 35

gaugeの導⼊に際して 気をつけなければならないこと • 強いるのではなく、共感によって変化を起こす • 種を蒔いて、⽔をやることで、はじめて変化を起こせる 36

gaugeの導⼊に際して 導⼊までのステップ • 動き始めるためにあらゆる準備を • 有志でのお試し活動 • 少しづつ進む 37

gaugeの導⼊に際して 動き始めるためにあらゆる準備を チームにとって良い変化をもたらすものだと⾃分が⼀番に信じ、⾏ 動で⽰す。 • gaugeを継続的にテストできる環境の構築 • gaugeのセットアップ⼿順/セットアップを簡略化するスクリプト • 最もシンプルなテストケースの作成 38

gaugeの導⼊に際して 有志でのお試し活動 アーリーアダプターを巻き込み、アイデアを試してみて、学習を深める。 ⼀⼈でも⼆⼈でも仲間が増えれば、より多くの発⾒が⾒つかる。 • gaugeを使って解決したい課題と、gaugeについて紹介する • 定期的にモブプロでドキュメント作成を⾏うコミュニティを作る 39

gaugeの導⼊に際して 少しづつ進む 短期的な⽬標を１つずつクリアしていくことで、定期的に⾃分達の⾏動を 振り返る。⼀気に⾼い⽬標のために動き出すと振り返る機会が少ないゆ えに形骸化したり、遠すぎる⽬標に届かず挫折の原因になる。 • まずはよく問い合わせのくる機能に絞ってドキュメンテーション 40

gaugeの導⼊に際して ⽬指したい姿 チームとして決めたことだからやる ではなく アイデアに共感する仲間になってもらう 無理なく、楽しく、⻑続きする⽂化になる 41

まとめ • プロダクト仕様の暗黙知化、情報の信頼性の⽋如に実⾏可能ドキュ メントで⽴ち向かう • gaugeは実⾏可能な仕様書を作成するためのツール。Markdown での仕様記述が可能でドキュメント⽣成も充実しており、記述/読解 のハードルが低い。 • 新しいアイデアを組織に浸透させるにはツールの紹介だけでは不⼗分。 できる限りの準備と、継続的にアイデアを浸透させる活動が必要。 42

ご清聴ありがとうございました。 43