Плагин autotest-plugin для VSCode

Плагин предназначен для автоматического тестирования проектов на nodejs

Для корректной работы плагина требуется наличие следующих утилит:

• jsdoc

  npm install -g jsdoc
  jsdoc -v // для проверки

• nodeunit

  npm install -g nodeunit
  nodeunit -v // для проверки

Инструкция по генерации и установке плагина

npm install -g vsce // эту команду можно не выполнять если пакет vsce был установлен до этого. подробнее https://code.visualstudio.com/docs/extensions/publish-extension
git clone git://git.appcode.pw/autotest-plugin.git
npm install
vsce package

После генерации в корневом каталоге проекта будет создан файл с расширением .vsix. Инструкция по установке плагина тут

Основные функции плагина:

• Создание автоматических тестов
• Автоматическое выполнение
• Вывод отчета о тестировании

Синтаксис для создания автоматических тестов

Автоматические тесты создаются только для файлов javascript и только для проектов nodejs.

Для определения валидности файла применяется проверка на расширение *.js и наличие в синтаксисе exports. module. и других слов присущих коду nodejs

Создание тестов происходит, как для синхронных методов, так и для асинхронных.

!!! Внимание. Для корректного формирования тестов имена классов и методов не должны оканчиваться на Test

Синтаксис для синхронных методов.

Описание метода для создания автотестирования происходит при помощи синтаксиса jsdoc. Пример:

/**
 * сумма двух чисел
 * @unittest (1, 1) == 2
 * @unittest (0, 1) == 1
 * @param {number} a число a
 * @param {number} b число b
 * @returns {number}
 */
exports.sum = function (a, b) {
    return a + b;
}

где @unittest — специальный атрибут, который принимает один параметр (1, 1) == 2, что является условием проверки теста:

• левая сторона  — параметры передаваемые в функцию
• правая сторона — ожидаемый результат после выполнения
• == — условие

Для тестирование модуля применяется следующий синтаксис:

/**
 * тестирование простой функции
 * @param {number} i число
 * @unittest (10) == 5
 */
module.exports = function(i) {
    return i / 2;
}

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

// пример 1
exports.sumTest = function(t) {
    t.equal(mod.sum(1, 1) == 2, true, 'функция sum - сумма двух чисел');
    t.equal(mod.sum(0, 1) == 1, true, 'функция sum - сумма двух чисел');
    t.done();
}
// пример 2
exports.exportsTest = function(t) {
    t.equal(mod(10) == 5, true, 'функция exports - тестирование простой функции');
    t.done();
}

Правило формирования файлов

Например при создании теста для файла ~/resources/index.js автоматически будет создан файл ~/test/resources/index.t.js

•  к наименованию каталога добавляется папка test Является папкой по умолчанию
• В имени файла вместо .js указывается .t.js

Синтаксис для асинхронных методов

Описание данных методом отличается от синхронных тем, что последним параметром в функции должна быть «функция обратного вызова»

/**
 * асинхронный вызов
 * @unittest
 * (10, function(num) { 
 *     [num == 10] 
 * });
 * @unittest
 * (20, function(num) { 
 *     [num == 20] 
 * });
 * @param {number} i число
 * @param {function} callback функция обратного вызова
 */
exports.async = function (i, callback) {
    var id = setTimeout(function () {
        callback(i);
        clearTimeout(id);
    }, 11);
}

где после атрибута @unittest указывается алгоритм проверки

Привило формирования алгоритма проверки для асинхронных функций:

(20, function(num) {
   [num == 20] 
});

• передаются параметры в функцию
• последним параметром должна быть функция обратного вызова
• функция может как возвращать данные так и нет
  • если данные возвращаются, то можно применить проверку, которая обязательно указывается в квадратных скобках
  • если функция ничего не возвращает, то просто указываем []

Пример пустой проверки:

/**
 * асинхронный вызов
 * @unittest
 * (function() { 
 *     [] 
 * });
 * @param {function} callback функция обратного вызова
 */
exports.asyncSimple = function (callback) {
    var id = setTimeout(function () {
        callback();
        clearTimeout(id);
    }, 10);
}

Правило определения синхронной и асинхронной функции:

• если указан атрибут @unittest, и в описание параметров функции нет слова callback, то тест является синхронным
• если при указании атрибута @unittest параметре присутствует функция callback, то тест является асинхронным
• для явного указания, что тест является асинхронным можно указать атрибут @asyncunittest  вместо @unittest

Объявление переменных

@unittest
var fs = require('fs');
(1, 1) == 2

