rust-testing

Padrões de Teste em Rust

Padrões de teste abrangentes em Rust para escrever testes confiáveis e de fácil manutenção seguindo a metodologia TDD.

Quando Usar

• Ao escrever novas funções, métodos ou traits em Rust
• Ao adicionar cobertura de teste a código existente
• Ao criar benchmarks para código crítico de desempenho
• Ao implementar testes baseados em propriedades para validação de entrada
• Ao seguir o fluxo de trabalho TDD em projetos Rust

Como Funciona

1. Identifique o código alvo — Encontre a função, trait ou módulo a ser testado
2. Escreva um teste — Use #[test] em um módulo #[cfg(test)], rstest para testes parametrizados, ou proptest para testes baseados em propriedades
3. Simule dependências — Use mockall para isolar a unidade sob teste
4. Execute os testes (VERMELHO) — Verifique se o teste falha com o erro esperado
5. Implemente (VERDE) — Escreva o código mínimo para passar
6. Refatore — Melhore mantendo os testes verdes
7. Verifique a cobertura — Use cargo-llvm-cov, alvo 80%+

Fluxo de Trabalho TDD para Rust

O Ciclo VERMELHO-VERDE-REFATORAR

VERMELHO → Escreva um teste que falha primeiro
VERDE   → Escreva o código mínimo para passar no teste
REFATORAR → Melhore o código mantendo os testes verdes
REPITA  → Continue com o próximo requisito

TDD Passo a Passo em Rust

// VERMELHO: Escreva o teste primeiro, use todo!() como placeholder
pub fn adicionar(a: i32, b: i32) -> i32 { todo!() }

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn test_adicionar() { assert_eq!(adicionar(2, 3), 5); }
}
// cargo test → panic em 'not yet implemented'

// VERDE: Substitua todo!() pela implementação mínima
pub fn adicionar(a: i32, b: i32) -> i32 { a + b }
// cargo test → PASS, então REFATORAR mantendo os testes verdes

Testes Unitários

Organização de Testes no Nível do Módulo

// src/usuario.rs
pub struct Usuario {
    pub nome: String,
    pub email: String,
}

impl Usuario {
    pub fn new(nome: impl Into<String>, email: impl Into<String>) -> Result<Self, String> {
        let email = email.into();
        if !email.contains('@') {
            return Err(format!("email inválido: {email}"));
        }
        Ok(Self { nome: nome.into(), email })
    }

    pub fn nome_exibicao(&self) -> &str {
        &self.nome
    }
}

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

    #[test]
    fn cria_usuario_com_email_valido() {
        let usuario = Usuario::new("Alice", "[email protected]").unwrap();
        assert_eq!(usuario.nome_exibicao(), "Alice");
        assert_eq!(usuario.email, "[email protected]");
    }

    #[test]
    fn rejeita_email_invalido() {
        let resultado = Usuario::new("Bob", "nao-email");
        assert!(resultado.is_err());
        assert!(resultado.unwrap_err().contains("email inválido"));
    }
}

Macros de Assertion

assert_eq!(2 + 2, 4);                                    // Igualdade
assert_ne!(2 + 2, 5);                                    // Desigualdade
assert!(vec![1, 2, 3].contains(&2));                     // Booleano
assert_eq!(valor, 42, "esperava 42 mas obteve {valor}"); // Mensagem personalizada
assert!((0.1_f64 + 0.2 - 0.3).abs() < f64::EPSILON);   // Comparação de ponto flutuante

Teste de Erros e Pânicos

Testando Retornos Result

#[test]
fn parse_retorna_erro_para_entrada_invalida() {
    let resultado = parse_config("}{");
    assert!(resultado.is_err());

    // Afirme a variante específica do erro
    let erro = resultado.unwrap_err();
    assert!(matches!(erro, ConfigError::ParseError(_)));
}

