Создание функций CLI часто сводится к следующему:

• Выпустить новые конечные точки API.
• Создайте новые действия CLI, требующие изменений API.
• Осознайте, что в API, который вы только что выпустили, были допущены ошибки.
• Постарайтесь исправить API для этой функции, чтобы не создавать новых проблем в будущем.
• Постарайтесь вспомнить, чего вы пытались достичь в CLI, а затем действительно достигните этого.  
• ПЕРЕЙДИТЕ: осознайте, что были допущены ошибки.

Каждый шаг требует предыдущего, и упс, мы заново изобрели водопадное управление проектами. Вы изматываете боль, пытаясь изящно скрыть ошибки, пока не хромаете до функционального состояния, но уходите задолго до исключительного. И не заставляйте меня продолжать поддерживать полученный кластер специальных «исправлений» и недостатков.

Был там, сделал это. Мы знали, что нам нужно отказаться от подхода, напоминающего водопад.

Вот история о том, как мы этого добились, и некоторые инструменты, которые помогли на этом пути.

Начало схематичное

Нам нужна была дешевая и быстрая итерация, пока мы не поймем эту функцию, и только после этого переходим к дорогостоящей реализации и долгосрочной поддержке. Будучи небольшой командой, я часто выполнял этот процесс от начала до конца и хотел поочередно сосредоточиться на каждой части. Мы хотели подделывать части реализации до тех пор, пока не почувствуем себя достаточно уверенно, чтобы это сделать.

Возвращаясь к процессу, он начинается с предложения функций. Мы хотели уйти от абстракции, но не в том случае, если это означало недоработанную реализацию. Мы подделали его с помощью «эскизов», вдохновленных подходом к эскизам CLI Google Docs, который описывает здесь Github.

К сожалению, статические эскизы не дали нам той обратной связи, которую мы хотели. Наш интерфейс командной строки со временем меняет вывод, больше похожий на анимацию, чем на рисунок. Чтобы добиться более высокой точности, я написал небольшие программы на Ruby, которые принимают базовые входные данные и отвечают, печатая соответствующие стандартные ответы.

С тех пор мы нашли еще лучший способ захвата анимированного вывода CLI, но чтобы объяснить это, нужно немного отвлечься.

Вы даже тестируете?

Когда мы начали прорабатывать наш интерфейс командной строки, мы также хотели протестировать крайние случаи и обнаружить регрессии. В поисках идей я исследовал общедоступные интерфейсы командной строки на основе кобры и пузырькового чая и нашел удручающе мало тестов. Затем мы наткнулись на тест Чарма, который дал нам отправную точку.

Teestest фокусируется на золотых тестах, фиксируя заведомо хорошие результаты и затем утверждая, что будущие результаты будут продолжать соответствовать им. Это снова вернуло нас к высокоточному захвату анимированных результатов 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-анализ, позволяя нам понять, как должны выглядеть результаты и изменились ли они. Нам это настолько нравится, что мы планируем заменить наши эскизные программы на выходные данные в золотом стиле в документах Google в стиле Github, чтобы мы могли воплощать идеи как анимации, так и стилей.

Имея в руках наши прошлые и будущие наброски, давайте вернемся к началу работы с новыми конечными точками API.

Совместное проектирование 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

Этот упрощенный пример показывает, как может выглядеть схема для базовой команды авторизации. Мы используем спектральный линтер, чтобы упростить работу с этими файлами.

Имея на руках эскиз, мы затем используем призму в качестве фиктивного сервера API, пока реализуем CLI. Когда мы неизбежно понимаем, что были допущены ошибки, мы можем просто настроить спецификацию и вернуться к нашей итерации CLI. Работа на таком высоком уровне позволяет нам вместе развивать API и CLI и отложить дорогостоящую реализацию до тех пор, пока мы не получим более глубокие знания.

Реализация API

Мы также опираемся на нашу спецификацию OpenAPI, чтобы обеспечить честность во время реализации с использованием комитета. Assert_schema_conform проверяет выравнивание, а промежуточное программное обеспечение уведомляет нас о любых реальных расхождениях. В совокупности они позволяют реализовать красно-зеленый, одновременно защищая нас от регрессов.

Тестирование с помощью моков и прокси

В завершение, наш набор тестов использует флаги для запуска prism в режиме макета или прокси. Используя флаги, мы можем сосредоточиться на написании только одного типа тестов, хотя это означает, что мы пропускаем некоторые тесты в том или ином режиме. Мы используем пробные тесты на их скорость, а также на Windows и macOS, где наш полный стек не работает в CI. Наши прокси-тесты позволяют нам запускать тесты для всего нашего стека, просто добавляя флаг, что позволяет легко запускать сквозное тестирование, когда мы считаем это необходимым.

Собираем все вместе

Эскизы и спецификации помогают нам преодолевать абстрактные идеи, не увязая в реализации. Затем макеты и прокси помогают нам убедиться, что реализации соответствуют эскизам. Продолжая повторять наш процесс, каждая функция вызывает меньше хлопот, что мы глубоко ценим при создании командного опыта, который мы представим позже в этом месяце.

Мы продолжим совершенствовать наш процесс. Надеюсь, вы чему-то научились, и мне бы хотелось поучиться у вас. Что вы пробовали, чем гордитесь, а что по-прежнему расстраивает?