Сочетания клавиш

Нажмите ← или → для навигации между главами

Нажмите S или / для поиска по книге

Нажмите ?, чтобы показать эту справку

Нажмите Esc, чтобы скрыть эту справку

Организация тестов

Как упоминалось в начале главы, тестирование — это сложная дисциплина, и разные люди используют разные терминологию и организацию. Сообщество Rust рассматривает тесты в терминах двух основных категорий: модульные тесты и интеграционные тесты. Модульные тесты небольшие и более сфокусированные, тестируют один модуль в изоляции за раз и могут тестировать приватные интерфейсы. Интеграционные тесты полностью внешние по отношению к вашей библиотеке и используют ваш код так же, как это делал бы любой другой внешний код, используя только публичный интерфейс и потенциально задействуя несколько модулей за один тест.

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

Модульные тесты

Цель модульных тестов — тестировать каждую единицу кода в изоляции от остального кода, чтобы быстро определить, где код работает, а где нет, как ожидалось. Вы будете размещать модульные тесты в каталоге src в каждом файле с кодом, который они тестируют. Соглашение состоит в том, чтобы создать модуль с именем tests в каждом файле, содержащий тестовые функции, и аннотировать модуль атрибутом cfg(test).

Модуль tests и атрибут #[cfg(test)]

Аннотация #[cfg(test)] на модуле tests говорит Rust компилировать и запускать тестовый код только при запуске cargo test, а не при запуске cargo build. Это экономит время компиляции, когда вы хотите только собрать библиотеку, и экономит место в результирующем скомпилированном артефакте, потому что тесты не включаются. Вы увидите, что поскольку интеграционные тесты находятся в другом каталоге, им не нужна аннотация #[cfg(test)]. Однако, поскольку модульные тесты находятся в тех же файлах, что и код, вы будете использовать #[cfg(test)], чтобы указать, что они не должны включаться в скомпилированный результат.

Вспомните, что когда мы создали новый проект adder в первом разделе этой главы, Cargo сгенерировал для нас этот код:

Имя файла: 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);
    }
}

В автоматически сгенерированном модуле tests атрибут cfg означает конфигурация и говорит Rust, что следующий элемент должен быть включён только при определённой опции конфигурации. В этом случае опция конфигурации — это test, которая предоставляется Rust для компиляции и запуска тестов. Используя атрибут cfg, Cargo компилирует наш тестовый код только если мы активно запускаем тесты с помощью cargo test. Это включает любые вспомогательные функции, которые могут быть в этом модуле, в дополнение к функциям, аннотированным #[test].

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

В сообществе тестировщиков ведутся дебаты о том, следует ли тестировать приватные функции напрямую, и в других языках сделать это сложно или невозможно. Независимо от того, какой идеологии тестирования вы придерживаетесь, правила приватности Rust позволяют тестировать приватные функции. Рассмотрим код в листинге 11-12 с приватной функцией internal_adder.

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

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

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

    #[test]
    fn internal() {
        let result = internal_adder(2, 2);
        assert_eq!(result, 4);
    }
}
Листинг 11-12: Тестирование приватной функции

Обратите внимание, что функция internal_adder не помечена как pub. Тесты — это просто код на Rust, а модуль tests — это просто ещё один модуль. Как мы обсуждали в разделе «Пути для ссылки на элемент в дереве модулей», элементы в дочерних модулях могут использовать элементы в своих родительских модулях. В этом тесте мы вводим в область видимости все элементы, принадлежащие родительскому модулю модуля tests, с помощью use super::*, и затем тест может вызвать internal_adder. Если вы не считаете, что приватные функции следует тестировать, ничто в Rust не заставит вас это делать.

Интеграционные тесты

В Rust интеграционные тесты полностью внешние по отношению к вашей библиотеке. Они используют вашу библиотеку так же, как это делал бы любой другой код, что означает, что они могут вызывать только функции, которые являются частью публичного API вашей библиотеки. Их цель — проверить, работают ли многие части вашей библиотеки вместе правильно. Единицы кода, которые работают правильно сами по себе, могут иметь проблемы при интеграции, поэтому покрытие тестами интегрированного кода также важно. Чтобы создать интеграционные тесты, вам сначала нужен каталог tests.

