Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Как писать тесты

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

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

Давайте рассмотрим возможности, которые Rust предоставляет специально для написания тестов, реализующих эти действия, включая атрибут test, несколько макросов и атрибут should_panic.

Структура тестовых функций

В самом простом случае тест в Rust — это функция, аннотированная атрибутом test. Атрибуты — это метаданные о фрагментах кода Rust; один из примеров — это атрибут derive, который мы использовали со структурами в главе 5. Чтобы превратить функцию в тестовую, добавьте #[test] в строке перед fn. Когда вы запускаете свои тесты командой cargo test, Rust собирает бинарный файл запуска тестов, который запускает аннотированные функции и сообщает, проходит ли каждая тестовая функция или терпит неудачу.

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

Мы исследуем некоторые аспекты работы тестов, экспериментируя с шаблонным тестом, прежде чем фактически тестировать какой-либо код. Затем мы напишем несколько реальных тестов, которые вызывают код, который мы написали, и проверяют, что его поведение корректно.

Давайте создадим новый библиотечный проект с именем adder, который будет складывать два числа:

$ cargo new adder --lib
     Created library `adder` project
$ cd adder

Содержимое файла src/lib.rs в вашей библиотеке adder должно выглядеть как в листинге 11-1.

Имя файла: src/lib.rs
pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}
Листинг 11-1: Код, автоматически сгенерированный командой cargo new

Файл начинается с примера функции add, чтобы у нас было что тестировать.

Пока сосредоточимся исключительно на функции it_works. Обратите внимание на аннотацию #[test]: этот атрибут указывает, что это тестовая функция, поэтому средство запуска тестов знает, что эту функцию нужно рассматривать как тест. У нас также могут быть не-тестовые функции в модуле tests для настройки общих сценариев или выполнения общих операций, поэтому нам всегда нужно указывать, какие функции являются тестами.

Тело примерной функции использует макрос assert_eq!, чтобы проверить, что result, содержащий результат вызова add с аргументами 2 и 2, равен 4. Это утверждение служит примером формата типичного теста. Давайте запустим его, чтобы увидеть, что этот тест проходит.

Команда cargo test запускает все тесты в нашем проекте, как показано в листинге 11-2.

$ cargo test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.57s
     Running unittests src/lib.rs (target/debug/deps/adder-01ad14159ff659ab)

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests adder

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Листинг 11-2: Вывод при запуске автоматически сгенерированного теста

Cargo скомпилировал и запустил тест. Мы видим строку running 1 test. Следующая строка показывает имя сгенерированной тестовой функции tests::it_works, и что результат выполнения этого теста — ok. Общая сводка test result: ok. означает, что все тесты прошли, а фрагмент, который читается как 1 passed; 0 failed, суммирует количество прошедших и неудачных тестов.

Можно пометить тест как игнорируемый, чтобы он не запускался в конкретном случае; мы рассмотрим это в разделе «Игнорирование тестов, если они не запрошены специально» далее в этой главе. Поскольку мы не делали этого здесь, в сводке отображается 0 ignored. Мы также можем передать аргумент команде cargo test, чтобы запускать только тесты, имя которых совпадает со строкой; это называется фильтрацией, и мы рассмотрим это в разделе «Запуск подмножества тестов по имени». Здесь мы не фильтровали запускаемые тесты, поэтому в конце сводки отображается 0 filtered out.

Статистика 0 measured предназначена для бенчмарк-тестов, которые измеряют производительность. Бенчмарк-тесты на момент написания доступны только в ночной сборке Rust. См. документацию о бенчмарк-тестах, чтобы узнать больше.

Следующая часть вывода тестов, начинающаяся с Doc-tests adder, относится к результатам любых документационных тестов. У нас пока нет документационных тестов, но Rust может компилировать любые примеры кода, которые появляются в нашей документации API. Эта возможность помогает поддерживать документацию и код в синхронизации! Мы обсудим, как писать документационные тесты, в разделе «Комментарии документации как тесты» главы 14. Пока мы будем игнорировать вывод Doc-tests.

Давайте начнём настраивать тест под наши собственные нужды. Сначала изменим имя функции it_works на другое, например exploration, вот так:

Имя файла: src/lib.rs

pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn exploration() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

Затем снова запустите cargo test. Теперь вывод показывает exploration вместо it_works:

