theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/testing-rust/SKILL.md

@@ -0,0 +1,506 @@
+---
+name: testing-rust
+description: Patrones de testing en Rust — tests unitarios y de integración, testing async, testing
+  basado en propiedades, mocking y cobertura, siguiendo la metodología TDD. Úsala al escribir tests
+  para código Rust o al añadir cobertura a un crate existente.
+---
+
+# Patrones de testing en Rust
+
+Patrones completos de testing en Rust para escribir tests fiables y mantenibles siguiendo la metodología TDD.
+
+## Cuándo usarla
+
+- Al escribir nuevas funciones, métodos o traits en Rust.
+- Al añadir cobertura de tests a código existente.
+- Al crear benchmarks para código crítico de rendimiento.
+- Al implementar tests basados en propiedades para validación de entradas.
+- Al seguir el flujo TDD en proyectos Rust.
+
+## Cómo funciona
+
+1. **Identifica el código objetivo** — encuentra la función, trait o módulo a testear.
+2. **Escribe un test** — usa `#[test]` en un módulo `#[cfg(test)]`, rstest para tests parametrizados, o proptest para tests basados en propiedades.
+3. **Mockea las dependencias** — usa mockall para aislar la unidad bajo prueba.
+4. **Ejecuta los tests (ROJO)** — verifica que el test falla con el error esperado.
+5. **Implementa (VERDE)** — escribe el código mínimo para pasar.
+6. **Refactoriza** — mejora manteniendo los tests en verde.
+7. **Verifica la cobertura** — usa cargo-llvm-cov, objetivo 80 %+.
+
+## Flujo TDD en Rust
+
+### El ciclo ROJO-VERDE-REFACTOR
+
+```
+ROJO      → Escribe primero un test que falle
+VERDE     → Escribe el código mínimo para pasar el test
+REFACTOR  → Mejora el código manteniendo los tests en verde
+REPITE    → Continúa con el siguiente requisito
+```
+
+### TDD paso a paso en Rust
+
+```rust
+// ROJO: escribe primero el test, usa todo!() como marcador
+pub fn add(a: i32, b: i32) -> i32 { todo!() }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn test_add() { assert_eq!(add(2, 3), 5); }
+}
+// cargo test → entra en pánico con 'not yet implemented'
+```
+
+```rust
+// VERDE: sustituye todo!() por la implementación mínima
+pub fn add(a: i32, b: i32) -> i32 { a + b }
+// cargo test → PASA; luego REFACTOR manteniendo los tests en verde
+```
+
+## Tests unitarios
+
+### Organización de tests a nivel de módulo
+
+```rust
+// src/user.rs
+pub struct User {
+    pub name: String,
+    pub email: String,
+}
+
+impl User {
+    pub fn new(name: 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 { name: name.into(), email })
+    }
+
+    pub fn display_name(&self) -> &str {
+        &self.name
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn crea_usuario_con_email_valido() {
+        let user = User::new("Alice", "alice@example.com").unwrap();
+        assert_eq!(user.display_name(), "Alice");
+        assert_eq!(user.email, "alice@example.com");
+    }
+
+    #[test]
+    fn rechaza_email_invalido() {
+        let result = User::new("Bob", "no-es-un-email");
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("email inválido"));
+    }
+}
+```
+
+### Macros de aserción
+
+```rust
+assert_eq!(2 + 2, 4);                                    // Igualdad
+assert_ne!(2 + 2, 5);                                    // Desigualdad
+assert!(vec![1, 2, 3].contains(&2));                     // Booleano
+assert_eq!(value, 42, "se esperaba 42 pero llegó {value}"); // Mensaje personalizado
+assert!((0.1_f64 + 0.2 - 0.3).abs() < f64::EPSILON);   // Comparación de flotantes
+```
+
+## Testing de errores y panics
+
+### Testear retornos `Result`
+
+```rust
+#[test]
+fn parse_devuelve_error_con_entrada_invalida() {
+    let result = parse_config("}{invalid");
+    assert!(result.is_err());
+
+    // Asegura la variante de error concreta
+    let err = result.unwrap_err();
+    assert!(matches!(err, ConfigError::ParseError(_)));
+}
+
+#[test]
+fn parse_funciona_con_entrada_valida() -> Result<(), Box<dyn std::error::Error>> {
+    let config = parse_config(r#"{"port": 8080}"#)?;
+    assert_eq!(config.port, 8080);
+    Ok(()) // El test falla si algún ? devuelve Err
+}
+```
+
+### Testear panics
+
+```rust
+#[test]
+#[should_panic]
+fn entra_en_panico_con_entrada_vacia() {
+    process(&[]);
+}
+
+#[test]
+#[should_panic(expected = "index out of bounds")]
+fn entra_en_panico_con_mensaje_especifico() {
+    let v: Vec<i32> = vec![];
+    let _ = v[0];
+}
+```
+
+## Tests de integración
+
+### Estructura de archivos
+
+```text
+my_crate/
+├── src/
+│   └── lib.rs
+├── tests/              # Tests de integración
+│   ├── api_test.rs     # Cada archivo es un binario de test separado
+│   ├── db_test.rs
+│   └── common/         # Utilidades de test compartidas
+│       └── mod.rs
+```
+
+### Escribir tests de integración
+
+```rust
+// tests/api_test.rs
+use my_crate::{App, Config};
+
+#[test]
+fn ciclo_completo_de_peticion() {
+    let config = Config::test_default();
+    let app = App::new(config);
+
+    let response = app.handle_request("/health");
+    assert_eq!(response.status, 200);
+    assert_eq!(response.body, "OK");
+}
+```
+
+## Tests async
+
+### Con Tokio
+
+```rust
+#[tokio::test]
+async fn obtiene_datos_correctamente() {
+    let client = TestClient::new().await;
+    let result = client.get("/data").await;
+    assert!(result.is_ok());
+    assert_eq!(result.unwrap().items.len(), 3);
+}
+
+#[tokio::test]
+async fn maneja_el_timeout() {
+    use std::time::Duration;
+    let result = tokio::time::timeout(
+        Duration::from_millis(100),
+        slow_operation(),
+    ).await;
+
+    assert!(result.is_err(), "debería haber expirado");
+}
+```
+
+## Patrones de organización de tests
+
+### Tests parametrizados con `rstest`
+
+```rust
+use rstest::{rstest, fixture};
+
+#[rstest]
+#[case("hello", 5)]
+#[case("", 0)]
+#[case("rust", 4)]
+fn test_longitud_de_cadena(#[case] input: &str, #[case] expected: usize) {
+    assert_eq!(input.len(), expected);
+}
+
+// Fixtures
+#[fixture]
+fn test_db() -> TestDb {
+    TestDb::new_in_memory()
+}
+
+#[rstest]
+fn test_insercion(test_db: TestDb) {
+    test_db.insert("key", "value");
+    assert_eq!(test_db.get("key"), Some("value".into()));
+}
+```
+
+### Helpers de test
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Crea un usuario de prueba con valores por defecto razonables.
+    fn make_user(name: &str) -> User {
+        User::new(name, &format!("{name}@test.com")).unwrap()
+    }
+
+    #[test]
+    fn nombre_visible_del_usuario() {
+        let user = make_user("alice");
+        assert_eq!(user.display_name(), "alice");
+    }
+}
+```
+
+## Testing basado en propiedades con `proptest`
+
+### Tests de propiedades básicos
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn encode_decode_ida_y_vuelta(input in ".*") {
+        let encoded = encode(&input);
+        let decoded = decode(&encoded).unwrap();
+        assert_eq!(input, decoded);
+    }
+
+    #[test]
+    fn ordenar_preserva_la_longitud(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
+        let original_len = vec.len();
+        vec.sort();
+        assert_eq!(vec.len(), original_len);
+    }
+
+    #[test]
+    fn ordenar_produce_salida_ordenada(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
+        vec.sort();
+        for window in vec.windows(2) {
+            assert!(window[0] <= window[1]);
+        }
+    }
+}
+```
+
+### Estrategias personalizadas
+
+```rust
+use proptest::prelude::*;
+
+fn valid_email() -> impl Strategy<Value = String> {
+    ("[a-z]{1,10}", "[a-z]{1,5}")
+        .prop_map(|(user, domain)| format!("{user}@{domain}.com"))
+}
+
+proptest! {
+    #[test]
+    fn acepta_emails_validos(email in valid_email()) {
+        assert!(User::new("Test", &email).is_ok());
+    }
+}
+```
+
+## Mocking con `mockall`
+
+### Mocking basado en traits
+
+```rust
+use mockall::{automock, predicate::eq};
+
+#[automock]
+trait UserRepository {
+    fn find_by_id(&self, id: u64) -> Option<User>;
+    fn save(&self, user: &User) -> Result<(), StorageError>;
+}
+
+#[test]
+fn el_servicio_devuelve_usuario_cuando_existe() {
+    let mut mock = MockUserRepository::new();
+    mock.expect_find_by_id()
+        .with(eq(42))
+        .times(1)
+        .returning(|_| Some(User { id: 42, name: "Alice".into() }));
+
+    let service = UserService::new(Box::new(mock));
+    let user = service.get_user(42).unwrap();
+    assert_eq!(user.name, "Alice");
+}
+
+#[test]
+fn el_servicio_devuelve_none_cuando_no_existe() {
+    let mut mock = MockUserRepository::new();
+    mock.expect_find_by_id()
+        .returning(|_| None);
+
+    let service = UserService::new(Box::new(mock));
+    assert!(service.get_user(99).is_none());
+}
+```
+
+## Doc tests
+
+### Documentación ejecutable
+
+```rust
+/// Suma dos números.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::add;
+///
+/// assert_eq!(add(2, 3), 5);
+/// assert_eq!(add(-1, 1), 0);
+/// ```
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+
+/// Parsea una cadena de configuración.
+///
+/// # Errors
+///
+/// Devuelve `Err` si la entrada no es TOML válido.
+///
+/// ```no_run
+/// use my_crate::parse_config;
+///
+/// let config = parse_config(r#"port = 8080"#).unwrap();
+/// assert_eq!(config.port, 8080);
+/// ```
+///
+/// ```no_run
+/// use my_crate::parse_config;
+///
+/// assert!(parse_config("}{invalid").is_err());
+/// ```
+pub fn parse_config(input: &str) -> Result<Config, ParseError> {
+    todo!()
+}
+```
+
+## Benchmarks con Criterion
+
+```toml
+# Cargo.toml
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "benchmark"
+harness = false
+```
+
+```rust
+// 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 tests
+
+### Ejecutar la cobertura
+
+```bash
+# Instalar: cargo install cargo-llvm-cov (o taiki-e/install-action en CI)
+cargo llvm-cov                    # Resumen
+cargo llvm-cov --html             # Informe HTML
+cargo llvm-cov --lcov > lcov.info # Formato LCOV para CI
+cargo llvm-cov --fail-under-lines 80  # Falla por debajo del umbral
+```
+
+### Objetivos de cobertura
+
+| Tipo de código | Objetivo |
+|-----------|--------|
+| Lógica de negocio crítica | 100 % |
+| API pública | 90 %+ |
+| Código general | 80 %+ |
+| Bindings generados / FFI | Excluir |
+
+## Comandos de testing
+
+```bash
+cargo test                        # Ejecuta todos los tests
+cargo test -- --nocapture         # Muestra la salida de println
+cargo test test_name              # Ejecuta los tests que coinciden con el patrón
+cargo test --lib                  # Solo tests unitarios
+cargo test --test api_test        # Solo tests de integración
+cargo test --doc                  # Solo doc tests
+cargo test --no-fail-fast         # No se detiene en el primer fallo
+cargo test -- --ignored           # Ejecuta los tests ignorados
+```
+
+## Buenas prácticas
+
+**SÍ:**
+- Escribe los tests PRIMERO (TDD).
+- Usa módulos `#[cfg(test)]` para tests unitarios.
+- Testea el comportamiento, no la implementación.
+- Usa nombres de test descriptivos que expliquen el escenario.
+- Prefiere `assert_eq!` a `assert!` para mejores mensajes de error.
+- Usa `?` en tests que devuelven `Result` para una salida de error más limpia.
+- Mantén los tests independientes — sin estado mutable compartido.
+
+**NO:**
+- Uses `#[should_panic]` cuando puedas testear `Result::is_err()`.
+- Mockees todo — prefiere tests de integración cuando sea viable.
+- Ignores tests inestables — arréglalos o ponlos en cuarentena.
+- Uses `sleep()` en tests — usa canales, barreras o `tokio::time::pause()`.
+- Te saltes el testing de las rutas de error.
+
+## Integración en CI
+
+```yaml
+# GitHub Actions
+test:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - uses: dtolnay/rust-toolchain@stable
+      with:
+        components: clippy, rustfmt
+
+    - name: Verificar el formato
+      run: cargo fmt --check
+
+    - name: Clippy
+      run: cargo clippy -- -D warnings
+
+    - name: Ejecutar tests
+      run: cargo test
+
+    - uses: taiki-e/install-action@cargo-llvm-cov
+
+    - name: Cobertura
+      run: cargo llvm-cov --fail-under-lines 80
+```
+
+**Recuerda**: los tests son documentación. Muestran cómo debe usarse tu código. Escríbelos con claridad y mantenlos al día.
+
+## Skills relacionadas
+
+- `patrones-rust`
+- `flujo-tdd`