#[test]
fn parse_sucesso_para_entrada_valida() -> Result<(), Box<dyn std::error::Error>> {
    let config = parse_config(r#"{"porta": 8080}"#)?;
    assert_eq!(config.porta, 8080);
    Ok(()) // O teste falha se qualquer ? retornar Err
}

Testando Pânicos

#[test]
#[should_panic]
fn panic_em_entrada_vazia() {
    processar(&[]);
}

#[test]
#[should_panic(expected = "índice fora dos limites")]
fn panic_com_mensagem_especifica() {
    let v: Vec<i32> = vec![];
    let _ = v[0];
}

Testes de Integração

Estrutura de Arquivos

meu_projeto/
├── src/
│   └── lib.rs
├── tests/              # Testes de integração
│   ├── api_test.rs     # Cada arquivo é um binário de teste separado
│   ├── db_test.rs
│   └── common/         # Utilitários de teste compartilhados
│       └── mod.rs

Escrevendo Testes de Integração

// tests/api_test.rs
use meu_projeto::{App, Config};

#[test]
fn ciclo_completo_de_requisicao() {
    let config = Config::padrao_teste();
    let app = App::new(config);

    let resposta = app.handle_request("/saude");
    assert_eq!(resposta.status, 200);
    assert_eq!(resposta.body, "OK");
}

Testes Assíncronos

Com Tokio

#[tokio::test]
async fn busca_dados_com_sucesso() {
    let cliente = TestClient::new().await;
    let resultado = cliente.get("/dados").await;
    assert!(resultado.is_ok());
    assert_eq!(resultado.unwrap().itens.len(), 3);
}

#[tokio::test]
async fn lida_com_timeout() {
    use std::time::Duration;
    let resultado = tokio::time::timeout(
        Duration::from_millis(100),
        operacao_lenta(),
    ).await;

    assert!(resultado.is_err(), "deveria ter expirado o tempo");
}

Padrões de Organização de Testes

Testes Parametrizados com rstest

use rstest::{rstest, fixture};

#[rstest]
#[case("ola", 3)]
#[case("", 0)]
#[case("rust", 4)]
fn test_tamanho_string(#[case] entrada: &str, #[case] esperado: usize) {
    assert_eq!(entrada.len(), esperado);
}

// Fixtures
#[fixture]
fn banco_teste() -> BancoTeste {
    BancoTeste::novo_em_memoria()
}

#[rstest]
fn test_inserir(banco_teste: BancoTeste) {
    banco_teste.inserir("chave", "valor");
    assert_eq!(banco_teste.obter("chave"), Some("valor".into()));
}

Helpers de Teste

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

    /// Cria um usuário de teste com valores padrões sensíveis.
    fn criar_usuario(nome: &str) -> Usuario {
        Usuario::new(nome, &format!("{nome}@teste.com")).unwrap()
    }

    #[test]
    fn exibicao_usuario() {
        let usuario = criar_usuario("alice");
        assert_eq!(usuario.nome_exibicao(), "alice");
    }
}

Testes Baseados em Propriedades com proptest

Testes de Propriedade Básicos

use proptest::prelude::*;

proptest! {
    #[test]
    fn codifica_decodifica_roundtrip(entrada in ".*") {
        let codificado = codificar(&entrada);
        let decodificado = decodificar(&codificado).unwrap();
        assert_eq!(entrada, decodificado);
    }

    #[test]
    fn ordenar_preserva_tamanho(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
        let tamanho_original = vec.len();
        vec.sort();
        assert_eq!(vec.len(), tamanho_original);
    }

    #[test]
    fn ordenar_produz_saida_ordenada(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
        vec.sort();
        for janela in vec.windows(2) {
            assert!(janela[0] <= janela[1]);
        }
    }
}

Estratégias Personalizadas

use proptest::prelude::*;

fn email_valido() -> impl Strategy<Value = String> {
    ("[a-z]{1,10}", "[a-z]{1,5}")
        .prop_map(|(usuario, dominio)| format!("{usuario}@{dominio}.com"))
}

proptest! {
    #[test]
    fn aceita_emails_validos(email in email_valido()) {
        assert!(Usuario::new("Teste", &email).is_ok());
    }
}

Mocking com mockall

Mocking Baseado em Trait

use mockall::{automock, predicate::eq};

#[automock]
trait RepositorioUsuario {
    fn buscar_por_id(&self, id: u64) -> Option<Usuario>;
    fn salvar(&self, usuario: &Usuario) -> Result<(), ErroArmazenamento>;
}

#[test]
fn servico_retorna_usuario_quando_encontrado() {
    let mut mock = MockRepositorioUsuario::new();
    mock.expect_buscar_por_id()
        .with(eq(42))
        .vezes(1)
        .returning(|_| Some(Usuario { id: 42, nome: "Alice".into() }));

    let servico = ServicoUsuario::new(Box::new(mock));
    let usuario = servico.obter_usuario(42).unwrap();
    assert_eq!(usuario.nome, "Alice");
}

