Мета документа

Доповнити процес тестування майданчиків (програмно-апаратних комплексів) з метою мінімізації наступних ситуацій:

• Відсутність контролю за деплоєм протестованих змін у продакшн з боку майданчиків.

• Мінімізація ситуацій, коли майданчики залишаються без технічної підтримки.

• Посилення тестування API, а не лише UI/UX частини майданчика.

• Спрощення аудиту.

Загальне

На даний момент ми не можемо тестувати кодову базу кожного майданчика і не можемо бути впевненими, що всі клони мають актуальні договори на технічну підтримку від своїх розробників.

Найпростіший спосіб мінімізувати подібні проблеми — це версіонування кодової бази майданчиків і фіксація версії під час тестування.

Вимоги до програмно-апаратних комплексів майданчиків

Ці вимоги стосуються не лише ПЗ майданчиків, а й SELF-HOSTED проєктів, які розробляє Prozorro і які взаємодіють з API ЦБД. Наприклад: портал, mirror-клієнти, адмінка тощо — усе, що знаходиться поза периметром ЦБД.

Версіонування кодової бази

• Кодова база майданчика має підтримувати семантичне версіонування (semver).

• Версіонування має бути наскрізним і не прив’язане до версій ЦБД.

• Кожна релізна зміна, яка поширюється далі, має призводити до збільшення версії згідно з правилами семантичного версіонування.

Надання журналу змін (Change Log)

• Майданчик має надавати список змін у кодовій базі на запит тестувальників Prozorro.Sale у будь-який момент.

• Для спрощення комунікації та аналізу змін рекомендується використовувати Conventional Commits та автоматично генерувати Change Log під час релізів.

Указання версії у запитах до API ЦБД

• Усі запити до API ЦБД мають містити HTTP-заголовок Platform-Version зі значенням поточної версії ПЗ майданчика.

• Це потрібно для перевірки, що в продакшні працює саме протестована версія ПЗ.

API-ендпоінти для версії та статусу ПЗ

Майданчики повинні реалізувати такі JSON API-ендпоінти:

• /api/platform/version — повертає поточну версію ПЗ:
  {"version": "X.X.X"}

• /api/platform/cdb/status — повертає результат запитів до ендпоінтів ЦБД api/auth з валідним токеном авторизації.

Пояснення щодо /api/platform/cdb/status:

Залежно від того, з якими оточеннями ЦБД працює майданчик, відповідь може містити кілька елементів:

{
  "procedure-sandbox.prozorro.sale": {
    "owner": "XXXX",
    "ip": "91.245.78.204",
    "procedures": {
      "alienation-english": ["procedure", "bids"]
    }
  },
  "dgf-procedure-sandbox.prozorro.sale": {
    "owner": "XXXX",
    "ip": "91.245.78.204",
    "procedures": {
      "dgf-dutch": ["procedure", "bids"]
    }
  }
}

Логи запитів до ЦБД

• Усі програмно-апаратні комплекси мають забезпечити логування всіх запитів до API ЦБД.

• Логи мають бути доступними для Prozorro на запит:

  • для непродакшн-оточень — за запитом тестувальників, розробників, DevOps;

  • для продакшн-оточень — лише за офіційним запитом бізнесу (через наявність конфіденційних даних).

У логах обов'язково мають бути:

• дата запиту (у UTC)

• URI запиту з query-параметрами (без чутливої інформації — наприклад, токени)

• HTTP-метод

• статус відповіді API ЦБД

• значення заголовка request-id, який повернув ЦБД

Формат логів:

• бажано — інтерфейс типу Kibana;

• мінімум — текстові файли з можливістю фільтрації за:

  • часовим діапазоном

  • request-id

  • API-ендпоінтом

  • статусом

  • HTTP-методом

Логи повинні бути розділені за оточеннями (sandbox, prod тощо).

Строк зберігання:

• для непродакшн — щонайменше 14 днів;

• для продакшн — щонайменше 30 днів.

Зміни в процесі тестування майданчиків

Під час тестування:

• Тестувальник фіксує версію ПЗ, яку повертає /api/platform/version.

• Якщо заводиться баг — у тікеті вказується ця версія.

• Під час ретесту тестувальник перевіряє, чи змінилася версія. Якщо ні — потрібно перепитати у Майданчика причину (наприклад, змінено лише конфіг у адмінці без зміни коду).

• Після завершення тестування тестувальник фіксує, що певна версія ПЗ протестована та дозволена для продакшну.

Нюанси з версіями ПЗ

• Версія має збільшуватись після тестування, якщо були внесені зміни (навіть не пов’язані з API).

• Але версія на продакшні не може бути нижчою, ніж протестована.

Автоматизація

Після впровадження версіонування можливе створення:

• дашборду для тестувальників з поточними версіями ПЗ, які взаємодіють з ЦБД;

• алертингу, якщо на продакшні використовується версія нижча за протестовану.

Що це дає?

• Розуміння, що ми протестували і що взаємодіє з ЦБД.

• Можливість проводити аудит стану та взаємодії з ЦБД.

• Тестувальник після UI/UX-тестування може перевірити логи запитів до API ЦБД і переконатися в коректній інтеграції.

• Спрощення аналізу нестандартних ситуацій.

• Можливість перевірки токенів доступу і правильності їх використання.

• Основу для подальшої автоматизації процесу.