std/unittest

Этот модуль реализует шаблон, упрощающий создание модульных тестов.

Статус теста и его имя выводятся после любого вывода или отслеживания ошибки.

Тесты могут быть вложенными, однако неудача вложенного теста не помечает родительский тест как неудачный. Настройка и завершение наследуются. Настройка может быть переопределена локально.

Скомпилированные тестовые файлы, а также nim c -r <testfile.nim> завершаются с кодом 0 для успешного выполнения (без неудачных тестов) или 1 для неудачи.

Testament

Вместо unittest, пожалуйста, рассмотрите использование инструмента Testament, который предлагает изоляцию процессов для ваших тестов.

В качестве альтернативы, использование when isMainModule: doAssert conditionHere обычно является гораздо более простым решением для целей тестирования.

Запуск одного теста

Укажите имя теста в качестве аргумента командной строки.

nim c -r test "my test name" "another test"

Можно использовать несколько аргументов.

Запуск одного набора тестов

Укажите имя набора, ограниченное "::".

nim c -r test "my test name::"

Выбор тестов по шаблону

Один "*" может быть использован для подстановки.

Ограничьте конец имени набора "::".

Выполняются тесты, соответствующие любому из аргументов.

nim c -r test fast_suite::mytest1 fast_suite::mytest2
nim c -r test "fast_suite::mytest*"
nim c -r test "auth*::" "crypto::hashing*"
# Run suites starting with 'bug #' and standalone tests starting with '#'
nim c -r test 'bug #*::' '::#*'

Примеры

suite "description for this stuff":
  echo "suite setup: run once before the tests"
  
  setup:
    echo "run before each test"
  
  teardown:
    echo "run after each test"
  
  test "essential truths":
    # give up and stop if this fails
    require(true)
  
  test "slightly less obvious stuff":
    # print a nasty message and move on, skipping
    # the remainder of this block
    check(1 != 1)
    check("asd"[2] == 'd')
  
  test "out of bounds error is thrown on bad access":
    let v = @[1, 2, 3]  # you can do initialization here
    expect(IndexDefect):
      discard v[4]
  
  echo "suite teardown: run once after the tests"

Ограничения/Ошибки

Так как check будет переписывать некоторые выражения для поддержки контрольных точек (а именно, присваивать выражения переменным), некоторые преобразования типов не поддерживаются. Например, check 4.0 == 2 + 2 не сработает. Но doAssert 4.0 == 2 + 2 работает. Убедитесь, что обе стороны оператора (такие как ==, >= и т.д.) имеют одинаковый тип.

Импорты

since, exitprocs, macros, strutils, streams, times, sets, sequtils, os, terminal

Типы

ConsoleOutputFormatter = ref object of OutputFormatter
  ## Have test results printed in color.
  ## Default is `auto` depending on `isatty(stdout)`, or override it with
  ## `-d:nimUnittestColor:auto|on|off`.
  ## 
  ## Deprecated: Setting the environment variable `NIMTEST_COLOR` to `always`
  ## or `never` changes the default for the non-js target to true or false respectively.
  ## Deprecated: the environment variable `NIMTEST_NO_COLOR`, when set, changes the
  ## default to true, if `NIMTEST_COLOR` is undefined.
  ## Set the verbosity of test results.
  ## Default is `PRINT_ALL`, or override with:
  ## `-d:nimUnittestOutputLevel:PRINT_ALL|PRINT_FAILURES|PRINT_NONE`.
  ## 
  ## Deprecated: the `NIMTEST_OUTPUT_LVL` environment variable is set for the non-js target.

Исходный код Изменить

JUnitOutputFormatter = ref object of OutputFormatter

Исходный код Изменить

OutputFormatter = ref object of RootObj

Исходный код Изменить

OutputLevel = enum
  PRINT_ALL,                ## Print as much as possible.
  PRINT_FAILURES,           ## Print only the failed tests.
  PRINT_NONE                 ## Print nothing.

Уровень детализации вывода тестов. Исходный код Изменить

TestResult = object
  suiteName*: string ## Name of the test suite that contains this test case.
                     ## Can be ``nil`` if the test case is not in a suite.
  testName*: string          ## Name of the test case
  status*: TestStatus

Исходный код Изменить

TestStatus = enum
  OK, FAILED, SKIPPED