$ cargo test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.59s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 1 test
test tests::exploration ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests adder

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Теперь мы добавим ещё один тест, но на этот раз мы сделаем тест, который терпит неудачу! Тесты терпят неудачу, когда что-то в тестовой функции паникует. Каждый тест запускается в новом потоке, и когда главный поток видит, что тестовый поток завершился, тест помечается как неудачный. В главе 9 мы говорили о том, что простейший способ вызвать панику — вызвать макрос panic!. Введите новый тест как функцию с именем another, чтобы ваш файл src/lib.rs выглядел как в листинге 11-3.

Имя файла: src/lib.rs
pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn exploration() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }

    #[test]
    fn another() {
        panic!("Make this test fail");
    }
}
Листинг 11-3: Добавление второго теста, который завершится неудачей, потому что мы вызываем макрос panic!

Снова запустите тесты с помощью cargo test. Вывод должен выглядеть как в листинге 11-4, который показывает, что наш тест exploration прошёл, а another завершился неудачей.

$ cargo test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.72s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 2 tests
test tests::another ... FAILED
test tests::exploration ... ok

failures:

---- tests::another stdout ----

thread 'tests::another' (6019162) panicked at src/lib.rs:17:9:
Make this test fail
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::another

test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`
Листинг 11-4: Результаты тестов, когда один тест проходит, а другой терпит неудачу

Вместо ok строка test tests::another показывает FAILED. Появляются два новых раздела между отдельными результатами и сводкой: первый отображает подробную причину для каждого неудачного теста. В данном случае мы получаем сведения о том, что tests::another завершился неудачей, потому что он запаниковал с сообщением Make this test fail в строке 17 файла src/lib.rs. Следующий раздел перечисляет только имена всех неудачных тестов, что полезно, когда есть много тестов и много подробного вывода о неудачных тестах. Мы можем использовать имя неудачного теста, чтобы запустить только этот тест и отладить его более легко; мы поговорим подробнее о способах запуска тестов в разделе «Управление запуском тестов».

Строка сводки отображается в конце: в целом, наш результат теста — FAILED. У нас был один прошедший тест и один неудачный.

Теперь, когда вы увидели, как выглядят результаты тестов в разных сценариях, давайте рассмотрим некоторые макросы, кроме panic!, которые полезны в тестах.

Проверка результатов с помощью assert!

Макрос assert!, предоставляемый стандартной библиотекой, полезен, когда нужно убедиться, что некоторое условие в тесте вычисляется в true. Мы передаём макросу assert! аргумент, который вычисляется в логическое значение. Если значение — true, ничего не происходит и тест проходит. Если значение — false, макрос assert! вызывает panic!, чтобы вызвать неудачу теста. Использование макроса assert! помогает проверить, что наш код работает так, как мы задумали.

В главе 5, листинге 5-15, мы использовали структуру Rectangle и метод can_hold, которые повторены здесь в листинге 11-5. Давайте поместим этот код в файл src/lib.rs, а затем напишем для него несколько тестов с использованием макроса assert!.

Имя файла: src/lib.rs
#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}
Листинг 11-5: Структура Rectangle и её метод can_hold из главы 5

Метод can_hold возвращает логическое значение, что означает, что это идеальный случай для использования макроса assert!. В листинге 11-6 мы пишем тест, который упражняет метод can_hold, создавая экземпляр Rectangle с шириной 8 и высотой 7 и утверждая, что он может содержать другой экземпляр Rectangle с шириной 5 и высотой 1.

Имя файла: src/lib.rs
#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn larger_can_hold_smaller() {
        let larger = Rectangle {
            width: 8,
            height: 7,
        };
        let smaller = Rectangle {
            width: 5,
            height: 1,
        };

        assert!(larger.can_hold(&smaller));
    }
}
Листинг 11-6: Тест для can_hold, который проверяет, действительно ли больший прямоугольник может содержать меньший прямоугольник

Обратите внимание на строку use super::*; внутри модуля tests. Модуль tests — это обычный модуль, который следует обычным правилам видимости, которые мы рассмотрели в главе 7 в разделе «Пути для ссылки на элемент в дереве модулей». Поскольку модуль tests является внутренним модулем, нам нужно внести тестируемый код из внешнего модуля в область видимости внутреннего модуля. Мы используем здесь glob, поэтому всё, что мы определяем во внешнем модуле, доступно этому модулю tests.

Мы назвали наш тест larger_can_hold_smaller, и мы создали два экземпляра Rectangle, которые нам нужны. Затем мы вызвали макрос assert! и передали ему результат вызова larger.can_hold(&smaller). Это выражение должно вернуть true, поэтому наш тест должен пройти. Давайте выясним!

$ cargo test
   Compiling rectangle v0.1.0 (file:///projects/rectangle)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.66s
     Running unittests src/lib.rs (target/debug/deps/rectangle-6584c4561e48942e)

running 1 test
test tests::larger_can_hold_smaller ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests rectangle

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Он действительно проходит! Давайте добавим ещё один тест, на этот раз утверждая, что меньший прямоугольник не может содержать больший прямоугольник:

Имя файла: src/lib.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn larger_can_hold_smaller() {
        // --snip--
        let larger = Rectangle {
            width: 8,
            height: 7,
        };
        let smaller = Rectangle {
            width: 5,
            height: 1,
        };

        assert!(larger.can_hold(&smaller));
    }

    #[test]
    fn smaller_cannot_hold_larger() {
        let larger = Rectangle {
            width: 8,
            height: 7,
        };
        let smaller = Rectangle {
            width: 5,
            height: 1,
        };

        assert!(!smaller.can_hold(&larger));
    }
}

Поскольку правильный результат функции can_hold в этом случае — false, нам нужно инвертировать этот результат, прежде чем передать его в макрос assert!. В результате наш тест пройдёт, если can_hold вернёт false:

$ cargo test
   Compiling rectangle v0.1.0 (file:///projects/rectangle)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.66s
     Running unittests src/lib.rs (target/debug/deps/rectangle-6584c4561e48942e)

running 2 tests
test tests::larger_can_hold_smaller ... ok
test tests::smaller_cannot_hold_larger ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests rectangle

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Два теста проходят! Теперь давайте посмотрим, что произойдёт с результатами наших тестов, когда мы внесём ошибку в наш код. Мы изменим реализацию метода can_hold, заменив знак «больше» (>) на знак «меньше» (<) при сравнении ширин:

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

// --snip--
impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width < other.width && self.height > other.height
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn larger_can_hold_smaller() {
        let larger = Rectangle {
            width: 8,
            height: 7,
        };
        let smaller = Rectangle {
            width: 5,
            height: 1,
        };

        assert!(larger.can_hold(&smaller));
    }

    #[test]
    fn smaller_cannot_hold_larger() {
        let larger = Rectangle {
            width: 8,
            height: 7,
        };
        let smaller = Rectangle {
            width: 5,
            height: 1,
        };

        assert!(!smaller.can_hold(&larger));
    }
}

Теперь выполнение тестов выдаёт следующее:

$ cargo test
   Compiling rectangle v0.1.0 (file:///projects/rectangle)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.66s
     Running unittests src/lib.rs (target/debug/deps/rectangle-6584c4561e48942e)

running 2 tests
test tests::larger_can_hold_smaller ... FAILED
test tests::smaller_cannot_hold_larger ... ok

failures:

---- tests::larger_can_hold_smaller stdout ----

thread 'tests::larger_can_hold_smaller' (6020788) panicked at src/lib.rs:28:9:
assertion failed: larger.can_hold(&smaller)
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::larger_can_hold_smaller

test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

Наши тесты обнаружили ошибку! Поскольку larger.width равно 8, а smaller.width равно 5, сравнение ширин в can_hold теперь возвращает false: 8 не меньше 5.

Проверка равенства с помощью assert_eq! и assert_ne!

Распространённый способ проверить функциональность — проверить равенство между результатом тестируемого кода и значением, которое вы ожидаете получить от кода. Это можно сделать с помощью макроса assert!, передав ему выражение с оператором ==. Однако это настолько распространённый вид теста, что стандартная библиотека предоставляет пару макросов — assert_eq! и assert_ne! — для выполнения этой проверки более удобно. Эти макросы сравнивают два аргумента на равенство или неравенство соответственно. Они также выведут оба значения, если утверждение не выполняется, что упрощает понимание причины неудачи теста; напротив, макрос assert! только указывает, что он получил значение false для выражения ==, без вывода значений, которые привели к значению false.

В листинге 11-7 мы пишем функцию с именем add_two, которая добавляет 2 к своему параметру, а затем тестируем эту функцию с помощью макроса assert_eq!.

Имя файла: src/lib.rs
pub fn add_two(a: u64) -> u64 {
    a + 2
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_adds_two() {
        let result = add_two(2);
        assert_eq!(result, 4);
    }
}
Листинг 11-7: Тестирование функции add_two с помощью макроса assert_eq!

Давайте проверим, что он проходит!

$ cargo test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 1 test
test tests::it_adds_two ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests adder

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Мы создаём переменную с именем result, которая содержит результат вызова add_two(2). Затем мы передаём result и 4 в качестве аргументов макросу assert_eq!. Строка вывода для этого теста — test tests::it_adds_two ... ok, а текст ok указывает, что наш тест прошёл!

Давайте внесём ошибку в наш код, чтобы увидеть, как выглядит assert_eq!, когда он терпит неудачу. Изменим реализацию функции add_two, чтобы она добавляла 3:

pub fn add_two(a: u64) -> u64 {
    a + 3
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_adds_two() {
        let result = add_two(2);
        assert_eq!(result, 4);
    }
}

Снова запустите тесты:

$ cargo test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 1 test
test tests::it_adds_two ... FAILED

failures:

---- tests::it_adds_two stdout ----

thread 'tests::it_adds_two' (6020955) panicked at src/lib.rs:12:9:
assertion `left == right` failed
  left: 5
 right: 4
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::it_adds_two

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

Наш тест обнаружил ошибку! Тест tests::it_adds_two завершился неудачей, и сообщение говорит нам, что невыполненное утверждение было left == right, и каковы значения left и right. Это сообщение помогает нам начать отладку: аргумент left, где у нас был результат вызова add_two(2), был 5, но аргумент right был 4. Вы можете представить, что это было бы особенно полезно, когда у нас много тестов.

Обратите внимание, что в некоторых языках и тестовых фреймворках параметры функций проверки равенства называются expected и actual, и порядок, в котором мы указываем аргументы, имеет значение. Однако в Rust они называются left и right, и порядок, в котором мы указываем значение, которое ожидаем, и значение, которое производит код, не имеет значения. Мы могли бы записать утверждение в этом тесте как assert_eq!(4, result), что привело бы к тому же сообщению о неудаче, которое отображает assertion `left == right` failed.

Макрос assert_ne! пройдёт, если два переданных ему значения не равны, и потерпит неудачу, если они равны. Этот макрос наиболее полезен в случаях, когда мы не уверены, каким будет значение, но знаем, каким значение определённо не должно быть. Например, если мы тестируем функцию, которая гарантированно изменяет свой входной параметр каким-либо образом, но то, каким образом изменяется входной параметр, зависит от дня недели, в который мы запускаем наши тесты, лучше всего утверждать, что вывод функции не равен входному параметру.

Под капотом макросы assert_eq! и assert_ne! используют операторы == и != соответственно. Когда утверждения не выполняются, эти макросы выводят свои аргументы с использованием отладочного форматирования, что означает, что сравниваемые значения должны реализовывать трейты PartialEq и Debug. Все примитивные типы и большинство типов стандартной библиотеки реализуют эти трейты. Для структур и перечислений, которые вы определяете сами, вам нужно будет реализовать PartialEq, чтобы утверждать равенство этих типов. Вам также нужно будет реализовать Debug, чтобы выводить значения, когда утверждение не выполняется. Поскольку оба трейта являются выводимыми трейтами, как упомянуто в листинге 5-12 в главе 5, обычно это так же просто, как добавить аннотацию #[derive(PartialEq, Debug)] к определению вашей структуры или перечисления. См. приложение C, «Выводимые трейты», для получения дополнительных сведений об этих и других выводимых трейтах.

Добавление пользовательских сообщений о неудаче

Вы также можете добавить пользовательское сообщение, которое будет выводиться вместе с сообщением о неудаче, в качестве необязательных аргументов для макросов assert!, assert_eq! и assert_ne!. Любые аргументы, указанные после обязательных аргументов, передаются макросу format! (обсуждавшемуся в разделе «Конкатенация с помощью + или format!» главы 8), поэтому вы можете передать строку формата, содержащую заполнители {} и значения для подстановки в эти заполнители. Пользовательские сообщения полезны для документирования того, что означает утверждение; когда тест терпит неудачу, у вас будет лучшее представление о том, в чём проблема с кодом.

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

Имя файла: src/lib.rs

pub fn greeting(name: &str) -> String {
    format!("Hello {name}!")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn greeting_contains_name() {
        let result = greeting("Carol");
        assert!(result.contains("Carol"));
    }
}

Требования к этой программе ещё не согласованы, и мы вполне уверены, что текст Hello в начале приветствия изменится. Мы решили, что не хотим обновлять тест при изменении требований, поэтому вместо проверки на точное равенство значению, возвращаемому функцией greeting, мы просто утверждаем, что вывод содержит текст входного параметра.

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

pub fn greeting(name: &str) -> String {
    String::from("Hello!")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn greeting_contains_name() {
        let result = greeting("Carol");
        assert!(result.contains("Carol"));
    }
}

Выполнение этого теста выдаёт следующее:

$ cargo test
   Compiling greeter v0.1.0 (file:///projects/greeter)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.91s
     Running unittests src/lib.rs (target/debug/deps/greeter-170b942eb5bf5e3a)

running 1 test
test tests::greeting_contains_name ... FAILED

failures:

---- tests::greeting_contains_name stdout ----

thread 'tests::greeting_contains_name' (6021143) panicked at src/lib.rs:12:9:
assertion failed: result.contains("Carol")
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::greeting_contains_name

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

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

pub fn greeting(name: &str) -> String {
    String::from("Hello!")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn greeting_contains_name() {
        let result = greeting("Carol");
        assert!(
            result.contains("Carol"),
            "Greeting did not contain name, value was `{result}`"
        );
    }
}

Теперь, когда мы запускаем тест, мы получим более информативное сообщение об ошибке:

$ cargo test
   Compiling greeter v0.1.0 (file:///projects/greeter)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.93s
     Running unittests src/lib.rs (target/debug/deps/greeter-170b942eb5bf5e3a)

running 1 test
test tests::greeting_contains_name ... FAILED

failures:

---- tests::greeting_contains_name stdout ----

thread 'tests::greeting_contains_name' (6021333) panicked at src/lib.rs:12:9:
Greeting did not contain name, value was `Hello!`
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::greeting_contains_name

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

Мы можем видеть значение, которое фактически получили в выводе теста, что помогло бы нам отладить то, что произошло, вместо того, что мы ожидали.

Проверка паник с помощью should_panic

Помимо проверки возвращаемых значений, важно проверять, что наш код обрабатывает ошибочные условия так, как мы ожидаем. Например, рассмотрим тип Guess, который мы создали в главе 9, листинге 9-13. Другой код, использующий Guess, полагается на гарантию, что экземпляры Guess будут содержать только значения от 1 до 100. Мы можем написать тест, который проверяет, что попытка создать экземпляр Guess со значением за пределами этого диапазона вызывает панику.

Мы делаем это, добавляя атрибут should_panic к нашей тестовой функции. Тест проходит, если код внутри функции паникует; тест терпит неудачу, если код внутри функции не паникует.

Листинг 11-8 показывает тест, который проверяет, что ошибочные условия Guess::new происходят, когда мы их ожидаем.

Имя файла: src/lib.rs
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got {value}.");
        }

        Guess { value }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[should_panic]
    fn greater_than_100() {
        Guess::new(200);
    }
}
Листинг 11-8: Проверка того, что условие вызовет panic!

Мы помещаем атрибут #[should_panic] после атрибута #[test] и перед тестовой функцией, к которой он применяется. Давайте посмотрим на результат, когда этот тест проходит:

$ cargo test
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running unittests src/lib.rs (target/debug/deps/guessing_game-57d70c3acb738f4d)

running 1 test
test tests::greater_than_100 - should panic ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests guessing_game

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Выглядит хорошо! Теперь давайте внесём ошибку в наш код, удалив условие, при котором функция new будет паниковать, если значение больше 100:

pub struct Guess {
    value: i32,
}

// --snip--
impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 {
            panic!("Guess value must be between 1 and 100, got {value}.");
        }

        Guess { value }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[should_panic]
    fn greater_than_100() {
        Guess::new(200);
    }
}

Когда мы запускаем тест из листинга 11-8, он терпит неудачу:

$ cargo test
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.62s
     Running unittests src/lib.rs (target/debug/deps/guessing_game-57d70c3acb738f4d)

running 1 test
test tests::greater_than_100 - should panic ... FAILED

failures:

---- tests::greater_than_100 stdout ----
note: test did not panic as expected at src/lib.rs:21:8

failures:
    tests::greater_than_100

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

В этом случае мы не получаем очень полезного сообщения, но когда мы смотрим на тестовую функцию, мы видим, что она аннотирована #[should_panic]. Неудача, которую мы получили, означает, что код в тестовой функции не вызвал панику.

Тесты, использующие should_panic, могут быть неточными. Тест с should_panic пройдёт, даже если тест паникует по причине, отличной от той, которую мы ожидали. Чтобы сделать тесты should_panic более точными, мы можем добавить необязательный параметр expected в атрибут should_panic. Средство запуска тестов удостоверится, что сообщение о неудаче содержит указанный текст. Например, рассмотрим изменённый код для Guess в листинге 11-9, где функция new паникует с разными сообщениями в зависимости от того, слишком мало или слишком велико значение.

Имя файла: src/lib.rs
pub struct Guess {
    value: i32,
}

// --snip--

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 {
            panic!(
                "Guess value must be greater than or equal to 1, got {value}."
            );
        } else if value > 100 {
            panic!(
                "Guess value must be less than or equal to 100, got {value}."
            );
        }

        Guess { value }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[should_panic(expected = "less than or equal to 100")]
    fn greater_than_100() {
        Guess::new(200);
    }
}
Листинг 11-9: Проверка panic! с сообщением о панике, содержащим указанную подстроку

Этот тест пройдёт, потому что значение, которое мы поместили в параметр expected атрибута should_panic, является подстрокой сообщения, с которым паникует функция Guess::new. Мы могли бы указать всё сообщение о панике, которое ожидаем, что в данном случае было бы Guess value must be less than or equal to 100, got 200. Что выбрать для указания, зависит от того, насколько сообщение о панике уникально или динамично и насколько точным вы хотите сделать свой тест. В этом случае подстроки сообщения о панике достаточно, чтобы гарантировать, что код в тестовой функции выполняет случай else if value > 100.

Чтобы увидеть, что происходит, когда тест should_panic с сообщением expected терпит неудачу, давайте снова внесём ошибку в наш код, поменяв местами тела блоков if value < 1 и else if value > 100:

pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 {
            panic!(
                "Guess value must be less than or equal to 100, got {value}."
            );
        } else if value > 100 {
            panic!(
                "Guess value must be greater than or equal to 1, got {value}."
            );
        }

        Guess { value }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[should_panic(expected = "less than or equal to 100")]
    fn greater_than_100() {
        Guess::new(200);
    }
}

На этот раз, когда мы запускаем тест should_panic, он терпит неудачу:

$ cargo test
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.66s
     Running unittests src/lib.rs (target/debug/deps/guessing_game-57d70c3acb738f4d)

running 1 test
test tests::greater_than_100 - should panic ... FAILED

failures:

---- tests::greater_than_100 stdout ----

thread 'tests::greater_than_100' (6021675) panicked at src/lib.rs:12:13:
Guess value must be greater than or equal to 1, got 200.
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
note: panic did not contain expected string
      panic message: "Guess value must be greater than or equal to 1, got 200."
 expected substring: "less than or equal to 100"

failures:
    tests::greater_than_100

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

Сообщение о неудаче указывает, что этот тест действительно запаниковал, как мы и ожидали, но сообщение о панике не содержало ожидаемой строки less than or equal to 100. Сообщение о панике, которое мы получили в этом случае, было Guess value must be greater than or equal to 1, got 200. Теперь мы можем начать выяснять, где наша ошибка!

Использование Result<T, E> в тестах

Все наши тесты до сих пор паниковали, когда терпели неудачу. Мы также можем писать тесты, которые используют Result<T, E>! Вот тест из листинга 11-1, переписанный с использованием Result<T, E> и возвращающий Err вместо паники:

pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() -> Result<(), String> {
        let result = add(2, 2);

        if result == 4 {
            Ok(())
        } else {
            Err(String::from("two plus two does not equal four"))
        }
    }
}

Функция it_works теперь имеет возвращаемый тип Result<(), String>. В теле функции вместо вызова макроса assert_eq! мы возвращаем Ok(()), когда тест проходит, и Err с String внутри, когда тест терпит неудачу.

Написание тестов так, чтобы они возвращали Result<T, E>, позволяет использовать оператор вопросительного знака в теле тестов, что может быть удобным способом написания тестов, которые должны терпеть неудачу, если какая-либо операция внутри них возвращает вариант Err.

Вы не можете использовать аннотацию #[should_panic] в тестах, использующих Result<T, E>. Чтобы утверждать, что операция возвращает вариант Err, не используйте оператор вопросительного знака для значения Result<T, E>. Вместо этого используйте assert!(value.is_err()).

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