Мы в 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 г.