Как писать тесты
Тесты — это функции 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.
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);
}
}
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
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.
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");
}
}
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`
Вместо 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!.
#[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
}
}
Rectangle и её метод can_hold из главы 5Метод can_hold возвращает логическое значение, что означает, что это идеальный случай
для использования макроса assert!. В листинге 11-6 мы пишем тест, который упражняет
метод can_hold, создавая экземпляр Rectangle с шириной 8 и
высотой 7 и утверждая, что он может содержать другой экземпляр Rectangle
с шириной 5 и высотой 1.
#[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));
}
}
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!.
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);
}
}
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
происходят, когда мы их ожидаем.
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);
}
}
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
паникует с разными сообщениями в зависимости от того, слишком мало или
слишком велико значение.
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);
}
}
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.