theus-cli 0.2.82 → 0.2.84

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

@@ -1,506 +0,0 @@
----
-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`