CLI 機能の構築は、多くの場合次のようになります:

• 新しい API エンドポイントをリリースします。
• API の変更が必要な新しい CLI アクションを構築します。
• リリースしたばかりの API で間違いがあったことに気づきました。
• 今後さらなる問題を引き起こさないように、この機能の API の修正を試みてください。
• CLI で何を達成しようとしていたのかを思い出し、実際にそれを達成してみてください。  
• 後藤: 間違いがあったことに気付きました。

各ステップには前のステップが必要です。おっと、ウォーターフォール プロジェクト管理を再発明してしまいました。足を引きずって機能するようになるまで、失敗を優雅に乗り越えようとして痛みに疲れ果てますが、例外的な状況になる前に、うんざりしてしまいます。そして、結果として生じるその場限りの「修正」と問題のクラスターの保守を始めさせないでください。

そこにいた、やった。私たちは滝のようなアプローチを乗り越える必要があることを知っていました。

ここでは、私たちがそこに至るまでの経緯と、その過程で役に立ったいくつかのツールについて説明します。

大ざっぱなスタート

私たちは、機能を理解するまでは安価で迅速な反復を行い、理解してから高価な実装と長期サポートを約束したいと考えていました。小規模なチームとして、私はこのプロセスをエンドツーエンドで行うことが多く、各部分に順番に集中したいと考えていました。私たちは、十分に自信を持って作成できるようになるまで、実装部分を偽装したいと考えていました。

プロセスに戻りますが、機能の提案から始まります。私たちは抽象的な表現から抜け出したいと思っていましたが、それが中途半端な実装を意味するのであればそうではありませんでした。 Github でここで説明されている Google Docs CLI スケッチ アプローチに触発されて、「スケッチ」でそれを偽装しました。

残念ながら、静的スケッチでは私たちが望んでいたようなフィードバックが得られませんでした。私たちの CLI は、時間の経過とともに出力を変化させます。描画というよりはアニメーションに似ています。より高い忠実度を達成するために、基本的な入力を受け取り、適切な定型応答を出力することで応答する小さな Ruby プログラムを作成しました。

それ以来、アニメーション CLI 出力をキャプチャするさらに良い方法を見つけましたが、それを説明するには少し回り道が必要です。

テストもしますか？

CLI の具体化を開始するにあたり、エッジケースをテストして回帰を検出したいとも考えました。アイデアを探すために公開されている cobra/bubbletea ベースの CLI を調査しましたが、イライラするほどテストがほとんどありませんでした。その後、Charm の乳首テストに出会い、それが出発点となりました。

Teatest はゴールデン テストに焦点を当てており、既知の良好な出力をキャプチャし、将来の出力が引き続きその出力と一致することを主張します。これにより、アニメーション CLI 出力の高忠実度キャプチャに再び戻りました。 Teatest は、フリップブックのようなフレームベースのソリューションという素晴らしいアイデアを私たちに与えてくれました。私たちはそれをもとに構築しました。

─── SigninHeader ───────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
─── SigninInput --──────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    ? What is your username?
    ? user
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signing in to your CLI account… ⠋
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signed in to your CLI account: [email protected]

この簡略化された例は、基本的な認証コマンドのゴールデン出力がどのように見えるかを示しています。水平線はフレームを示し、ラベルはアクティブなモデルを示します。これらを総合すると、行が追加、削除、または置換された場合でも、出力を忠実にキャプチャできます。

テスト スイートでフラグを使用して、ゴールデン出力でファイルを更新します。それ以外の場合、出力がファイルと一致しない場合、テストは失敗します。これにより、出力の変更を常に認識し、出力がどのように見えるべきか、変更されたかどうかを理解できるため、PR レビューが容易になります。私たちはそれがとても気に入ったので、アニメーションとスタイルのアイデアの両方をキャプチャできるように、スケッチ プログラムを Github スタイルの Google ドキュメントのゴールデン スタイルの出力に置き換える予定です。

これまでと将来のスケッチを手に入れて、新しい API エンドポイントの使用開始に戻りましょう。

API と CLI を一緒に設計する

API と CLI の最適な設計は緊密な統合から生まれるため、私たちは API と CLI に同時に取り組んでいます。より安価なコンテキストで設計を繰り返し、要件が固まるまで実装を待つことで、ウォーターフォールの危険を回避しながらこれを実現できます。私たちの API の場合、これは OpenAPI を使用したスケッチを意味します:

openapi: 3.1.0
info:
  contact:
    email: [email protected]
  description: An example API.
  title: Example API
  version: 0.0.1
servers:
  - url: https://api.example.com
tags:
  - description: account operations
    name: account
paths:
  '/v0/auth/signin':
    post:
      description: Signin to CLI.
      operationId: auth_signin
      responses:
        '200':
          content:
            'application/json':
              schema:
                additionalProperties: false
                properties:
                  email:
                    description: Email address for authenticated user.
                    example: [email protected]
                    type: string
                required:
                  - email
                type: object
          description: Successful signin.
      summary: Signin to CLI.
      tags:
        - account

この簡略化された例は、基本的な認可コマンドのスキーマがどのようになるかを示しています。これらのファイルの作業を簡素化するためにスペクトル リンターを使用します。

スケッチを用意して、CLI を実装する際に prism をモック API サーバーとして使用します。間違いがあったことに必然的に気づいた場合は、仕様を微調整して CLI の反復に戻るだけで済みます。この高いレベルで作業することで、API と CLI を一緒に進化させ、知識が深まるまでコストのかかる実装を延期することができます。

APIの実装

また、委員会を使用して実装中に誠実さを保つために、OpenAPI 仕様にも力を入れています。 assert_schema_conform はアライメントをテストし、ミドルウェアはライブの不一致を通知します。これらを組み合わせることで、リグレッションから保護しながらレッド グリーンの実装が可能になります。

モックとプロキシを使用したテスト

最後に、テスト スイートはフラグを使用して、プリズムをモック モードまたはプロキシ モードで実行します。フラグを使用すると、1 種類のテストの作成だけに集中できますが、どちらかのモードで一部のテストをスキップすることになります。速度向上のために、フルスタックが CI で実行されない Windows および macOS 上で模擬テストを使用します。プロキシ テストを使用すると、フラグを追加するだけでスタック全体に対してテストを実行できるため、必要と思われるときはいつでもエンドツーエンドのテストを簡単に実行できます。

すべてをまとめる

スケッチと仕様は、実装で行き詰まることなく、要約を繰り返し進めるのに役立ちます。次に、モックとプロキシは、実装がスケッチと一致していることを確認するのに役立ちます。プロセスを反復し続けることで、各機能の苦痛が軽減され、今月後半に提供するチーム エクスペリエンスを構築する際に非常に感謝しています。

私たちはプロセスを繰り返していきます。皆さんがそこから何かを学べたことを願っていますし、私も皆さんから学びたいと思っています。あなたは何を試しましたか、どこを誇りに思いますか、そして何が不満のままですか?