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
- Escribe
fn roman(n: u32) -> Stringempezando por las pruebas: primero las pruebas para 1, 4, 9, 14, 40, 90, 400 y 1994, y después la implementación. - 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). - Con
proptest, comprueba que tumedianbasada 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.¿Dónde viven las pruebas de integración en un paquete de Cargo?
2.¿Qué hace
#[cfg(test)]en un módulo?3.¿Qué le ocurre a un bloque de código Rust dentro de un comentario de documentación
///cuando ejecutascargo test?