npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@spec-box/sync

v1.0.0

Published

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

Downloads

79

Readme

@spec-box/sync

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

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

  1. Установите пакет @spec-box/sync из внешнего npm
    npm i @spec-box/sync --registry=https://registry.npmjs.org -D
  2. Создайте конфигурационный файл .tms.json:
    {
        "api": {
            "host": "http://localhost:5059",
            "project": "id"
        },
        "yml": {
            "files": [
                "tests/unit/**/*.unit.testpalm.yml"
            ]
        }
    }
  3. Запустите валидацию данных
    npx spec-box validate
  4. Запустите выгрузку
    npx spec-box sync
    Передав опциональный параметр --message, вы можете указать дополнительную информацию, которая будет полезна для понимания контекста выгрузки. Например, вы можете указать название ветки VCS.
    npx spec-box sync --message="my commit message"
  5. Запустите выгрузку статистики о выполнении тестов из отчета Jest (опционально)
    npx spec-box upload-stat
    В базу функциональных требований будет выгружены: дата и время запуска тестов, суммарное количество тестов, суммарное время выполнения (как если бы тесты выполнялись в одном потоке)

Описание функциональности

Формат yml

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

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

feature: Главная страница    # понятное для человека название фичи
description: Пример описания  # описание фичи (опционально)

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

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

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

Уникальный код фичи

Поле code у фичи является обязательным. Оно должно содержать уникальное значение в пределах проекта, по которому можно сослаться на фичу.

Важно: значение поля code может содержать только английские буквы, цифры, знаки - (дефис) и _ (подчеркивание) и должно начинаться с буквы.

В названиях и описаниях фичей и функциональных требований (поля feature, assert и description) вы можете указать код другой фичи, добавив в начало знак $. При запуске валидации данных (команда validate) будет автоматически проверена корректность таких ссылок.

Например:

feature: Страница оформления заказа
code: checkout-page

# в описании ссылка на другую фичу с кодом 'product-card'
description: Пользователь попадает на эту страницу с карточки товара $product-card

specs-unit:
  Выбор адреса доставки:
      # в тексте функционального требования ссылка на другую фичу с кодом 'address-dialog'
    - assert: При нажатии на кнопку "Выбрать адрес" открывается диалог выбора адреса на карте $address-dialog

Мета-информация

Обратите внимание, формат поля code для сущностей мета-информации — такой же, как формат поля code для фичей

Вы можете создать в корне проекта файл .spec-box-meta.yml и описать в нем мета-информацию для фичей: атрбуты и порядок группировки для просмотра в виде дерева.

Вы можете хранить мета-информацию в файле с другим названием. Для этого укажите путь к файлу в конфигурационном файле .tms.json в поле yml => metaPath

Разметка фичей атрибутами

Вы можете размечать фичи атрибутами, чтобы фильтровать и группировать по ним список фичей.

Задайте список атрибутов и их значений в файле .spec-box-meta.yml в поле attributes. Для каждого атрибата и значения нужно указать код (должен быть уникальным в пределах проекта) и отображаемый текст (для просмотра в интерфейсе):

attributes:
  - code: attr1
    title: Пример атрибута 1
    values:
      - code: cats
        title: Кошки
      - code: dogs
        title: Собаки
  - code: attr2
    title: Пример атрибута 2
    values:
      - code: predators
        title: Хищники
      - code: herbivores
        title: Травоядные

После этого вы можете указывать атрибуты для фичей в поле definitions:

feature: Пример названия фичи
code: example-code

# список функциональных требований
# ...

# список атрибутов фичи
definitions:
  attr1:        # код атрибута
    - dogs      # код значения
  attr2:
    - predators # для одного атрибута можно указать несколько значений
    - herbivores

Если вы указали для фичи код атрибута, который не описан в файле .spec-box-meta.yml, то при выгрузке вы увидите сообщение об ошибке. Если вы укажете для фичи значение существующего атрибута, которое не описано в .spec-box-meta.yml, то значение будет выгружено в базу ФТ, в качестве отображаемого текста будет использоваться код значения.

Группировка фичей по атрибутам

Вы можете настраивать варианты группировки фичей по атрибутам для просмотра в структурированном виде. Добавьте в .spec-box-meta.yml поле trees. Для каждого дерева укажите уникальный код, название (отображаемый текст для просмотра в интерфейсе) и список атрибутов для группировки:

attributes:
  # ... список атрибутов
trees:
  - code: ui-structure              # уникальный код
    title: Разбивка по страницам    # название
    group-by:                       # порядок группировки
      - page
      - component

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

Вместе с информацией о функциональных требованиях можно выгружать информацию о том, что их проверка автоматизирована. Для некоторых видов автотестов реализовано автоматическое вычисление признака automationState. На текущий момент поддерживаются jest и storybook.

Jest

Отчет о выполнении тестов можно сформировать, запустив 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> — значение указанного атрибута (человеко-понятное название)

Storybook

Если в сторибуке написана история, то считаем, что она проверяется скриншотным тестом и проверку соответствующего ФТ считаем автоматизированной. В качестве входной информации нужно предоставить файл index.json, который формируется сторибуком при сборке и содержит список историй. Поддерживается Storybook v7 и выше.

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

{
    // ...
    "storybook": {
        // путь к файлу index.json, генерируемого при билде сторибука
        "indexPath": "index.json",

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

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

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

import type { Meta, StoryObj } from '@storybook/react';
import { Cart } from './Cart';

export default {
  title: 'Главная страница/Блок корзины',
  component: Cart,
} as Meta;

export const Default: StoryObj<typeof Cart> = {
  name: 'Отображается количество и общая стоимость товаров в корзине',
  render: () => <Cart />,
};

Если вы укажете в настройках поле publicUrl, то для каждого ФТ, для которого в сторибуке написана история, будет прикреплена ссылка на эту историю.

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

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

{
    "projectPath": "/aaa/bbb", // путь к корневой папке проекта, опционально
    // настройки выгрузки
    "api": {
        "host": "http://localhost:5059",
        "project": "id"
    },
    // уровни ошибок: error / warning / info / off
    "validation": {
        // ссылка на несуществующую фичу
        "feature-missing-link": "error",

        // тест, не описанный в yml
        "jest-unused": "error"
    }
    "yml": {
        // путь к файлу с мета-информацией, относительно корня проекта, опционально
        "metaPath": "./configs/spec-box-meta.yml",

        // настройки хранения в проекте информации о функциональных требоваинях в yml
        "files": [
            // шаблоны путей указываются относительно корня проекта
            "tests/unit/**/*.unit.testpalm.yml"
        ]
    },
    // настройки для сопоставления ФТ с отчетами jest
    "jest": {
        "reportPath": "jest-report.json", // путь к файлу с отчетом о выполнении тестов
        "keys": [ // сегменты идентификатора для сопоставления автотестов с ФТ
            "featureTitle",
            "$sub-component",
            "groupTitle",
            "assertionTitle"
        ]
    }
    // настройки для сопоставления ФТ с историями storybook
    "storybook": {
        "indexPath": "index.json", // путь к файлу index.json, генерируемого при билде сторибука
        "publicUrl": "https://my-dev-domain/storybook", // базовый путь к опубликованному стрибуку, опционально
        "keys": [ // сегменты идентификатора для сопоставления историй из storybook с ФТ
            "featureTitle",
            "$sub-component",
            "groupTitle",
            "assertionTitle"
        ]
    }
}