#[test]
fn servico_retorna_none_quando_nao_encontrado() {
    let mut mock = MockRepositorioUsuario::new();
    mock.expect_buscar_por_id()
        .returning(|_| None);

    let servico = ServicoUsuario::new(Box::new(mock));
    assert!(servico.obter_usuario(99).is_none());
}

Testes de Documentação

Documentação Executável

/// Soma dois números.
///
/// # Exemplos
///
/// ```
/// use meu_projeto::somar;
///
/// assert_eq!(somar(2, 3), 5);
/// assert_eq!(somar(-1, 1), 0);
/// ```
pub fn somar(a: i32, b: i32) -> i32 {
    a + b
}

/// Analisa uma string de configuração.
///
/// # Erros
///
/// Retorna `Err` se a entrada não for TOML válido.
///
/// ```no_run
/// use meu_projeto::parse_config;
///
/// let config = parse_config(r#"porta = 8080"#).unwrap();
/// assert_eq!(config.porta, 8080);
/// ```
///
/// ```no_run
/// use meu_projeto::parse_config;
///
/// assert!(parse_config("}{").is_err());
/// ```
pub fn parse_config(entrada: &str) -> Result<Config, ErroParse> {
    todo!()
}

Benchmarking com Criterion

# Cargo.toml
[dev-dependencies]
criterion = { version = "0.5", features = ["html_reports"] }

[[bench]]
name = "benchmark"
harness = false

// benches/benchmark.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn fibonacci(n: u64) -> u64 {
    match n {
        0 | 1 => n,
        _ => fibonacci(n - 1) + fibonacci(n - 2),
    }
}

fn bench_fibonacci(c: &mut Criterion) {
    c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20))));
}

criterion_group!(benches, bench_fibonacci);
criterion_main!(benches);

Cobertura de Testes

Executando Cobertura

# Instalar: cargo install cargo-llvm-cov (ou usar taiki-e/install-action no CI)
cargo llvm-cov                    # Resumo
cargo llvm-cov --html             # Relatório HTML
cargo llvm-cov --lcov > lcov.info # Formato LCOV para CI
cargo llvm-cov --fail-under-lines 80  # Falhar se abaixo do limite

Metas de Cobertura

Tipo de Código	Meta
Lógica de negócio crítica	100%
API pública	90%+
Código geral	80%+
Código gerado / bindings FFI	Excluir

Comandos de Teste

cargo test                        # Executar todos os testes
cargo test -- --nocapture         # Mostrar saída println
cargo test nome_teste             # Executar testes correspondentes ao padrão
cargo test --lib                  # Apenas testes unitários
cargo test --test api_test        # Apenas testes de integração
cargo test --doc                  # Apenas testes de documentação
cargo test --no-fail-fast         # Não parar na primeira falha
cargo test -- --ignored           # Executar testes ignorados

Melhores Práticas

FAÇA:

• Escreva os testes PRIMEIRO (TDD)
• Use módulos #[cfg(test)] para testes unitários
• Teste comportamento, não implementação
• Use nomes de teste descritivos que expliquem o cenário
• Prefira assert_eq! em vez de assert! para melhores mensagens de erro
• Use ? em testes que retornam Result para saída de erro mais limpa
• Mantenha os testes independentes — sem estado mutável compartilhado

NÃO FAÇA:

• Use #[should_panic] quando puder testar Result::is_err()
• Mock tudo — prefira testes de integração quando viável
• Ignore testes instáveis — corrija-os ou coloque-os em quarentena
• Use sleep() em testes — use canais, barreiras ou tokio::time::pause()
• Pule testes de caminhos de erro

Integração com CI

# GitHub Actions
teste:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
      with:
        components: clippy, rustfmt

    - name: Verificar formatação
      run: cargo fmt --check

    - name: Clippy
      run: cargo clippy -- -D warnings

    - name: Executar testes
      run: cargo test

    - uses: taiki-e/install-action@cargo-llvm-cov

    - name: Cobertura
      run: cargo llvm-cov --fail-under-lines 80

Lembre-se: Testes são documentação. Eles mostram como seu código deve ser usado. Escreva-os claramente e mantenha-os atualizados.