theus-cli-linux-x64 1.2.2 → 1.4.0

package/vendor/theus-arsenal/skills/tdd-laravel/SKILL.md

@@ -1,673 +0,0 @@
----
-name: tdd-laravel
-description: Estrategias de testing para Laravel con PHPUnit, Pest, factories de modelos, pruebas HTTP, autenticación con Sanctum, mocking y cobertura.
----
-
-# Testing en Laravel con TDD
-
-Desarrollo dirigido por pruebas para aplicaciones Laravel usando PHPUnit, Pest, factories de Laravel y los helpers de testing del framework.
-
-## Cuándo usarla
-
-- Al escribir nuevas aplicaciones o funcionalidades en Laravel
-- Al implementar endpoints de API con autenticación Sanctum o Passport
-- Al probar modelos Eloquent, relaciones, scopes y accessors
-- Al montar la infraestructura de testing de un proyecto Laravel
-- Al escribir pruebas de feature para controladores HTTP y form requests
-- Al mockear servicios externos (colas, correo, notificaciones, HTTP)
-
-## Flujo TDD para Laravel
-
-### Ciclo Rojo-Verde-Refactor
-
-```php
-// Paso 1: ROJO — escribe una prueba que falle
-public function test_se_puede_crear_un_producto(): void
-{
-    $product = Product::factory()->create(['name' => 'Producto de prueba']);
-    $this->assertDatabaseHas('products', ['name' => 'Producto de prueba']);
-}
-
-// Paso 2: VERDE — escribe la migración, el modelo y la factory
-// Paso 3: REFACTOR — mejora manteniendo las pruebas en verde
-```
-
-## Configuración
-
-### Configuración de PHPUnit
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
-         bootstrap="vendor/autoload.php"
-         colors="true">
-    <testsuites>
-        <testsuite name="Unit">
-            <directory suffix="Test.php">tests/Unit</directory>
-        </testsuite>
-        <testsuite name="Feature">
-            <directory suffix="Test.php">tests/Feature</directory>
-        </testsuite>
-    </testsuites>
-    <php>
-        <env name="APP_ENV" value="testing"/>
-        <env name="BCRYPT_ROUNDS" value="4"/>
-        <env name="CACHE_STORE" value="array"/>
-        <env name="DB_CONNECTION" value="sqlite"/>
-        <env name="DB_DATABASE" value=":memory:"/>
-        <env name="MAIL_MAILER" value="array"/>
-        <env name="QUEUE_CONNECTION" value="sync"/>
-        <env name="SESSION_DRIVER" value="array"/>
-    </php>
-</phpunit>
-```
-
-### Configuración del TestCase base
-
-```php
-namespace Tests;
-
-use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
-
-abstract class TestCase extends BaseTestCase
-{
-    protected function setUp(): void
-    {
-        parent::setUp();
-        // Llama a $this->withoutExceptionHandling() solo en pruebas que
-        // prueban excepciones no HTTP; suprime assertStatus(), etc.
-    }
-
-    // Helper: autenticar y devolver el usuario
-    protected function actingAsUser(): mixed
-    {
-        $user = \App\Models\User::factory()->create();
-        $this->actingAs($user);
-        return $user;
-    }
-
-    protected function actingAsAdmin(): mixed
-    {
-        $admin = \App\Models\User::factory()->admin()->create();
-        $this->actingAs($admin);
-        return $admin;
-    }
-}
-```
-
-## Factories de modelos
-
-```php
-// database/factories/UserFactory.php
-class UserFactory extends Factory
-{
-    protected static ?string $password = null;
-
-    public function definition(): array
-    {
-        return [
-            'name' => fake()->name(),
-            'email' => fake()->unique()->safeEmail(),
-            'email_verified_at' => now(),
-            'password' => static::$password ??= Hash::make('password'),
-            'remember_token' => Str::random(10),
-            'role' => 'user',
-        ];
-    }
-
-    public function admin(): static
-    {
-        return $this->state(fn (array $attributes) => ['role' => 'admin']);
-    }
-
-    public function unverified(): static
-    {
-        return $this->state(fn (array $attributes) => ['email_verified_at' => null]);
-    }
-}
-
-// database/factories/ProductFactory.php
-class ProductFactory extends Factory
-{
-    public function definition(): array
-    {
-        return [
-            'name' => fake()->unique()->words(3, true),
-            'slug' => fn (array $attrs) => Str::slug($attrs['name']),
-            'description' => fake()->paragraph(),
-            'price' => fake()->numberBetween(100, 100000),
-            'stock' => fake()->numberBetween(0, 100),
-            'is_active' => true,
-            'user_id' => UserFactory::new(),
-        ];
-    }
-
-    public function outOfStock(): static
-    {
-        return $this->state(fn (array $attributes) => ['stock' => 0]);
-    }
-}
-```
-
-### Uso de factories
-
-```php
-$user = User::factory()->create();
-$admin = User::factory()->admin()->create();
-$product = Product::factory()->create(['user_id' => $user->id]);
-$products = Product::factory()->count(10)->create();
-$draft = Product::factory()->make(); // No persistido
-
-// Con relaciones
-$user = User::factory()->has(Product::factory()->count(3))->create();
-
-// Secuencias
-User::factory()->count(3)->sequence(
-    ['role' => 'admin'], ['role' => 'editor'], ['role' => 'user'],
-)->create();
-```
-
-## Testing de modelos
-
-```php
-namespace Tests\Unit\Models;
-
-use App\Models\User;
-use App\Models\Product;
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Tests\TestCase;
-
-class UserTest extends TestCase
-{
-    use RefreshDatabase;
-
-    public function test_oculta_atributos_sensibles(): void
-    {
-        $user = User::factory()->create();
-        $this->assertArrayNotHasKey('password', $user->toArray());
-    }
-
-    public function test_el_scope_admin_devuelve_solo_admins(): void
-    {
-        User::factory()->admin()->create();
-        User::factory()->count(3)->create();
-
-        $this->assertCount(1, User::admin()->get());
-    }
-}
-
-class ProductTest extends TestCase
-{
-    use RefreshDatabase;
-
-    public function test_el_scope_active_filtra_correctamente(): void
-    {
-        Product::factory()->count(3)->create(['is_active' => true]);
-        Product::factory()->count(2)->create(['is_active' => false]);
-
-        $this->assertCount(3, Product::active()->get());
-    }
-
-    public function test_pertenece_a_un_usuario(): void
-    {
-        $user = User::factory()->create();
-        $product = Product::factory()->create(['user_id' => $user->id]);
-
-        $this->assertTrue($product->user->is($user));
-    }
-}
-```
-
-## Testing de features / HTTP
-
-```php
-namespace Tests\Feature\Http\Controllers;
-
-use App\Models\Product;
-use App\Models\User;
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Tests\TestCase;
-
-class ProductControllerTest extends TestCase
-{
-    use RefreshDatabase;
-
-    public function test_los_invitados_son_redirigidos_al_login(): void
-    {
-        $this->get(route('products.create'))->assertRedirect(route('login'));
-    }
-
-    public function test_almacena_un_producto_nuevo(): void
-    {
-        $user = User::factory()->create();
-        $this->actingAs($user);
-
-        $response = $this->post(route('products.store'), [
-            'name' => 'Producto nuevo',
-            'description' => 'Descripción',
-            'price' => 2999,
-            'stock' => 10,
-        ]);
-
-        $response->assertRedirect(route('products.index'));
-        $this->assertDatabaseHas('products', [
-            'name' => 'Producto nuevo',
-            'user_id' => $user->id,
-        ]);
-    }
-
-    public function test_valida_los_campos_obligatorios(): void
-    {
-        $this->actingAs(User::factory()->create());
-        $this->post(route('products.store'), [])
-            ->assertSessionHasErrors(['name', 'price']);
-    }
-
-    public function test_los_usuarios_no_pueden_modificar_productos_ajenos(): void
-    {
-        $owner = User::factory()->create();
-        $attacker = User::factory()->create();
-        $product = Product::factory()->create(['user_id' => $owner->id]);
-
-        $this->actingAs($attacker)
-            ->delete(route('products.destroy', $product))
-            ->assertForbidden();
-    }
-}
-```
-
-## Testing de API JSON
-
-```php
-namespace Tests\Feature\Http\Controllers\Api;
-
-use App\Models\Product;
-use App\Models\User;
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Tests\TestCase;
-
-class ProductApiTest extends TestCase
-{
-    use RefreshDatabase;
-
-    public function test_las_solicitudes_sin_autenticar_son_rechazadas(): void
-    {
-        $this->getJson('/api/products')->assertUnauthorized();
-    }
-
-    public function test_lista_productos_paginados(): void
-    {
-        $user = User::factory()->create();
-        Product::factory()->count(5)->create(['user_id' => $user->id]);
-
-        $response = $this->actingAs($user)->getJson('/api/products');
-
-        $response->assertOk();
-        $response->assertJsonCount(5, 'data');
-        $response->assertJsonStructure([
-            'data' => [['id', 'name', 'price']],
-            'meta' => ['current_page', 'last_page', 'total'],
-        ]);
-    }
-
-    public function test_crea_un_producto(): void
-    {
-        $user = User::factory()->create();
-
-        $response = $this->actingAs($user)->postJson('/api/products', [
-            'name' => 'Producto de API',
-            'price' => 4999,
-        ]);
-
-        $response->assertCreated();
-        $response->assertJsonPath('data.name', 'Producto de API');
-    }
-
-    public function test_los_usuarios_no_pueden_eliminar_productos_ajenos(): void
-    {
-        $owner = User::factory()->create();
-        $attacker = User::factory()->create();
-        $product = Product::factory()->create(['user_id' => $owner->id]);
-
-        $this->actingAs($attacker)
-            ->deleteJson("/api/products/{$product->id}")
-            ->assertForbidden();
-    }
-}
-```
-
-## Testing de autenticación de API con Sanctum
-
-```php
-namespace Tests\Feature\Http\Controllers\Api;
-
-use App\Models\User;
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Illuminate\Support\Facades\Hash;
-use Tests\TestCase;
-
-class AuthControllerTest extends TestCase
-{
-    use RefreshDatabase;
-
-    public function test_los_usuarios_pueden_registrarse(): void
-    {
-        $response = $this->postJson('/api/register', [
-            'name' => 'Usuario de prueba',
-            'email' => 'test@example.com',
-            'password' => 'Password123!',
-            'password_confirmation' => 'Password123!',
-        ]);
-
-        $response->assertCreated();
-        $response->assertJsonStructure(['data' => ['user', 'token']]);
-    }
-
-    public function test_los_usuarios_pueden_iniciar_sesion(): void
-    {
-        User::factory()->create([
-            'email' => 'test@example.com',
-            'password' => Hash::make('Password123!'),
-        ]);
-
-        $response = $this->postJson('/api/login', [
-            'email' => 'test@example.com',
-            'password' => 'Password123!',
-        ]);
-
-        $response->assertOk();
-        $response->assertJsonStructure(['data' => ['token']]);
-    }
-
-    public function test_los_usuarios_no_pueden_iniciar_sesion_con_contrasena_incorrecta(): void
-    {
-        User::factory()->create(['email' => 'test@example.com']);
-
-        $this->postJson('/api/login', [
-            'email' => 'test@example.com',
-            'password' => 'incorrecta',
-        ])->assertUnprocessable();
-    }
-
-    public function test_el_token_bearer_autentica_las_solicitudes(): void
-    {
-        $user = User::factory()->create();
-        $token = $user->createToken('test')->plainTextToken;
-
-        $this->withToken($token)
-            ->getJson('/api/user')
-            ->assertOk()
-            ->assertJsonPath('data.email', $user->email);
-    }
-}
-```
-
-## Mocking y fakes
-
-### HTTP fake
-
-```php
-use Illuminate\Support\Facades\Http;
-
-public function test_maneja_un_pago_exitoso(): void
-{
-    Http::fake([
-        'api.stripe.com/*' => Http::response(['id' => 'pi_123', 'status' => 'succeeded'], 200),
-    ]);
-
-    $result = (new PaymentService())->charge(2999);
-    $this->assertTrue($result->success);
-}
-
-public function test_maneja_un_fallo_de_la_pasarela(): void
-{
-    Http::fake([
-        'api.stripe.com/*' => Http::response(['error' => 'card_declined'], 402),
-    ]);
-
-    $this->expectException(PaymentFailedException::class);
-    (new PaymentService())->charge(2999);
-}
-
-public function test_reintenta_ante_timeout(): void
-{
-    Http::fake([
-        'api.stripe.com/*' => Http::sequence()
-            ->pushStatus(408)
-            ->pushStatus(200),
-    ]);
-
-    $this->assertTrue((new PaymentService())->charge(2999)->success);
-}
-```
-
-### Mail fake
-
-```php
-Mail::fake();
-
-$order->sendConfirmation();
-
-Mail::assertSent(OrderConfirmation::class, function ($mail) use ($order) {
-    return $mail->hasTo($order->user->email);
-});
-```
-
-### Notification fake
-
-```php
-Notification::fake();
-
-$user->notify(new WelcomeUser());
-
-Notification::assertSentTo($user, WelcomeUser::class);
-```
-
-### Queue fake
-
-```php
-Queue::fake();
-
-ProcessImage::dispatch($product);
-
-Queue::assertPushed(ProcessImage::class, function ($job) use ($product) {
-    return $job->product->id === $product->id;
-});
-```
-
-### Storage fake
-
-```php
-Storage::fake('public');
-
-$file = UploadedFile::fake()->image('foto.jpg', 200, 200);
-
-$response = $this->actingAs($user)->post('/avatar', [
-    'avatar' => $file,
-]);
-
-$response->assertSessionHasNoErrors();
-Storage::disk('public')->assertExists('avatars/' . $file->hashName());
-```
-
-### Event fake
-
-```php
-Event::fake();
-
-$order->markAsShipped();
-
-Event::assertDispatched(OrderShipped::class, function ($event) use ($order) {
-    return $event->order->id === $order->id;
-});
-```
-
-## Pruebas de comandos Artisan
-
-```php
-public function test_envia_boletines(): void
-{
-    Mail::fake();
-    User::factory()->count(5)->create(['subscribed' => true]);
-
-    $this->artisan('newsletter:send')
-        ->expectsOutput('Enviando boletín a 5 suscriptores...')
-        ->assertExitCode(0);
-
-    Mail::assertSent(NewsletterMail::class, 5);
-}
-
-public function test_maneja_la_ausencia_de_suscriptores(): void
-{
-    $this->artisan('newsletter:send')
-        ->expectsOutput('No se encontraron suscriptores.')
-        ->assertExitCode(0);
-}
-```
-
-## Pruebas de autorización
-
-```php
-public function test_los_usuarios_pueden_actualizar_sus_propios_posts(): void
-{
-    $user = User::factory()->create();
-    $post = Post::factory()->create(['user_id' => $user->id]);
-
-    $this->actingAs($user)
-        ->put(route('posts.update', $post), ['title' => 'Actualizado'])
-        ->assertRedirect();
-}
-
-public function test_los_usuarios_no_pueden_actualizar_posts_ajenos(): void
-{
-    $post = Post::factory()->create();
-    $this->actingAs(User::factory()->create())
-        ->put(route('posts.update', $post), ['title' => 'Hackeado'])
-        ->assertForbidden();
-}
-
-public function test_gate_before_da_acceso_total_al_super_admin(): void
-{
-    $super = User::factory()->create(['role' => 'super-admin']);
-    $post = Post::factory()->create();
-
-    $this->actingAs($super)
-        ->delete(route('posts.destroy', $post))
-        ->assertRedirect();
-
-    $this->assertSoftDeleted($post);
-}
-```
-
-## Pruebas de feature con Pest
-
-```php
-<?php
-
-use App\Models\Product;
-use App\Models\User;
-
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
-
-beforeEach(function () {
-    $this->user = User::factory()->create();
-    $this->actingAs($this->user);
-});
-
-it('lista productos', function () {
-    Product::factory()->count(3)->create(['user_id' => $this->user->id]);
-
-    $this->get(route('products.index'))
-        ->assertOk()
-        ->assertViewHas('products');
-});
-
-it('crea un producto con datos válidos', function () {
-    $this->post(route('products.store'), [
-        'name' => 'Producto de prueba', 'price' => 1999,
-    ])->assertRedirect();
-
-    $this->assertDatabaseHas('products', ['name' => 'Producto de prueba']);
-});
-
-it('falla la validación sin los campos obligatorios', function () {
-    $this->post(route('products.store'), [])
-        ->assertSessionHasErrors(['name', 'price']);
-});
-
-it('autoriza las actualizaciones', function () {
-    $other = User::factory()->create();
-    $product = Product::factory()->create(['user_id' => $other->id]);
-
-    $this->put(route('products.update', $product), ['name' => 'Hackeado'])
-        ->assertForbidden();
-});
-```
-
-## Cobertura
-
-```bash
-# PHPUnit (usa la salida clover para comprobaciones de umbral en CI)
-vendor/bin/phpunit --coverage-html coverage --coverage-clover clover.xml
-
-# Pest (soporte de umbral integrado)
-vendor/bin/pest --coverage --min=80
-```
-
-### Objetivos de cobertura
-
-| Componente | Objetivo |
-|-----------|--------|
-| Modelos | 95 %+ |
-| Actions/Services | 90 %+ |
-| Form Requests | 90 %+ |
-| Controladores | 85 %+ |
-| Policies | 95 %+ |
-| Global | 80 %+ |
-
-## Buenas prácticas de testing
-
-### SÍ
-
-- Usa factories en lugar de llamadas manuales a `create()`
-- Una aserción lógica por prueba
-- Nombres descriptivos: `test_los_invitados_no_pueden_crear_productos`
-- Prueba casos límite y fronteras de autorización
-- Mockea servicios externos con `Http::fake()`, `Mail::fake()`
-- Usa `RefreshDatabase` para un estado limpio
-
-### NO
-
-- No pruebes los internos de Laravel (confía en el framework)
-- No hagas que las pruebas dependan unas de otras
-- No sobre-mockees — mockea solo las fronteras de servicios
-- No pruebes métodos privados — prueba a través de la interfaz pública
-- No acoples las pruebas a la estructura HTML
-
-## Referencia rápida
-
-| Patrón | Uso |
-|---------|-------|
-| `RefreshDatabase` | Reinicia la base de datos entre pruebas |
-| `$this->actingAs($user)` | Autenticarse como usuario |
-| `$this->withToken($token)` | Autenticación bearer para APIs |
-| `Model::factory()->create()` | Crear un modelo con factory |
-| `Model::factory()->count(5)->create()` | Crear varios registros |
-| `Http::fake([...])` | Mockear llamadas HTTP |
-| `Mail::fake()` | Capturar correo enviado |
-| `Notification::fake()` | Capturar notificaciones enviadas |
-| `Queue::fake()` | Capturar jobs encolados |
-| `Event::fake()` | Capturar eventos despachados |
-| `Storage::fake('public')` | Capturar operaciones de archivos |
-| `assertDatabaseHas` | Aserta que existe una fila en BD |
-| `assertSoftDeleted` | Aserta un soft-delete |
-| `assertSessionHasErrors` | Aserta errores de validación |
-| `assertForbidden` | Aserta estado 403 |
-
-## Skills relacionadas
-
-- `patrones-laravel` — arquitectura de Laravel, Eloquent, rutas y patrones de API
-- `seguridad-laravel` — autenticación, autorización y código seguro en Laravel
-- `flujo-tdd` — el ciclo ROJO -> VERDE -> REFACTOR a nivel de repositorio
-- `patrones-backend` — patrones generales de API y base de datos en backend