theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,479 @@
+---
+name: testing-perl
+description: Patrones de testing en Perl con Test2::V0, Test::More, el runner prove, mocking, cobertura con Devel::Cover y metodología TDD.
+---
+
+# Patrones de testing en Perl
+
+Estrategias de testing integrales para aplicaciones Perl usando Test2::V0, Test::More, prove y metodología TDD.
+
+## Cuándo usarla
+
+- Al escribir código Perl nuevo (sigue TDD: rojo, verde, refactor).
+- Al diseñar suites de tests para módulos o aplicaciones Perl.
+- Al revisar la cobertura de tests de código Perl.
+- Al montar infraestructura de testing para Perl.
+- Al migrar tests de Test::More a Test2::V0.
+- Al depurar tests Perl que fallan.
+
+## Flujo TDD
+
+Sigue siempre el ciclo ROJO-VERDE-REFACTOR.
+
+```perl
+# Paso 1: ROJO — escribir un test que falle
+# t/unit/calculator.t
+use v5.36;
+use Test2::V0;
+
+use lib 'lib';
+use Calculator;
+
+subtest 'suma' => sub {
+    my $calc = Calculator->new;
+    is($calc->add(2, 3), 5, 'suma dos números');
+    is($calc->add(-1, 1), 0, 'maneja negativos');
+};
+
+done_testing;
+
+# Paso 2: VERDE — escribir la implementación mínima
+# lib/Calculator.pm
+package Calculator;
+use v5.36;
+use Moo;
+
+sub add($self, $a, $b) {
+    return $a + $b;
+}
+
+1;
+
+# Paso 3: REFACTOR — mejorar mientras los tests siguen en verde
+# Ejecutar: prove -lv t/unit/calculator.t
+```
+
+## Fundamentos de Test::More
+
+El módulo estándar de testing de Perl — muy usado, viene en el core.
+
+### Aserciones básicas
+
+```perl
+use v5.36;
+use Test::More;
+
+# Plan por adelantado o done_testing
+# plan tests => 5;  # Plan fijo (opcional)
+
+# Igualdad
+is($result, 42, 'devuelve el valor correcto');
+isnt($result, 0, 'distinto de cero');
+
+# Booleanos
+ok($user->is_active, 'el usuario está activo');
+ok(!$user->is_banned, 'el usuario no está bloqueado');
+
+# Comparación profunda
+is_deeply(
+    $got,
+    { name => 'Alice', roles => ['admin'] },
+    'devuelve la estructura esperada'
+);
+
+# Coincidencia de patrones
+like($error, qr/not found/i, 'el error menciona "not found"');
+unlike($output, qr/password/, 'la salida oculta la contraseña');
+
+# Comprobación de tipo
+isa_ok($obj, 'MyApp::User');
+can_ok($obj, 'save', 'delete');
+
+done_testing;
+```
+
+### SKIP y TODO
+
+```perl
+use v5.36;
+use Test::More;
+
+# Omitir tests condicionalmente
+SKIP: {
+    skip 'Sin base de datos configurada', 2 unless $ENV{TEST_DB};
+
+    my $db = connect_db();
+    ok($db->ping, 'la base de datos responde');
+    is($db->version, '15', 'versión correcta de PostgreSQL');
+}
+
+# Marcar fallos esperados
+TODO: {
+    local $TODO = 'La caché aún no está implementada';
+    is($cache->get('key'), 'value', 'la caché devuelve el valor');
+}
+
+done_testing;
+```
+
+## Test2::V0, el framework moderno
+
+Test2::V0 es el reemplazo moderno de Test::More — aserciones más ricas, mejores diagnósticos y extensible.
+
+### ¿Por qué Test2?
+
+- Comparación profunda superior con builders de hash/array.
+- Mejor salida de diagnóstico ante fallos.
+- Subtests con un scoping más limpio.
+- Extensible vía plugins Test2::Tools::*.
+- Retrocompatible con tests de Test::More.
+
+### Comparación profunda con builders
+
+```perl
+use v5.36;
+use Test2::V0;
+
+# Builder de hash — comprobar estructura parcial
+is(
+    $user->to_hash,
+    hash {
+        field name  => 'Alice';
+        field email => match(qr/\@example\.com$/);
+        field age   => validator(sub { $_ >= 18 });
+        # Ignorar el resto de campos
+        etc();
+    },
+    'el usuario tiene los campos esperados'
+);
+
+# Builder de array
+is(
+    $result,
+    array {
+        item 'first';
+        item match(qr/^second/);
+        item DNE();  # Does Not Exist — verificar que no hay elementos extra
+    },
+    'el resultado coincide con la lista esperada'
+);
+
+# Bag — comparación independiente del orden
+is(
+    $tags,
+    bag {
+        item 'perl';
+        item 'testing';
+        item 'tdd';
+    },
+    'tiene todas las etiquetas requeridas sin importar el orden'
+);
+```
+
+### Subtests
+
+```perl
+use v5.36;
+use Test2::V0;
+
+subtest 'Creación de usuario' => sub {
+    my $user = User->new(name => 'Alice', email => 'alice@example.com');
+    ok($user, 'objeto usuario creado');
+    is($user->name, 'Alice', 'el nombre está asignado');
+    is($user->email, 'alice@example.com', 'el correo está asignado');
+};
+
+subtest 'Validación de usuario' => sub {
+    my $warnings = warns {
+        User->new(name => '', email => 'bad');
+    };
+    ok($warnings, 'advierte ante datos inválidos');
+};
+
+done_testing;
+```
+
+### Testing de excepciones con Test2
+
+```perl
+use v5.36;
+use Test2::V0;
+
+# Comprobar que el código muere
+like(
+    dies { divide(10, 0) },
+    qr/División por cero/,
+    'muere al dividir por cero'
+);
+
+# Comprobar que el código sobrevive
+ok(lives { divide(10, 2) }, 'la división tiene éxito') or note($@);
+
+# Patrón combinado
+subtest 'manejo de errores' => sub {
+    ok(lives { parse_config('valid.json') }, 'la config válida se parsea');
+    like(
+        dies { parse_config('missing.json') },
+        qr/Cannot open/,
+        'el archivo ausente muere con mensaje'
+    );
+};
+
+done_testing;
+```
+
+## Organización de tests y prove
+
+### Estructura de directorios
+
+```text
+t/
+├── 00-load.t              # Verificar que los módulos compilan
+├── 01-basic.t             # Funcionalidad central
+├── unit/
+│   ├── config.t           # Tests unitarios por módulo
+│   ├── user.t
+│   └── util.t
+├── integration/
+│   ├── database.t
+│   └── api.t
+├── lib/
+│   └── TestHelper.pm      # Utilidades de test compartidas
+└── fixtures/
+    ├── config.json        # Archivos de datos de prueba
+    └── users.csv
+```
+
+### Comandos de prove
+
+```bash
+# Ejecutar todos los tests
+prove -l t/
+
+# Salida detallada
+prove -lv t/
+
+# Ejecutar un test concreto
+prove -lv t/unit/user.t
+
+# Búsqueda recursiva
+prove -lr t/
+
+# Ejecución en paralelo (8 jobs)
+prove -lr -j8 t/
+
+# Ejecutar solo los tests que fallaron en la última corrida
+prove -l --state=failed t/
+
+# Salida con color y cronómetro
+prove -l --color --timer t/
+
+# Salida TAP para CI
+prove -l --formatter TAP::Formatter::JUnit t/ > results.xml
+```
+
+### Configuración .proverc
+
+```text
+-l
+--color
+--timer
+-r
+-j4
+--state=save
+```
+
+## Fixtures y setup/teardown
+
+### Aislamiento por subtest
+
+```perl
+use v5.36;
+use Test2::V0;
+use File::Temp qw(tempdir);
+use Path::Tiny;
+
+subtest 'procesamiento de archivos' => sub {
+    # Setup
+    my $dir = tempdir(CLEANUP => 1);
+    my $file = path($dir, 'input.txt');
+    $file->spew_utf8("linea1\nlinea2\nlinea3\n");
+
+    # Test
+    my $result = process_file("$file");
+    is($result->{line_count}, 3, 'cuenta las líneas');
+
+    # El teardown ocurre automáticamente (CLEANUP => 1)
+};
+```
+
+### Helpers de test compartidos
+
+Coloca los helpers reutilizables en `t/lib/TestHelper.pm` y cárgalos con `use lib 't/lib'`. Exporta funciones factoría como `create_test_db()`, `create_temp_dir()` y `fixture_path()` vía `Exporter`.
+
+## Mocking
+
+### Test::MockModule
+
+```perl
+use v5.36;
+use Test2::V0;
+use Test::MockModule;
+
+subtest 'mock de una API externa' => sub {
+    my $mock = Test::MockModule->new('MyApp::API');
+
+    # Bien: el mock devuelve datos controlados
+    $mock->mock(fetch_user => sub ($self, $id) {
+        return { id => $id, name => 'Usuario Mock', email => 'mock@test.com' };
+    });
+
+    my $api = MyApp::API->new;
+    my $user = $api->fetch_user(42);
+    is($user->{name}, 'Usuario Mock', 'devuelve el usuario mockeado');
+
+    # Verificar el número de llamadas
+    my $call_count = 0;
+    $mock->mock(fetch_user => sub { $call_count++; return {} });
+    $api->fetch_user(1);
+    $api->fetch_user(2);
+    is($call_count, 2, 'fetch_user se llamó dos veces');
+
+    # El mock se restaura automáticamente cuando $mock sale de scope
+};
+
+# Mal: monkey-patching sin restauración
+# *MyApp::API::fetch_user = sub { ... };  # NUNCA — se filtra entre tests
+```
+
+Para objetos mock ligeros, usa `Test::MockObject` para crear dobles de prueba inyectables con `->mock()` y verifica las llamadas con `->called_ok()`.
+
+## Cobertura con Devel::Cover
+
+### Ejecutar la cobertura
+
+```bash
+# Informe básico de cobertura
+cover -test
+
+# O paso a paso
+perl -MDevel::Cover -Ilib t/unit/user.t
+cover
+
+# Informe HTML
+cover -report html
+open cover_db/coverage.html
+
+# Umbrales específicos
+cover -test -report text | grep 'Total'
+
+# Amigable con CI: fallar por debajo del umbral
+cover -test && cover -report text -select '^lib/' \
+  | perl -ne 'if (/Total.*?(\d+\.\d+)/) { exit 1 if $1 < 80 }'
+```
+
+### Testing de integración
+
+Usa SQLite en memoria para los tests de base de datos y mockea HTTP::Tiny para los tests de API.
+
+```perl
+use v5.36;
+use Test2::V0;
+use DBI;
+
+subtest 'integración con base de datos' => sub {
+    my $dbh = DBI->connect('dbi:SQLite:dbname=:memory:', '', '', {
+        RaiseError => 1,
+    });
+    $dbh->do('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+
+    $dbh->prepare('INSERT INTO users (name) VALUES (?)')->execute('Alice');
+    my $row = $dbh->selectrow_hashref('SELECT * FROM users WHERE name = ?', undef, 'Alice');
+    is($row->{name}, 'Alice', 'usuario insertado y recuperado');
+};
+
+done_testing;
+```
+
+## Buenas prácticas
+
+### SÍ
+
+- **Sigue TDD**: escribe los tests antes de la implementación (rojo-verde-refactor).
+- **Usa Test2::V0**: aserciones modernas, mejores diagnósticos.
+- **Usa subtests**: agrupa aserciones relacionadas, aísla el estado.
+- **Mockea las dependencias externas**: red, base de datos, sistema de archivos.
+- **Usa `prove -l`**: incluye siempre lib/ en `@INC`.
+- **Nombra los tests con claridad**: `'el login con contraseña inválida falla'`.
+- **Prueba los casos límite**: strings vacíos, undef, cero, valores frontera.
+- **Apunta a 80 %+ de cobertura**: céntrate en las rutas de lógica de negocio.
+- **Mantén los tests rápidos**: mockea la E/S, usa bases de datos en memoria.
+
+### NO
+
+- **No pruebes la implementación**: prueba el comportamiento y la salida, no las tripas.
+- **No compartas estado entre subtests**: cada subtest debe ser independiente.
+- **No omitas `done_testing`**: garantiza que todos los tests planificados corrieron.
+- **No sobre-mockees**: mockea solo las fronteras, no el código bajo prueba.
+- **No uses `Test::More` en proyectos nuevos**: prefiere Test2::V0.
+- **No ignores los fallos de tests**: todos deben pasar antes del merge.
+- **No pruebes los módulos de CPAN**: confía en que las librerías funcionan.
+- **No escribas tests frágiles**: evita coincidencias de string demasiado específicas.
+
+## Referencia rápida
+
+| Tarea | Comando / patrón |
+|---|---|
+| Ejecutar todos los tests | `prove -lr t/` |
+| Ejecutar un test en detalle | `prove -lv t/unit/user.t` |
+| Corrida en paralelo | `prove -lr -j8 t/` |
+| Informe de cobertura | `cover -test && cover -report html` |
+| Probar igualdad | `is($got, $expected, 'etiqueta')` |
+| Comparación profunda | `is($got, hash { field k => 'v'; etc() }, 'etiqueta')` |
+| Probar una excepción | `like(dies { ... }, qr/msg/, 'etiqueta')` |
+| Probar que no hay excepción | `ok(lives { ... }, 'etiqueta')` |
+| Mockear un método | `Test::MockModule->new('Pkg')->mock(m => sub { ... })` |
+| Omitir tests | `SKIP: { skip 'motivo', $count unless $cond; ... }` |
+| Tests TODO | `TODO: { local $TODO = 'motivo'; ... }` |
+
+## Errores comunes
+
+### Olvidar `done_testing`
+
+```perl
+# Mal: el archivo de test corre pero no verifica que todo se ejecutó
+use Test2::V0;
+is(1, 1, 'funciona');
+# Falta done_testing — bugs silenciosos si se salta código de test
+
+# Bien: termina siempre con done_testing
+use Test2::V0;
+is(1, 1, 'funciona');
+done_testing;
+```
+
+### Olvidar el flag `-l`
+
+```bash
+# Mal: no se encuentran los módulos de lib/
+prove t/unit/user.t
+# Can't locate MyApp/User.pm in @INC
+
+# Bien: incluir lib/ en @INC
+prove -l t/unit/user.t
+```
+
+### Sobre-mockear
+
+Mockea la *dependencia*, no el código bajo prueba. Si tu test solo verifica que un mock devuelve lo que le dijiste, no prueba nada.
+
+### Contaminación entre tests
+
+Usa variables `my` dentro de los subtests — nunca `our` — para evitar que el estado se filtre entre tests.
+
+**Recuerda**: los tests son tu red de seguridad. Mantenlos rápidos, enfocados e independientes. Usa Test2::V0 para proyectos nuevos, prove para ejecutarlos y Devel::Cover para rendir cuentas.
+
+## Skills relacionadas
+
+- `patrones-perl`
+- `seguridad-perl`