Каталог tests

Мы создаём каталог tests на верхнем уровне каталога нашего проекта, рядом с src. Cargo знает, что нужно искать файлы интеграционных тестов в этом каталоге. Затем мы можем создать столько тестовых файлов, сколько захотим, и Cargo скомпилирует каждый из файлов как отдельный крейт.

Давайте создадим интеграционный тест. С кодом из листинга 11-12 всё ещё в файле src/lib.rs, создайте каталог tests и создайте новый файл с именем tests/integration_test.rs. Структура вашего каталога должна выглядеть так:

adder
├── Cargo.lock
├── Cargo.toml
├── src
│   └── lib.rs
└── tests
    └── integration_test.rs

Введите код из листинга 11-13 в файл tests/integration_test.rs.

Имя файла: tests/integration_test.rs
use adder::add_two;

#[test]
fn it_adds_two() {
    let result = add_two(2);
    assert_eq!(result, 4);
}
Листинг 11-13: Интеграционный тест функции в крейте adder

Каждый файл в каталоге tests — это отдельный крейт, поэтому нам нужно ввести нашу библиотеку в область видимости каждого тестового крейта. По этой причине мы добавляем use adder::add_two; в начало кода, что не требовалось в модульных тестах.

Нам не нужно аннотировать какой-либо код в tests/integration_test.rs атрибутом #[cfg(test)]. Cargo обрабатывает каталог tests особым образом и компилирует файлы в этом каталоге только при запуске cargo test. Запустите cargo test сейчас:

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

running 1 test
test tests::internal ... ok

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

     Running tests/integration_test.rs (target/debug/deps/integration_test-1082c4b063a8fbe6)

running 1 test
test 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

Три раздела вывода включают модульные тесты, интеграционный тест и doc-тесты. Обратите внимание, что если какой-либо тест в разделе завершится неудачно, последующие разделы не будут запущены. Например, если модульный тест завершится неудачно, не будет никакого вывода для интеграционных тестов и doc-тестов, потому что эти тесты запускаются только если все модульные тесты проходят.

Первый раздел для модульных тестов такой же, как мы видели: одна строка для каждого модульного теста (один с именем internal, который мы добавили в листинге 11-12), а затем итоговая строка для модульных тестов.

Раздел интеграционных тестов начинается со строки Running tests/integration_test.rs. Затем идёт строка для каждой тестовой функции в этом интеграционном тесте и итоговая строка для результатов интеграционного теста прямо перед началом раздела Doc-tests adder.

Каждый файл интеграционных тестов имеет свой собственный раздел, поэтому если мы добавим больше файлов в каталог tests, будет больше разделов интеграционных тестов.

Мы всё ещё можем запустить конкретную функцию интеграционного теста, указав имя тестовой функции в качестве аргумента для cargo test. Чтобы запустить все тесты в определённом файле интеграционных тестов, используйте аргумент --test для cargo test, за которым следует имя файла:

$ cargo test --test integration_test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.64s
     Running tests/integration_test.rs (target/debug/deps/integration_test-82e7799c1bc62298)

running 1 test
test it_adds_two ... ok

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

Эта команда запускает только тесты в файле tests/integration_test.rs.

Подмодули в интеграционных тестах

По мере добавления всё большего числа интеграционных тестов вы можете захотеть создать больше файлов в каталоге tests, чтобы помочь их организовать; например, вы можете сгруппировать тестовые функции по функциональности, которую они тестируют. Как упоминалось ранее, каждый файл в каталоге tests компилируется как отдельный крейт, что полезно для создания отдельных областей видимости, чтобы более точно имитировать то, как конечные пользователи будут использовать ваш крейт. Однако это означает, что файлы в каталоге tests не ведут себя так же, как файлы в src, как вы узнали в главе 7 относительно того, как разделять код на модули и файлы.

Различие в поведении файлов в каталоге tests наиболее заметно, когда у вас есть набор вспомогательных функций для использования в нескольких файлах интеграционных тестов, и вы пытаетесь выполнить шаги из раздела «Разделение модулей на разные файлы» главы 7, чтобы извлечь их в общий модуль. Например, если мы создадим tests/common.rs и поместим в него функцию с именем setup, мы можем добавить некоторый код в setup, который мы хотим вызывать из нескольких тестовых функций в нескольких тестовых файлах:

