Das Erstellen von CLI-Funktionen läuft oft auf Folgendes hinaus:

• Neue API-Endpunkte veröffentlichen.
• Erstellen Sie neue CLI-Aktionen, die die API-Änderungen erfordern.
• Erkennen Sie, dass in der API, die Sie gerade veröffentlicht haben, Fehler gemacht wurden.
• Versuchen Sie, die API für diese Funktion zu reparieren, ohne in Zukunft weitere Probleme zu verursachen.
• Versuchen Sie sich daran zu erinnern, was Sie mit der CLI erreichen wollten, und erreichen Sie es dann tatsächlich.  
• GOTO: erkennen, dass Fehler gemacht wurden.

Jeder Schritt erfordert den vorherigen und ups, wir haben das Wasserfall-Projektmanagement neu erfunden. Sie werden von dem Schmerz zermürbt, der versucht, Fehler anmutig zu überbrücken, bis Sie funktionsfähig werden, sich aber lange vor dem Ausnahmezustand verabschieden. Und lassen Sie mich nicht damit anfangen, die resultierende Ansammlung von Ad-hoc-„Korrekturen“ und Warzen aufrechtzuerhalten.

Ich war dort, habe das getan. Wir wussten, dass wir den Wasserfall-Ansatz hinter uns lassen mussten.

Hier ist die Geschichte, wie wir dorthin gelangt sind und einige der Tools, die uns dabei geholfen haben.

Der Start war lückenhaft

Wir wollten eine kostengünstige und schnelle Iteration, bis wir die Funktion verstanden haben, und uns erst dann auf eine teure Implementierung und langfristigen Support festlegen. Als kleines Team habe ich diesen Prozess oft Ende für Ende durchgeführt und wollte mich nacheinander auf jeden Teil konzentrieren. Wir wollten Implementierungsteile fälschen, bis wir uns sicher genug fühlten, es zu schaffen.

Um auf den Prozess zurückzukommen: Er beginnt mit dem Vorschlagen von Funktionen. Wir wollten aus dem Abstrakten herauskommen, aber nicht, wenn dies eine unausgegorene Umsetzung bedeutete. Wir haben es mit „Skizzen“ vorgetäuscht, inspiriert vom Google Docs CLI-Skizzen-Ansatz, den Github hier beschreibt.

Leider haben uns statische Skizzen nicht ganz das gewünschte Feedback gegeben. Unsere CLI verändert die Ausgabe im Laufe der Zeit und ähnelt eher einer Animation als einer Zeichnung. Um eine höhere Wiedergabetreue zu erreichen, habe ich kleine Ruby-Programme geschrieben, die grundlegende Eingaben aufnehmen und darauf reagieren, indem sie entsprechende vorgefertigte Antworten ausdrucken.

Seitdem haben wir eine noch bessere Möglichkeit gefunden, animierte CLI-Ausgaben zu erfassen, aber um das zu erklären, ist ein kleiner Umweg erforderlich.

Testen Sie überhaupt?

Als wir mit der Ausarbeitung unserer CLI begannen, wollten wir auch Randfälle testen und Regressionen erkennen. Ich habe öffentliche CLIs auf Cobra/Bubbletea-Basis untersucht, um nach Ideen zu suchen, und habe frustrierend wenige Tests gefunden. Dann stießen wir zufällig auf den Teatest von Charm, der uns einen Ausgangspunkt gab.

Teatest konzentriert sich auf goldene Tests, bei denen ein bekanntermaßen gutes Ergebnis erfasst und dann bestätigt wird, dass zukünftige Ergebnisse weiterhin damit übereinstimmen. Das brachte uns wieder einmal zurück zur High-Fidelity-Erfassung animierter CLI-Ausgaben. Teatest brachte uns auf die großartige Idee einer rahmenbasierten Lösung, wie einem Daumenkino, auf der wir aufgebaut haben:

─── 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]

Dieses vereinfachte Beispiel zeigt, wie eine goldene Ausgabe für einen einfachen Autorisierungsbefehl aussehen könnte. Die horizontalen Linien grenzen Rahmen ab, wobei Beschriftungen das aktive Modell angeben. Zusammengenommen erhalten wir eine hochauflösende Erfassung der Ausgabe, selbst wenn Zeilen hinzugefügt, entfernt oder ersetzt werden.