package/vendor/theus-arsenal/skills/testing-protocolos-di-swift/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: testing-protocolos-di-swift
+description: Inyección de dependencias basada en protocolos para código Swift testeable — mocks de
+  sistema de archivos, red y APIs externas mediante protocolos pequeños y enfocados, con Swift Testing.
+---
+
+# Inyección de dependencias por protocolos para testing en Swift
+
+Patrones para hacer testeable el código Swift abstrayendo las dependencias externas (sistema de archivos, red, iCloud) detrás de protocolos pequeños y enfocados. Permite tests deterministas sin I/O real.
+
+## Cuándo usarla
+
+- Al escribir código Swift que accede al sistema de archivos, la red o APIs externas.
+- Cuando necesitas probar rutas de manejo de errores sin provocar fallos reales.
+- Al construir módulos que funcionan en varios entornos (app, tests, previews de SwiftUI).
+- Al diseñar arquitectura testeable con concurrencia de Swift (actores, Sendable).
+
+## Patrón central
+
+### 1. Define protocolos pequeños y enfocados
+
+Cada protocolo cubre exactamente una preocupación externa.
+
+```swift
+// Acceso al sistema de archivos
+public protocol FileSystemProviding: Sendable {
+    func containerURL(for purpose: Purpose) -> URL?
+}
+
+// Operaciones de lectura/escritura de archivos
+public protocol FileAccessorProviding: Sendable {
+    func read(from url: URL) throws -> Data
+    func write(_ data: Data, to url: URL) throws
+    func fileExists(at url: URL) -> Bool
+}
+
+// Almacenamiento de bookmarks (p. ej., para apps con sandbox)
+public protocol BookmarkStorageProviding: Sendable {
+    func saveBookmark(_ data: Data, for key: String) throws
+    func loadBookmark(for key: String) throws -> Data?
+}
+```
+
+### 2. Crea las implementaciones por defecto (producción)
+
+```swift
+public struct DefaultFileSystemProvider: FileSystemProviding {
+    public init() {}
+
+    public func containerURL(for purpose: Purpose) -> URL? {
+        FileManager.default.url(forUbiquityContainerIdentifier: nil)
+    }
+}
+
+public struct DefaultFileAccessor: FileAccessorProviding {
+    public init() {}
+
+    public func read(from url: URL) throws -> Data {
+        try Data(contentsOf: url)
+    }
+
+    public func write(_ data: Data, to url: URL) throws {
+        try data.write(to: url, options: .atomic)
+    }
+
+    public func fileExists(at url: URL) -> Bool {
+        FileManager.default.fileExists(atPath: url.path)
+    }
+}
+```
+
+### 3. Crea implementaciones mock para los tests
+
+```swift
+public final class MockFileAccessor: FileAccessorProviding, @unchecked Sendable {
+    public var files: [URL: Data] = [:]
+    public var readError: Error?
+    public var writeError: Error?
+
+    public init() {}
+
+    public func read(from url: URL) throws -> Data {
+        if let error = readError { throw error }
+        guard let data = files[url] else {
+            throw CocoaError(.fileReadNoSuchFile)
+        }
+        return data
+    }
+
+    public func write(_ data: Data, to url: URL) throws {
+        if let error = writeError { throw error }
+        files[url] = data
+    }
+
+    public func fileExists(at url: URL) -> Bool {
+        files[url] != nil
+    }
+}
+```
+
+### 4. Inyecta las dependencias con parámetros por defecto
+
+El código de producción usa los defaults; los tests inyectan mocks.
+
+```swift
+public actor SyncManager {
+    private let fileSystem: FileSystemProviding
+    private let fileAccessor: FileAccessorProviding
+
+    public init(
+        fileSystem: FileSystemProviding = DefaultFileSystemProvider(),
+        fileAccessor: FileAccessorProviding = DefaultFileAccessor()
+    ) {
+        self.fileSystem = fileSystem
+        self.fileAccessor = fileAccessor
+    }
+
+    public func sync() async throws {
+        guard let containerURL = fileSystem.containerURL(for: .sync) else {
+            throw SyncError.containerNotAvailable
+        }
+        let data = try fileAccessor.read(
+            from: containerURL.appendingPathComponent("data.json")
+        )
+        // Procesar los datos...
+    }
+}
+```
+
+### 5. Escribe los tests con Swift Testing
+
+```swift
+import Testing
+
+@Test("El sync manager maneja un contenedor ausente")
+func testMissingContainer() async {
+    let mockFileSystem = MockFileSystemProvider(containerURL: nil)
+    let manager = SyncManager(fileSystem: mockFileSystem)
+
+    await #expect(throws: SyncError.containerNotAvailable) {
+        try await manager.sync()
+    }
+}
+
+@Test("El sync manager lee los datos correctamente")
+func testReadData() async throws {
+    let mockFileAccessor = MockFileAccessor()
+    mockFileAccessor.files[testURL] = testData
+
+    let manager = SyncManager(fileAccessor: mockFileAccessor)
+    let result = try await manager.loadData()
+
+    #expect(result == expectedData)
+}
+
+@Test("El sync manager maneja errores de lectura con gracia")
+func testReadError() async {
+    let mockFileAccessor = MockFileAccessor()
+    mockFileAccessor.readError = CocoaError(.fileReadCorruptFile)
+
+    let manager = SyncManager(fileAccessor: mockFileAccessor)
+
+    await #expect(throws: SyncError.self) {
+        try await manager.sync()
+    }
+}
+```
+
+## Buenas prácticas
+
+- **Responsabilidad única**: cada protocolo debe cubrir una sola preocupación — no crees "protocolos dios" con muchos métodos.
+- **Conformance a Sendable**: obligatoria cuando los protocolos cruzan fronteras de actor.
+- **Parámetros por defecto**: deja que producción use las implementaciones reales por defecto; solo los tests especifican mocks.
+- **Simulación de errores**: diseña los mocks con propiedades de error configurables para probar las rutas de fallo.
+- **Solo mockea las fronteras**: mockea dependencias externas (sistema de archivos, red, APIs), no tipos internos.
+
+## Antipatrones a evitar
+
+- Crear un único protocolo grande que cubra todo el acceso externo.
+- Mockear tipos internos que no tienen dependencias externas.
+- Usar condicionales `#if DEBUG` en lugar de inyección de dependencias real.
+- Olvidar la conformance a `Sendable` cuando se usa con actores.
+- Sobreingeniería: si un tipo no tiene dependencias externas, no necesita un protocolo.
+
+## Cuándo aplicarla
+
+- Cualquier código Swift que toque el sistema de archivos, la red o APIs externas.
+- Tests de rutas de error difíciles de provocar en entornos reales.
+- Módulos que deben funcionar en contextos de app, tests y previews de SwiftUI.
+- Apps con concurrencia de Swift (actores, concurrencia estructurada) que necesitan arquitectura testeable.
+
+## Skills relacionadas
+
+- `patrones-swiftui`
+- `concurrencia-swift-6-2`
+- `persistencia-actores-swift`