@spec-box/sync NPM

@spec-box/sync

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

Быстрый старт

Установите пакет @spec-box/sync из внешнего npm
```
npm i @spec-box/sync --registry=https://registry.npmjs.org -D
```

Создайте конфигурационный файл .tms.json:

{
    "api": {
        "host": "http://localhost:5059",
        "project": "id"
    },
    "yml": {
        "files": [
            "tests/unit/**/*.unit.testpalm.yml"
        ]
    }
}

Запустите выгрузку
```
npx spec-box sync
```

Формат yml

Каждый yml файл описывает функциональные требования отдельной фичи (целостного функционального блока) проекта. Для фичи указываются: уникальный код (по которму можно сослатсья на нее), название, дополнительная мета-информация (атрибуты) и список функциональных требований, объединенных в группы.

Пример описания ФТ в yml файле:

feature: Главная страница   # понятное для человека название фичи
code: home-page             # уникальный (в пределах проекта) код фичи, по которому можно на не ссылаться

# список функциональных требований (утверждений о продукте), объединенных в группы
specs-unit:
  Промо-блок:
    - assert: Отображается "карусель" со слайдами
    - assert: Для каждого слайда отображается заголовок, описание и фото, значения которых пришли с бэкенда

  Блок корзины:
    - assert: Отображается количество и общая стоимость товаров в корзине
    - assert: Отображается кнопка "Оформить заказ", при нажати пользователь переходит на страницу оформления заказа

# список атрибутов фичи
definitions:
  priority:
    - normal
  component:
    - common # для одного атрибута можно указать несколько значений
    - ui

Автоматическое определение признака isAutomated

Вместе с информацией о функциональных требованиях можно выгружать информацию о том, что их проверка автоматизирована. Определение автоматизированных ФТ выполняется автоматически, на основе информации об отчете jest в формате json. Отчет о выполнении тестов можно сформировать, запустив jest с параметром --json, например:

jest --json --outputFile=jest-report.json

Чтобы добавить в выгрузку ФТ информацию из отчета jest, добавьте в корень конфигурационного файла секцию "jest":

{
    // ...
    "jest": {
        // путь к файлу с отчетом о выполнении тестов
        "reportPath": "jest-report.json",

        // сегменты идентификатора для сопоставления автотестов с ФТ
        "keys": ["featureTitle", "groupTitle", "assertionTitle"]
    }

Для каждого ФТ, описанного в yml файлах проекта, будет сформирован уникальный идентификатор на основе поля "keys". Если в отчете jest есть тест, полное имя которого совпадает с идентификатором ФТ, то считается, что проверка этого ФТ — автоматизирована.

Например, если в проекте есть yml файл с содержимым, указанным выше и поле "keys" в разделе "jest" конфигурационного файла имеет значение ["featureTitle", "groupTitle", "assertionTitle"], то указанный ниже тест будет сопоставлен с ФТ "Отображается количество и общая стоимость товаров в корзине":

describe('Главная страница', () => {
    describe('Блок корзины', () => {
        test('Отображается количество и общая стоимость товаров в корзине', () => {
            // ...
        });
    });
});

В качестве частей идентификатора допустимо указывать следующие значения:

"featureTitle" — название фичи
"featureCode" — уникальный код фичи
"groupTitle" — название группы ФТ
"assertionTitle" — название ФТ
"filePath" — путь к yml файлу, относительно корня проекта
"fileName" — название yml файла без расширения (от начала до первого символа .)
@<attribute> — значение указанного атрибута (идентификатор значения)
$<attribute> — значение указанного атрибута (человеко-понятное название)

Формат конфига

Ниже указаны все возможные параметры конфигурационного файла:

{
    "projectPath": "/aaa/bbb", // путь к корневой папке проекта, опционально
    // настройки выгрузки
    "api": {
        "host": "http://localhost:5059",
        "project": "id"
    },
    "yml": {
        // настройки хранения в проекте информации о функциональных требоваинях в yml
        "files": [
            "tests/unit/**/*.unit.testpalm.yml"
        ],
        // список доступных атрибутов и их значений с человеко-понятными названиями
        "attributes": [
            {
                "code": "example",
                "title": "Пример атрибута",
                "values": [
                    {
                        "code": "aaa",
                        "title": "Тестовое значение"
                    },
                    // ...
                ]
            },
            // ...
        ]
    },
    // настройки для сопоставления ФТ с отчетами jest
    "jest": {
        "reportPath": "jest-report.json", // путь к файлу с отчетом о выполнении тестов
        "keys": [ //
            "featureTitle",
            "$sub-component",
            "groupTitle",
            "assertionTitle"
        ]
    }
}