Тестирование документации

Deno может выполнять фрагменты кода из комментариев JSDoc и файлов Markdown и запускать их как тесты. Это помогает поддерживать примеры в документации в актуальном состоянии: когда API меняется, устаревшие примеры завершаются с ошибкой в CI, а не вводят читателей в заблуждение.

Примеры блоков кода

/**
 * # Examples
 *
 * ```ts
 * import { assertEquals } from "jsr:@std/assert/equals";
 *
 * const sum = add(1, 2);
 * assertEquals(sum, 3);
 * ```
 */
export function add(a: number, b: number): number {
  return a + b;
}

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

• js
• javascript
• mjs
• cjs
• jsx
• ts
• typescript
• mts
• cts
• tsx

Если идентификатор языка не указан, язык определяется по типу медиа исходного документа, из которого извлечён блок кода.

deno test --doc example.ts

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

import { assertEquals } from "jsr:@std/assert/equals";
import { add } from "file:///path/to/example.ts";

Deno.test("example.ts$4-10.ts", async () => {
  const sum = add(1, 2);
  assertEquals(sum, 3);
});

Затем он будет запущен как отдельный модуль в том же каталоге, что и документируемый модуль.

Экспортированные элементы импортируются автоматически

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

Предположим, у нас есть следующий модуль:

/**
 * # Examples
 *
 * ```ts
 * import { assertEquals } from "jsr:@std/assert/equals";
 *
 * const sum = add(ONE, getTwo());
 * assertEquals(sum, 3);
 * ```
 */
export function add(a: number, b: number): number {
  return a + b;
}

export const ONE = 1;
export default function getTwo() {
  return 2;
}

Он будет преобразован в следующий тестовый пример:

import { assertEquals } from "jsr:@std/assert/equals";
import { add, ONE }, getTwo from "file:///path/to/example.ts";

Deno.test("example.ts$4-10.ts", async () => {
  const sum = add(ONE, getTwo());
  assertEquals(sum, 3);
});

Хешбанг и ограниченные разрешения

Если пример кода начинается с хешбанга, он проверяется на соответствие поддерживаемым флагам Deno CLI, а флаги разрешений передаются в сгенерированный Deno.test.

/**
 * Prints the value of an environment variable.
 *
 * ```ts
 * #!/usr/bin/env -S deno run --allow-env=MY_ENV_VAR
 * console.log(Deno.env.get("MY_ENV_VAR"));
 * ```
 */

Ниже описана интерпретация каждого флага разрешений:

Пропуск блоков кода

Можно пропустить выполнение блоков кода, добавив атрибут ignore.

/**
 * This code block will not be run.
 *
 * ```ts ignore
 * await sendEmail("deno@example.com");
 * ```
 */
export async function sendEmail(to: string) {
  // send an email to the given address...
}