Мы в Supabase любим писать как можно меньше кода, поэтому решили объединить наши модульные тесты с теми же комментариями JSDoc, что и VSCode IntelliSense.
Введение в JSDoc
Если вы никогда раньше не слышали о JSDoc, вы, вероятно, видели его. Это комментарии, которые идут над методом или классом Javascript, например:
/**
* Returns the sum of 2 numbers
* @param {number} a The first number
* @param {number} b The second number
*/
export const sum = (a, b) => {
return a + b
}
Тег @example
JSDoc имеет тег, который показывает разработчику, как использовать задокументированный элемент.
/**
* Returns the sum of 2 numbers
* @param {number} a The first number
* @param {number} b The second number
* @example
* // returns 3
* sum(1, 2)
*/
export const sum = (a, b) => {
return a + b
}
Хотя структура немного отличается, это очень похоже на доктесты Эликсира. Elixir имеет дополнительное преимущество: вы можете использовать эти комментарии для запуска своих тестов:
Поэтому мы решили, что было бы неплохо реализовать ту же функциональность с помощью Javascript: @supabase/doctest-js.
Doctest-JS использует формат, очень похожий на Doctests Elixir, с использованием //=>
для указания возвращаемых значений.
/**
* @example sum(1, 2)
* //=> 3
*/
Доктест-JS
Если вы хотите попробовать это на своем собственном коде, это очень просто:
1. Установите
npm install @supabase/doctest-js
2. Пишите комментарии @example
Создайте @example в стиле JSDoc для любых функций, которые вы хотите протестировать.
Например, создайте файл с именем sum.js
и добавьте этот код:
/**
* Returns the sum of 2 numbers
*
* @example sum(1, 2)
* //=> 3
*/
export const sum = (a, b) => {
return a + b
}
3. Запустите тесты
Импортируйте функцию doctest в свой набор тестов и укажите ей файл.
Например, создайте файл с именем test.js
и добавьте следующий код:
import doctests from '@supabase/doctest-js';
describe('Doctests', () => {
// file paths are relative to root of directory
doctest('sum.js')
})
А затем просто запустите node test
, и вы получите хорошо документированный, протестированный код без необходимости поддерживать какой-либо дополнительный код.
Смотрите и помечайте doctest-js, чтобы быть в курсе новых выпусков.
Вы можете увидеть это в действии в нашей библиотеке postgrest-js:
Первоначально опубликовано на https://dev.to 23 февраля 2020 г.