Статус теста по окончании. Исходный код Изменить

Переменные

abortOnError {.threadvar.}: bool

Установите в значение true, чтобы немедленно выйти при неудаче. По умолчанию значение false, или переопределите с помощью -d:nimUnittestAbortOnError:on|off.

Устарело: также можно переопределить в зависимости от того, установлена ли переменная среды NIMTEST_ABORT_ON_ERROR.

Исходный код Изменить

Процедуры

proc addOutputFormatter(formatter: OutputFormatter) {....raises: [], tags: [],
    forbids: [].}

Исходный код Изменить

proc checkpoint(msg: string) {....raises: [], tags: [], forbids: [].}

Устанавливает контрольную точку, идентифицированную по msg. При неудаче теста выводятся все контрольные точки, встреченные до сих пор. Пример:

checkpoint("Checkpoint A")
check((42, "the Answer to life and everything") == (1, "a"))
checkpoint("Checkpoint B")

выводит "Контрольная точка A" при неудаче.

Исходный код Изменить

proc close(formatter: JUnitOutputFormatter) {....raises: [IOError, OSError],
    tags: [WriteIOEffect], forbids: [].}

Завершает отчет и закрывает базовый поток. Исходный код Изменить

proc defaultConsoleFormatter(): ConsoleOutputFormatter {....raises: [ValueError],
    tags: [ReadEnvEffect], forbids: [].}

Исходный код Изменить

proc delOutputFormatter(formatter: OutputFormatter) {....raises: [], tags: [],
    forbids: [].}

Исходный код Изменить

proc disableParamFiltering() {....raises: [], tags: [], forbids: [].}

отключает фильтрацию тестов с параметрами командной строки Исходный код Изменить

proc newConsoleOutputFormatter(outputLevel: OutputLevel = outputLevelDefault;
                               colorOutput = true): ConsoleOutputFormatter {.
    ...raises: [], tags: [], forbids: [].}

Исходный код Изменить

proc newJUnitOutputFormatter(stream: Stream): JUnitOutputFormatter {.
    ...raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}

Создаёт форматировщик, который записывает отчёт в указанный поток в формате JUnit. Поток stream НЕ закрывается автоматически по завершении тестов, так как форматировщик не может определить, когда все тесты завершены. Вы должны вызвать formatter.close() для финализации отчёта. Исходный код Изменить

proc resetOutputFormatters() {....raises: [], tags: [], forbids: [].}

Исходный код Изменить

Методы

method failureOccurred(formatter: ConsoleOutputFormatter;
                       checkpoints: seq[string]; stackTrace: string) {.
    ...raises: [], tags: [], forbids: [].}

Исходный код Редактировать

method failureOccurred(formatter: JUnitOutputFormatter;
                       checkpoints: seq[string]; stackTrace: string) {.
    ...raises: [], tags: [], forbids: [].}

stackTrace предоставляется только в случае возникновения ошибки из-за исключения. checkpoints никогда nil. Исходный код Редактировать

method failureOccurred(formatter: OutputFormatter; checkpoints: seq[string];
                       stackTrace: string) {.base, ...gcsafe, raises: [], tags: [],
    forbids: [].}

stackTrace предоставляется только в случае возникновения ошибки из-за исключения. checkpoints никогда nil. Исходный код Редактировать

method suiteEnded(formatter: ConsoleOutputFormatter) {....raises: [], tags: [],
    forbids: [].}

Исходный код Редактировать

method suiteEnded(formatter: JUnitOutputFormatter) {....raises: [IOError, OSError],
    tags: [WriteIOEffect], forbids: [].}

Исходный код Редактировать

method suiteEnded(formatter: OutputFormatter) {.base, ...gcsafe, raises: [],
    tags: [], forbids: [].}

Исходный код Редактировать

method suiteStarted(formatter: ConsoleOutputFormatter; suiteName: string) {.
    ...raises: [IOError], tags: [RootEffect, WriteIOEffect], forbids: [].}

Исходный код Редактировать

method suiteStarted(formatter: JUnitOutputFormatter; suiteName: string) {.
    ...raises: [IOError, OSError, ValueError], tags: [WriteIOEffect], forbids: [].}

Исходный код Редактировать

method suiteStarted(formatter: OutputFormatter; suiteName: string) {.base,
    ...gcsafe, raises: [], tags: [], forbids: [].}

