Тестовый фреймворк для модулей на wb-rules

Цели проекта

Работа с wb-rules для платформы Wiren Board может быть сложной:

• Редактирование в интерфейсе: писать сложные модули в интерфейсе неудобно.
• Тестирование на контроллере: требует заливки кода, моделирования данных, что занимает много времени.
• Отсутствие регрессионного тестирования: при внесении изменений сложно убедиться, что ничего не сломано.

Этот проект решает эти проблемы, предоставляя удобное тестовое окружение:

• Локальное тестирование: писать модули в удобной IDE и тестировать их локально.
• Автоматизация: запуск тестов одной командой.
• Быстрая обратная связь: выполнение тестов занимает всего несколько секунд.
• Поддержка регрессии: тесты фиксируют поведение модулей, предотвращая случайные поломки.

Фреймворк вдохновлён подходом Python Doctest и адаптирован под потребности платформы Wiren Board.

---

Описание

Этот проект предоставляет инструменты для написания и автоматического тестирования модулей wb-rules.

Он включает:

1. test.sh — Bash-скрипт для управления запуском wb-rules.
2. test_gen.js — JavaScript-скрипт для генерации кода тестов по JSDoc вашего модуля.
3. Dockerfile — окружение для выполнения тестов с поддержкой архитектуры ARM.
4. Makefile — удобный способ сборки и запуска тестов.

---

Как это работает?

1. Вы пишете модули для wb-rules в папке src/.
2. Запускаете тесты make.
3. Фреймворк генерирует тесты, сравнивает результаты с ожидаемыми и выводит отчёт.

---

Пример использования

Допустим, у вас есть модуль exampleModule.js:

// exampleModule.js
function add(a, b) {
    return a + b;
}

exports.add = add;

И вы хотите протестировать его.

Использование JsDoc

Для этого перед функцией нужно добавить комментарий в формате JSDoc с @example примерами вызова функции, например так:

// exampleModule.js
/**
 * @example
 * add(2, 3) // 5
 * @example
 * add(10, -5) // 5
 */
function add(a, b) {
    return a + b;
}

exports.add = add;

Функция tests

Если примеры сложные для описыния в JsDoc то можно описать функцию tests без аргументов и эспортировать её. Эту функцию позовёт фреймворк и если в процессе не будет брошени исключений то тесты завершатся успешно.

// exampleModule.js
function add(a, b) {
    return a + b;
}

function tests(){
   if (add(2, 3) <> 5){
      throw Error("Test error")
   }
}
exports.add = add;
exports.tests = tests;

Теперь выполните тесты:

make

Результат:

INFO:  [rule info] Start testing exampleModule in file /etc/wb-rules/exampleModule-tests.js
INFO:  [rule info] PASS: Test 1 in exampleModule
INFO:  [rule info] PASS: Test 2 in exampleModule
INFO:  [rule info] PASS: Test 3 in exampleModule
INFO:  [rule info] PASS: Test 4 in exampleModule
INFO:  all rule files are loaded

Примеры в специальном модуле

---

Структура проекта

├── Dockerfile           # Docker-образ для выполнения тестов
├── Makefile             # Утилита для сборки и запуска контейнера
├── test.sh              # Скрипт управления тестами
├── test_gen.js          # Скрипт генерации тестов
├── mosquitto.conf       # Конфигурация Mosquitto
├── wirenboard.gpg       # GPG-ключ репозитория Wiren Board
└── src/                 # Директория с модулями `wb-rules`

---

Установка и запуск

Требования

• Установленный Docker
• Поддержка архитектуры ARM (или её эмуляция)

Шаги

1. Склонируйте репозиторий:

   git clone git@github.com:ifinik/wb_staff.git
   cd wb_staff

2. Запустите эмуляцию ARM (если требуется):

   docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

3. Соберите и выполните тесты:

   make

Контейнер выполнит тесты и выведет результаты в консоль.

---

Как добавить модуль и тесты?

1. Поместите ваш модуль в папку src/ (например, src/exampleModule.js).

2. Выполните тесты:

   make

---

Makefile

• make — сборка образа и запуск тестов.
• make docker_build — сборка Docker-образа.
• make docker_run — запуск тестов в контейнере.

---

Преимущества

• Быстрое тестирование: полный цикл занимает ~5 секунд.
• Поддержка регрессии: вы всегда знаете, что ничего не сломано.
• IDE-дружественность: пишите код в любимой IDE, а не в веб-интерфейсе.
• Минимальная настройка: готовый Docker-образ с поддержкой ARM.

---

FAQ

Вопрос:

Зачем нужна эта обвязка (Wiren Board, Dockerfile и прочее)? Разве нельзя просто написать юнит-тесты?

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

1. Эмуляция особенностей контроллера: позволяет работать с объектами wb-rules, сохраняя тот же синтаксис и доступные методы, что на реальном устройстве.
2. Унификация окружения: Docker и сопутствующие инструменты позволяют добиться одинакового поведения кода в локальной и продакшен-среде.

---

Вопрос:

Как работает код с обращением к топикам через dev[]?

Ответ: В контейнере запускается MQTT-брокер, который позволяет обращаться к топикам через dev[] и записывать данные. Однако для полноценного тестирования нужно эмулировать запись в топики, что требует дополнительных усилий.

---

Вопрос:

Работает ли создание виртуальных устройств?

Ответ: Да, виртуальные устройства создаются вместе с топиками. Однако, если в них ничего не записывать, они не имеют практической пользы для тестирования.

---

Вопрос:

Можно ли отображать статус виртуальных устройств?

Ответ: Отображение статуса виртуальных устройств в текущей реализации не поддерживается.

---

Вопрос:

Верно ли, что фреймворк ориентирован не только на специфику Wiren Board, а является более общим решением?

Ответ: Хотя фреймворк имеет некоторые особенности, характерные для Wiren Board (например, использование wb-rules и специфические инструменты), его подходы и методология тестирования могут быть адаптированы для других платформ.

---

Вопрос:

Как фреймворк тестирует работу с топиками?

Ответ: Фреймворк поднимает MQTT-брокер для работы с топиками. Однако, если сторонний код не пишет данные в эти топики, требуется эмуляция их заполнения.