@unittest
var fs = require('fs');
(10, function(num) { 
    [num == 10] 
});

Автоматическое выполнение

Плагин работает по следующему алгоритму:

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

Статусы тестирования:

• Протестировано — все тесты были выполнены
• Тест не пройден — один или несколько тестов не пройдены

Для просмотра результат тестирования можно навести курсор мыши на соответствующие статусы

При наведении на результат теста выводится следующая информация:

• результат тестирования функции
• файл тестирования
• способ создания теста (подробнее о ручном режиме смотреть ниже)

Ручной способ создания теста

Для создания более сложных тестов можно воспользоватся одним из следующих способов:

Создание дополнительного файла

Для этого в каталоге с файла для тестирования создается файл с именем в котором указан номер. Например происходит тестирование файла

~/resources/index.js

значит каталоге уже есть файл

~/test/resources/index.t.js

и к нему мы добавляем следующий файл

~/test/resources/index2.t.js

Таким образом можно добавлять несколько дополнительных файлов

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

/**
 * Тестирование сумма двух чисел
 */
exports.sumTest = function (t) {
    t.equal(mod.sum(3, 4) == 6, true, 'функция sum - сумма двух чисел');
    t.done();
}

где sumTest — это имя тестируемой функции + слово Test Синтаксис для формирования теста применяется от nodeunit (см. выше)

После этого тестирование функции sum произойдет в двух файлах, одним из которых будет автотест, а другой — ручной тест.

Создание файла для тестирования без привязки @unittest

Данный способ позволяет без применения описания @unittest сопоставить метод с тестом, который был создан в ручном режиме.

Например есть метод minus для которого создан тест в ручном режиме:

// описание отсутствует
exports.minus = function (a, b) {
    return a - b;
}

Пример теста в файле для тестирования:

// сопоставление по имени + Test
exports.minusTest = function (t) {
    t.equal(mod.minus(10, 5) == 5, true);
    t.done();
}

Сопоставление происходит по правилу сопоставления имен и наименованию функций.

Выполнение полного тестирования проекта

Тестирование происходит для файлов, которые находятся в каталоге ~/test

Для запуска тестирования можно вызвать команду «Тестирование проекта» при помощи сочетания клавиш CTRL+SHIFT+P, либо вызвать напрямую CTRL+ALT+T

Выполнение операции может занимать некоторое время. Статус выполнения можно отслеживать внизу.

После завершения тестирования будет создан отчет, в котором будут выведены методы с не пройденным тестированием.

Отчет содержит следующую информацию:

• информация в каком тесте произошла ошибка
• продолжительность выполнения тестирования в разных каталогах

Если результат тестирования будет без ошибок, то будет выведено соответствующее сообщение и отчет построен не будет.

Настройки проекта

Плагин поддерживает следующие настройки:

• unittest.folder: string — папка по умолчанию для хранения файлов для тестирования. По умолчанию папка test
• unittest.extension: string — расширение файла, которое применяется к файлу с  тестированием. По умолчанию .t.js
• unittest.ignore: string[] — указывается список папок для игнорирования тестирования

Для переопределения настроек по умолчанию используется папка .vscode, которую нужно создать в корневом каталоге проекта. Далее в этой папке создается файл settings.json. Этот файл может быть уже создан, так как он предназначен для стандартного механизма переопределения настроек vscode.

Открываем файл и в формате json указывает настройки для переопределения.

Применение глобальных переменных

Для упрощения написания тестов под nodejs доступен механизм для указания глобальных переменных:

• __rootpath — равен корневому каталогу

Пример

/**
 * подмена
 * @unittest (__rootpath) == true
 */
exports.root = function (path) {
    return true;
}

Результат созданного тестирования

var mod = require('../../resources/node-replace.js');
var pth = require('path');
var join = pth.join;

/**
 * Тестирование подмена
 */
exports.rootTest = function(t) {
    t.equal(mod.root(join(__dirname, "../../")) == true, true, 'функция root - подмена');
    t.done();
}

Код __rootpath был преобразован в join(__dirname, «../../»)

Объявление переменных в шапке файла (тестирования)

Пример для nodejs

/**
 * @file /resources/node-file.js
 * @project autotest-module
 * @author Александр
 * @unittestheader
 * var str = 'Hello';
 */

/**
 * @file /resources/Panel.js
 * @project autotest-module
 * @author Александр
 * @unittestheader
 * var str = 'Hello World!!!';
 */

Дополнительная документация модулей:

• http://docs.appcode.pw/projects?project=autotest-module
• http://docs.appcode.pw/projects?project=autotest-plugin