Исходный код Редактировать

method testEnded(formatter: ConsoleOutputFormatter; testResult: TestResult) {.
    ...raises: [IOError], tags: [RootEffect, WriteIOEffect], forbids: [].}

Исходный код Редактировать

method testEnded(formatter: JUnitOutputFormatter; testResult: TestResult) {.
    ...raises: [IOError, OSError, ValueError], tags: [TimeEffect, WriteIOEffect],
    forbids: [].}

Исходный код Редактировать

method testEnded(formatter: OutputFormatter; testResult: TestResult) {.base,
    ...gcsafe, raises: [], tags: [], forbids: [].}

Исходный код Редактировать

method testStarted(formatter: ConsoleOutputFormatter; testName: string) {.
    ...raises: [], tags: [], forbids: [].}

Исходный код Редактировать

method testStarted(formatter: JUnitOutputFormatter; testName: string) {.
    ...raises: [], tags: [TimeEffect], forbids: [].}

Исходный код Редактировать

method testStarted(formatter: OutputFormatter; testName: string) {.base, ...gcsafe,
    raises: [], tags: [], forbids: [].}

Исходный код Редактировать

Макросы

macro check(conditions: untyped): untyped

Проверить, истинно ли утверждение или список утверждений. При ошибке выводится полезное сообщение об ошибке и устанавливаются контрольные точки (если outputLevel не PRINT_NONE).

Пример:

import std/strutils

check("AKB48".toLowerAscii() == "akb48")

let teams = {'A', 'K', 'B', '4', '8'}

check:
  "AKB48".toLowerAscii() == "akb48"
  'C' notin teams

Исходный код Редактировать

macro expect(exceptions: varargs[typed]; body: untyped): untyped

Проверить, вызывает ли body исключение, указанное в переданных exceptions. Тест проходит, если поднятое исключение является частью допустимых исключений. В противном случае тест проваливается.

Пример:

import std/[math, random, strutils]
proc defectiveRobot() =
  randomize()
  case rand(1..4)
  of 1: raise newException(OSError, "CANNOT COMPUTE!")
  of 2: discard parseInt("Hello World!")
  of 3: raise newException(IOError, "I can't do that Dave.")
  else: assert 2 + 2 == 5

expect IOError, OSError, ValueError, AssertionDefect:
  defectiveRobot()

Исходный код Редактировать

Шаблоны

template fail()

Вывести найденные контрольные точки и завершить работу, если abortOnError истинно. В противном случае очистить контрольные точки и указать, что тест завершился неудачей (изменить код выхода и состояние теста). Этот шаблон полезен для отладки, но в основном используется во внутреннем использовании. Пример:

checkpoint("Checkpoint A")
complicatedProcInThread()
fail()

выводит "Контрольная точка A" перед завершением.

Исходный код Редактировать

template require(conditions: untyped)

То же, что и check, за исключением того, что любой проваленный тест вызывает немедленное завершение программы. Любые завершающие действия не выполняются, и вывод проваленного теста не генерируется. Исходный код Редактировать

template skip()

Отметить тест как пропущенный. Должно использоваться в случае, когда выполнить тест невозможно по причинам, зависящим от внешней среды, или определенных условий или конфигураций логики приложения. Код теста всё равно выполняется.

if not isGLContextCreated():
  skip()

Исходный код Редактировать

template suite(name, body) {.dirty.}

Объявить набор тестов, идентифицированный name, с необязательной секцией setup и/или teardown.

Набор тестов — это ряд одного или нескольких связанных тестов, которые используют общую фикстуру (setup, teardown). Фикстура выполняется ДЛЯ КАЖДОГО теста.

suite "test suite for addition":
  setup:
    let result = 4
  
  test "2 + 2 = 4":
    check(2+2 == result)
  
  test "(2 + -2) != 4":
    check(2 + -2 != result)
  
  # No teardown needed

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

[Suite] test suite for addition
  [OK] 2 + 2 = 4
  [OK] (2 + -2) != 4

Исходный код Редактировать

template test(name, body) {.dirty.}

Определить отдельный тестовый случай, идентифицированный name.

test "roses are red":
  let roses = "red"
  check(roses == "red")

Вышеприведенный код выводит:

[OK] roses are red

Исходный код Редактировать