La creación de funciones CLI a menudo se reduce a:

• Lanzar nuevos puntos finales de API.
• Cree nuevas acciones CLI que necesiten cambios en la API.
• Date cuenta de que se cometieron errores en la API que acabas de lanzar.
• Intenta arreglar la API para esta función sin crear más problemas en el futuro.
• Intente recordar lo que intentaba lograr en la CLI y luego consígalo.  
• IR A: darse cuenta de que se cometieron errores.

Cada paso requiere el anterior y, vaya, hemos reinventado la gestión de proyectos en cascada. Te desgasta el dolor al tratar de superar con gracia los errores hasta que cojeas y te vuelves funcional, pero te retiras mucho antes de lo excepcional. Y no me hagas hablar del mantenimiento del conjunto resultante de “arreglos” y fallos ad hoc.

Estuve allí y lo hice. Sabíamos que necesitábamos dejar atrás el enfoque tipo cascada.

Aquí está la historia de cómo llegamos allí y algunas de las herramientas que nos ayudaron en el camino.

Hacia un comienzo incompleto

Queríamos una iteración rápida y económica hasta que entendiéramos la función y solo entonces comprometernos con una implementación costosa y soporte a largo plazo. Como equipo pequeño, a menudo hacía este proceso de principio a fin y quería centrarme en cada parte por turno. Queríamos falsificar partes de implementación hasta que nos sintiéramos lo suficientemente seguros para hacerlo.

Volviendo al proceso, comienza proponiendo características. Queríamos salir de lo abstracto, pero no si eso significaba una implementación a medias. Lo falsificamos con "bocetos", inspirados en el enfoque de boceto de la CLI de Google Docs que Github describe aquí.

Desafortunadamente, los bocetos estáticos no nos dieron la respuesta que buscábamos. Nuestra CLI cambia la salida con el tiempo, más como una animación que como un dibujo. Para lograr una mayor fidelidad, escribí pequeños programas Ruby para tomar entradas básicas y responder imprimiendo respuestas predeterminadas apropiadas.

Desde entonces, hemos encontrado una manera aún mejor de capturar resultados CLI animados, pero explicarlo requiere un pequeño desvío.

¿Incluso haces pruebas?

Cuando comenzamos a desarrollar nuestra CLI, también queríamos probar casos extremos y detectar regresiones. Encuesté CLI públicas basadas en cobra/bubbletea para buscar ideas y encontré frustrantemente pocas pruebas. Luego nos topamos con la prueba de Charm que nos dio un punto de partida.

Teatest se centra en pruebas de oro, capturando un buen resultado conocido y luego afirmando que los resultados futuros continúan igualándolo. Lo que nos trajo de nuevo, una vez más, a la captura de alta fidelidad de salidas CLI animadas. Teatest nos dio la gran idea de una solución basada en marcos, como un flipbook, sobre la cual hemos construido:

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

Este ejemplo simplificado muestra cómo se vería una salida dorada para un comando de autorización básico. Las líneas horizontales delimitan marcos, con etiquetas que indican el modelo activo. En conjunto, obtenemos una captura de alta fidelidad de la salida incluso cuando se agregan, eliminan o reemplazan líneas.

Usamos una bandera en nuestro conjunto de pruebas para actualizar archivos con las salidas doradas y, de lo contrario, las pruebas fallan si la salida no coincide con los archivos. Esto nos mantiene al tanto de los cambios en los resultados y facilita las revisiones de relaciones públicas al permitirnos comprender cómo debería verse el resultado y si ha cambiado. Nos gusta tanto que planeamos reemplazar nuestros programas de bocetos con resultados de estilo dorado en documentos de Google estilo Github para que podamos capturar tanto animaciones como ideas de estilo.

Con nuestros bocetos anteriores y futuros en mano, volvamos a comenzar con nuevos puntos finales API.

Diseñando API y CLI juntos

Trabajamos en la API y la CLI simultáneamente, porque los mejores diseños para ellas surgen de una estrecha integración. Podemos hacer esto, evitando al mismo tiempo los peligros de la cascada, iterando diseños en contextos más baratos y esperando para implementar hasta que los requisitos se solidifiquen. Para nuestras API, esto significa realizar bocetos con 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

Este ejemplo simplificado muestra cómo se vería un esquema para un comando de autorización básico. Usamos el linter espectral para simplificar el trabajo con estos archivos.

Con un boceto en mano, usamos prism como servidor API simulado mientras implementamos la CLI. Cuando inevitablemente nos damos cuenta de que se cometieron errores, podemos simplemente modificar la especificación y volver a nuestra iteración CLI. Trabajar a este alto nivel nos permite desarrollar la API y la CLI juntas y posponer una implementación costosa hasta que tengamos un mejor conocimiento.

Implementación de API

También nos apoyamos en nuestra especificación OpenAPI para mantenernos honestos durante la implementación utilizando el comité. afirmar_schema_conform prueba la alineación y el middleware nos notifica cualquier discrepancia en vivo. Estos se combinan para permitir la implementación de rojo y verde y al mismo tiempo protegernos de regresiones.

Pruebas con simulacros y proxies

Para completar las cosas, nuestro conjunto de pruebas utiliza indicadores para ejecutar prisma en modo simulado o proxy. Al usar banderas podemos concentrarnos en escribir solo un tipo de prueba, aunque eso significa que nos saltamos algunas pruebas en un modo u otro. Usamos pruebas simuladas para determinar su velocidad y en Windows y macOS donde nuestra pila completa no se ejecuta en CI. Nuestras pruebas de proxy nos permiten ejecutar pruebas en toda nuestra pila simplemente agregando una bandera, lo que facilita la ejecución de pruebas de un extremo a otro siempre que lo consideremos necesario.

Juntándolo todo

Los bocetos y las especificaciones nos ayudan a superar lo abstracto sin tener que atascarnos en la implementación. Luego, los simulacros y los proxy nos ayudan a garantizar que las implementaciones coincidan con los bocetos. Al continuar repitiendo nuestro proceso, cada característica causa menos molestias, lo cual apreciamos profundamente mientras construimos la experiencia de los equipos que ofreceremos a finales de este mes.

Seguiremos repitiendo nuestro proceso, espero que hayas aprendido algo de él y me encantaría aprender de ti. ¿Qué has probado, de qué estás orgulloso y qué sigue siendo frustrante?