FerrousPath

Nivel 2 · Practicante· Lección 7 de 8 · 20 min

Pruebas y documentación

Pruebas unitarias, pruebas de integración, pruebas de documentación, pruebas basadas en propiedades y las herramientas que mantienen sano un código.

Pruebas unitarias

Las pruebas viven junto al código, en un módulo que solo se compila con cargo test. Abre el bloque de abajo en el Playground y pulsa allí Probar.

pub fn median(values: &mut [f64]) -> Option<f64> {
    if values.is_empty() {
        return None;
    }
    values.sort_by(|a, b| a.total_cmp(b));
    let mid = values.len() / 2;
    Some(if values.len() % 2 == 0 {
        (values[mid - 1] + values[mid]) / 2.0
    } else {
        values[mid]
    })
}

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

    #[test]
    fn empty_has_no_median() {
        assert_eq!(median(&mut []), None);
    }

    #[test]
    fn odd_length() {
        assert_eq!(median(&mut [3.0, 1.0, 2.0]), Some(2.0));
    }

    #[test]
    fn even_length_averages_the_middle() {
        assert_eq!(median(&mut [4.0, 1.0, 3.0, 2.0]), Some(2.5));
    }

    #[test]
    #[should_panic(expected = "index out of bounds")]
    fn indexing_past_the_end_panics() {
        let v = vec![1];
        let i = v.len();
        let _ = v[i];
    }

    #[test]
    fn tests_can_return_result() -> Result<(), std::num::ParseIntError> {
        let n: i32 = "42".parse()?;
        assert_eq!(n, 42);
        Ok(())
    }
}

fn main() {
    println!("{:?}", median(&mut [5.0, 1.0, 9.0]));
}

Las herramientas: assert!(cond), assert_eq!(a, b), assert_ne!(a, b), cada una con un mensaje de formato opcional al final. Como tests es un módulo hijo, puede probar funciones privadas.

Comandos útiles:

Comando Efecto
cargo test lo ejecuta todo
cargo test median ejecuta las pruebas cuyo nombre contiene median
cargo test -- --nocapture muestra la salida de println! de las pruebas que pasan
cargo test -- --test-threads=1 las ejecuta en serie
#[ignore] + cargo test -- --ignored pruebas lentas que se ejecutan solo si lo pides

Pruebas de integración

Los archivos de tests/ son crates separados que solo ven tu API pública: usan la biblioteca exactamente como lo haría un usuario.

my_crate/
├── src/lib.rs
└── tests/
    ├── basic.rs
    └── common/mod.rs   // utilidades compartidas
// tests/basic.rs
use my_crate::median;

#[test]
fn works_through_the_public_api() {
    assert_eq!(median(&mut [1.0, 2.0, 3.0]), Some(2.0));
}

Un crate que solo es un binario no tiene una biblioteca que las pruebas de integración puedan importar, y esa es una de las razones para mantener main.rs pequeño y poner la lógica en lib.rs.

Documentación y pruebas de documentación

/// documenta el elemento que viene a continuación; //! documenta el módulo o el crate que lo contiene. Los comentarios son Markdown, y cargo test compila y ejecuta los bloques de código que hay en ellos.

/// Clamps `value` to the inclusive range `lo..=hi`.
///
/// # Examples
///
/// ```
/// assert_eq!(my_crate::clamp(15, 0, 10), 10);
/// assert_eq!(my_crate::clamp(-3, 0, 10), 0);
/// ```
///
/// # Panics
///
/// Panics if `lo > hi`.
pub fn clamp(value: i32, lo: i32, hi: i32) -> i32 {
    assert!(lo <= hi, "lo must not exceed hi");
    value.max(lo).min(hi)
}

Las secciones convencionales son # Examples, # Panics, # Errors y # Safety (obligatoria en las unsafe fn). cargo doc --open lo presenta todo con el mismo formato que la documentación de la biblioteca estándar.

Pruebas basadas en propiedades

Las pruebas con ejemplos comprueban los casos que se te ocurrieron. Las pruebas de propiedades enuncian una ley y dejan que la máquina busque un contraejemplo y después lo reduzca a uno mínimo. Con el crate proptest:

// crate: proptest
use proptest::prelude::*;

fn reverse<T: Clone>(xs: &[T]) -> Vec<T> {
    xs.iter().rev().cloned().collect()
}

proptest! {
    #[test]
    fn reversing_twice_is_identity(xs in proptest::collection::vec(any::<i32>(), 0..100)) {
        prop_assert_eq!(reverse(&reverse(&xs)), xs);
    }

    #[test]
    fn reverse_preserves_length(xs in proptest::collection::vec(any::<u8>(), 0..100)) {
        prop_assert_eq!(reverse(&xs).len(), xs.len());
    }
}

Buenas propiedades: viajes de ida y vuelta (decode(encode(x)) == x), invariantes (la salida está ordenada), coincidencia con una implementación lenta y obviamente correcta.

El resto de la caja de herramientas

Herramienta Para qué sirve
cargo fmt Formato canónico. Ejecútalo al guardar
cargo clippy Lints de bugs, rendimiento y estilo idiomático. Trata los avisos como lecciones
cargo bench con criterion Microbenchmarks estadísticamente sólidos
cargo fuzz Fuzzing guiado por cobertura: la mejor forma de encontrar pánicos en analizadores
cargo miri test Ejecuta las pruebas en un intérprete que detecta comportamiento indefinido
cargo audit, cargo deny Vulnerabilidades conocidas y política de licencias en las dependencias
cargo llvm-cov Cobertura de código

Una base razonable para la integración continua: cargo fmt --check, cargo clippy -- -D warnings, cargo test.

Ejercicios

  1. Escribe fn roman(n: u32) -> String empezando por las pruebas: primero las pruebas para 1, 4, 9, 14, 40, 90, 400 y 1994, y después la implementación.
  2. Añade un comentario de documentación con un ejemplo ejecutable y una sección # Panics (para 0 y para los valores superiores a 3999).
  3. Con proptest, comprueba que tu median basada en ordenar queda siempre entre el mínimo y el máximo de la entrada.

Comprueba lo que has entendido

Elige una respuesta para ver la explicación.

  1. 1.¿Dónde viven las pruebas de integración en un paquete de Cargo?

  2. 2.¿Qué hace #[cfg(test)] en un módulo?

  3. 3.¿Qué le ocurre a un bloque de código Rust dentro de un comentario de documentación /// cuando ejecutas cargo test?

Términos clave de esta lección

¿Has terminado la lección y los ejercicios?