Wir verwenden in unserer Testsuite ein Flag, um Dateien mit den goldenen Ausgaben zu aktualisieren. Andernfalls schlagen die Tests fehl, wenn die Ausgabe nicht mit den Dateien übereinstimmt. Dies hält uns über Ausgabeänderungen auf dem Laufenden und erleichtert PR-Überprüfungen, indem es uns ermöglicht, zu verstehen, wie die Ausgabe aussehen sollte und ob sie sich geändert hat. Es gefällt uns so gut, dass wir planen, unsere Skizzenprogramme durch die Ausgabe im Golden-Style in Google Docs im Github-Stil zu ersetzen, damit wir sowohl Animations- als auch Stilideen erfassen können.

Mit unseren einmaligen und zukünftigen Skizzen in der Hand kehren wir zu den ersten Schritten mit neuen API-Endpunkten zurück.

API und CLI gemeinsam entwerfen

Wir arbeiten gleichzeitig an der API und der CLI, da die besten Designs dafür aus einer engen Integration entstehen. Wir sind in der Lage, dies zu tun und gleichzeitig die Gefahren des Wasserfalls zu vermeiden, indem wir Designs in günstigeren Kontexten iterieren und mit der Implementierung warten, bis sich die Anforderungen verfestigen. Für unsere APIs bedeutet dies das Skizzieren mit 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

Dieses vereinfachte Beispiel zeigt, wie ein Schema für einen einfachen Autorisierungsbefehl aussehen könnte. Wir verwenden den Spectral Linter, um die Arbeit an diesen Dateien zu vereinfachen.

Mit einer Skizze in der Hand verwenden wir Prisma dann als simulierten API-Server, während wir die CLI implementieren. Wenn wir unweigerlich feststellen, dass Fehler gemacht wurden, können wir einfach die Spezifikation optimieren und zu unserer CLI-Iteration zurückkehren. Die Arbeit auf diesem hohen Niveau ermöglicht es uns, die API und die CLI gemeinsam weiterzuentwickeln und die kostspielige Implementierung aufzuschieben, bis wir bessere Kenntnisse haben.

APIs implementieren

Wir stützen uns auch auf unsere OpenAPI-Spezifikation, um bei der Implementierung mithilfe des Ausschusses ehrlich zu bleiben. affirm_schema_conform testet die Ausrichtung und die Middleware benachrichtigt uns über alle Live-Diskrepanzen. Diese ermöglichen zusammen eine Rot-Grün-Implementierung und schützen uns gleichzeitig vor Rückschritten.

Testen mit Mocks und Proxys

Um das Ganze abzurunden, verwendet unsere Testsuite Flags, um Prism entweder im Mock- oder Proxy-Modus auszuführen. Durch die Verwendung von Flags können wir uns auf das Schreiben nur einer Art von Tests konzentrieren, obwohl dies bedeutet, dass wir einige Tests in dem einen oder anderen Modus überspringen. Wir verwenden Mock-Tests wegen ihrer Geschwindigkeit und unter Windows und macOS, wo unser vollständiger Stack nicht in CI läuft. Mit unseren Proxy-Tests können wir Tests für unseren gesamten Stack ausführen, indem wir einfach ein Flag hinzufügen. So können wir ganz einfach End-to-End-Tests durchführen, wann immer wir es für notwendig halten.

Alles zusammenbringen

Skizzen und Spezifikationen helfen uns, über die Zusammenfassung hinaus zu iterieren, ohne uns bei der Implementierung zu verzetteln. Dann helfen uns Mocks und Proxys dabei, sicherzustellen, dass die Implementierungen mit den Skizzen übereinstimmen. Durch die kontinuierliche Iteration unseres Prozesses verursacht jede Funktion weniger Probleme, was wir beim Aufbau der Teams-Erfahrung, die wir später in diesem Monat liefern werden, sehr zu schätzen wissen.

Wir werden unseren Prozess weiter wiederholen. Ich hoffe, Sie haben etwas daraus gelernt und ich würde gerne von Ihnen lernen. Was haben Sie versucht, worauf sind Sie stolz und was bleibt frustrierend?