Имя файла: tests/common.rs

pub fn setup() {
    // код настройки, специфичный для тестов вашей библиотеки, будет здесь
}

Когда мы снова запустим тесты, мы увидим новый раздел в выводе тестов для файла common.rs, хотя этот файл не содержит тестовых функций и мы ниоткуда не вызывали функцию setup:

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

running 1 test
test tests::internal ... ok

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

     Running tests/common.rs (target/debug/deps/common-92948b65e88960b4)

running 0 tests

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

     Running tests/integration_test.rs (target/debug/deps/integration_test-92948b65e88960b4)

running 1 test
test 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

Наличие common в результатах тестов с отображением running 0 tests для него — это не то, что мы хотели. Мы просто хотели поделиться некоторым кодом с другими файлами интеграционных тестов. Чтобы избежать появления common в выводе тестов, вместо создания tests/common.rs мы создадим tests/common/mod.rs. Каталог проекта теперь выглядит так:

├── Cargo.lock
├── Cargo.toml
├── src
│   └── lib.rs
└── tests
    ├── common
    │   └── mod.rs
    └── integration_test.rs

Это более старый стиль именования файлов, который Rust также понимает, о котором мы упоминали в разделе «Альтернативные пути к файлам» главы 7. Называя файл таким образом, вы говорите Rust не обрабатывать модуль common как файл интеграционного теста. Когда мы перемещаем код функции setup в tests/common/mod.rs и удаляем файл tests/common.rs, раздел в выводе тестов больше не будет появляться. Файлы в подкаталогах каталога tests не компилируются как отдельные крейты и не имеют разделов в выводе тестов.

После того как мы создали tests/common/mod.rs, мы можем использовать его из любого из файлов интеграционных тестов как модуль. Вот пример вызова функции setup из теста it_adds_two в tests/integration_test.rs:

Имя файла: tests/integration_test.rs

use adder::add_two;

mod common;

#[test]
fn it_adds_two() {
    common::setup();

    let result = add_two(2);
    assert_eq!(result, 4);
}

Обратите внимание, что объявление mod common; такое же, как объявление модуля, которое мы демонстрировали в листинге 7-21. Затем в тестовой функции мы можем вызвать функцию common::setup().

Интеграционные тесты для бинарных крейтов

Если наш проект — это бинарный крейт, который содержит только файл src/main.rs и не имеет файла src/lib.rs, мы не можем создавать интеграционные тесты в каталоге tests и вводить функции, определённые в файле src/main.rs, в область видимости с помощью оператора use. Только библиотечные крейты предоставляют функции, которые могут использовать другие крейты; бинарные крейты предназначены для запуска сами по себе.

Это одна из причин, по которой проекты на Rust, предоставляющие бинарный файл, имеют простой файл src/main.rs, который вызывает логику, находящуюся в файле src/lib.rs. Используя такую структуру, интеграционные тесты могут тестировать библиотечный крейт с помощью use, чтобы сделать важную функциональность доступной. Если важная функциональность работает, небольшой объём кода в файле src/main.rs также будет работать, и этот небольшой объём кода не нужно тестировать.

Итоги

Возможности тестирования Rust предоставляют способ указать, как должен работать код, чтобы гарантировать, что он продолжает работать так, как вы ожидаете, даже когда вы вносите изменения. Модульные тесты проверяют различные части библиотеки по отдельности и могут тестировать детали приватной реализации. Интеграционные тесты проверяют, что многие части библиотеки работают вместе правильно, и используют публичный API библиотеки для тестирования кода так же, как его будет использовать внешний код. Даже несмотря на то, что система типов и правила владения Rust помогают предотвратить некоторые виды ошибок, тесты всё ещё важны для уменьшения логических ошибок, связанных с тем, как, как ожидается, должен вести себя ваш код.

Давайте объединим знания, которые вы изучили в этой главе и в предыдущих главах, чтобы поработать над проектом!