> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/docs/archive/fase_4_testing_completada.md).

# FASE 4: Testing - Documentación Completa

## 📋 Resumen de Implementación

Se han creado **6 archivos de testing** con un total de **70+ tests** cubriendo:

* ✅ Autenticación (Login, Logout, Tokens)
* ✅ CRUD de Productos
* ✅ Sistema RBAC (Roles y Permisos)
* ✅ Tests Unitarios (Modelos)

***

## 📁 Archivos Creados

### 1. **tests/TestCase.php** (Base de Testing)

**Ubicación**: `/tests/TestCase.php`

**Métodos Helper**:

```php
- createEmpresa()           // Crea empresa de prueba
- createUsuario()           // Crea usuario con roles opcionales
- createAdminUsuario()      // Usuario administrador
- actingAsUsuario()         // Obtiene token de autenticación
- authenticatedJson()       // Helper para requests autenticados
- seedRoles()               // Seed de 4 roles básicos
- seedPermisos()            // Seed de 6 permisos básicos
- assignAllPermissionsToRole() // Asigna todos los permisos a un rol
```

**Uso**: Todos los tests heredan de esta clase base.

***

### 2. **tests/Feature/AuthTest.php** (11 Tests)

**Ubicación**: `/tests/Feature/AuthTest.php`

**Tests Implementados**:

1. ✅ `test_usuario_puede_hacer_login_con_credenciales_validas`
2. ✅ `test_login_falla_con_credenciales_invalidas`
3. ✅ `test_login_falla_con_usuario_inexistente`
4. ✅ `test_login_falla_con_usuario_inactivo`
5. ✅ `test_login_requiere_email_y_password`
6. ✅ `test_usuario_puede_hacer_logout`
7. ✅ `test_usuario_autenticado_puede_obtener_su_informacion`
8. ✅ `test_login_retorna_permisos_del_usuario`
9. ✅ `test_token_tiene_tiempo_de_expiracion`
10. ✅ `test_usuario_puede_tener_multiples_tokens_activos`
11. ✅ `test_logout_solo_elimina_token_actual`

**Endpoints Testeados**:

* `POST /api/login`
* `POST /api/logout`
* `GET /api/user`

***

### 3. **tests/Feature/ProductoTest.php** (12 Tests)

**Ubicación**: `/tests/Feature/ProductoTest.php`

**Tests Implementados**:

1. ✅ `test_puede_listar_productos_autenticado`
2. ✅ `test_puede_crear_producto_con_datos_validos`
3. ✅ `test_no_puede_crear_producto_sin_autenticacion`
4. ✅ `test_validacion_campos_requeridos_al_crear_producto`
5. ✅ `test_no_puede_crear_producto_con_codigo_duplicado`
6. ✅ `test_puede_actualizar_producto_existente`
7. ✅ `test_puede_eliminar_producto_soft_delete`
8. ✅ `test_puede_buscar_productos_por_nombre`
9. ✅ `test_puede_filtrar_productos_por_estado_activo`
10. ✅ `test_productos_estan_paginados`
11. ✅ `test_usuario_solo_ve_productos_de_su_empresa`
12. ✅ `test_productos_eliminados_no_aparecen_en_listado`

**Endpoints Testeados**:

* `GET /api/productos` (con filtros y búsqueda)
* `POST /api/productos`
* `PUT /api/productos/{id}`
* `DELETE /api/productos/{id}`

**Validaciones Testeadas**:

* Campos requeridos (nombre, código)
* Unicidad de código por empresa
* Multi-tenancy (aislamiento por empresa)
* Soft deletes
* Paginación
* Búsqueda FULLTEXT

***

### 4. **tests/Feature/PermissionTest.php** (17 Tests)

**Ubicación**: `/tests/Feature/PermissionTest.php`

**Tests Implementados**:

1. ✅ `test_usuario_administrador_tiene_todos_los_permisos`
2. ✅ `test_usuario_sin_rol_no_tiene_permisos`
3. ✅ `test_usuario_con_rol_especifico_tiene_solo_sus_permisos`
4. ✅ `test_puede_asignar_rol_a_usuario`
5. ✅ `test_puede_remover_rol_de_usuario`
6. ✅ `test_usuario_puede_tener_multiples_roles`
7. ✅ `test_permisos_se_heredan_de_todos_los_roles`
8. ✅ `test_rol_inactivo_no_otorga_permisos`
9. ✅ `test_puede_listar_todos_los_permisos`
10. ✅ `test_puede_listar_todos_los_roles`
11. ✅ `test_puede_asignar_permisos_a_rol`
12. ✅ `test_puede_remover_permisos_de_rol`
13. ✅ `test_permisos_agrupados_por_modulo`
14. ✅ `test_middleware_verifica_permisos_correctamente`
15. ✅ `test_usuario_obtiene_lista_de_sus_permisos`
16. ✅ `test_crear_rol_requiere_nombre_unico`
17. ✅ `test_solo_usuarios_con_permiso_pueden_gestionar_roles`

**Endpoints Testeados**:

* `GET /api/permisos`
* `GET /api/permisos/grouped`
* `GET /api/roles`
* `POST /api/roles/{id}/permisos`
* `DELETE /api/roles/{id}/permisos/{permiso_id}`
* `GET /api/user/permissions`

**Funcionalidades RBAC Testeadas**:

* Asignación de roles a usuarios
* Herencia de permisos desde múltiples roles
* Roles activos/inactivos
* Middleware de permisos
* Gestión de permisos por módulo

***

### 5. **tests/Unit/RoleTest.php** (10 Tests)

**Ubicación**: `/tests/Unit/RoleTest.php`

**Tests Unitarios**:

1. ✅ `test_rol_puede_tener_multiples_permisos`
2. ✅ `test_has_permission_verifica_permiso_por_slug`
3. ✅ `test_rol_tiene_relacion_con_usuarios`
4. ✅ `test_scope_activos_filtra_roles_activos`
5. ✅ `test_nombre_rol_se_normaliza_al_guardar`
6. ✅ `test_puede_eliminar_permiso_de_rol`
7. ✅ `test_rol_tiene_timestamps_personalizados`
8. ✅ `test_eliminacion_rol_no_elimina_usuarios`
9. ✅ `test_puede_sincronizar_permisos_de_rol`
10. ✅ `test_validacion_campos_requeridos`

**Métodos del Modelo Testeados**:

* `hasPermission()`
* `usuarios()` (relación)
* `permisos()` (relación)
* `scopeActivos()`
* Normalización de nombre
* Sincronización de permisos

***

### 6. **tests/Unit/UsuarioTest.php** (16 Tests)

**Ubicación**: `/tests/Unit/UsuarioTest.php`

**Tests Unitarios**:

1. ✅ `test_usuario_pertenece_a_empresa`
2. ✅ `test_usuario_puede_tener_multiples_roles`
3. ✅ `test_has_role_verifica_si_usuario_tiene_rol`
4. ✅ `test_has_permission_verifica_permisos_a_traves_de_roles`
5. ✅ `test_usuario_sin_roles_no_tiene_permisos`
6. ✅ `test_get_all_permissions_retorna_todos_los_permisos`
7. ✅ `test_password_hash_se_usa_para_autenticacion`
8. ✅ `test_usuario_puede_tener_cargo`
9. ✅ `test_timestamps_personalizados_funcionan`
10. ✅ `test_usuario_activo_puede_iniciar_sesion`
11. ✅ `test_usuario_inactivo_no_puede_iniciar_sesion`
12. ✅ `test_usuario_puede_crear_tokens_sanctum`
13. ✅ `test_usuario_puede_tener_multiples_tokens`
14. ✅ `test_permisos_de_roles_inactivos_no_se_cuentan`
15. ✅ `test_email_debe_ser_unico`
16. ✅ `test_campos_fillable_permiten_asignacion_masiva`

**Métodos del Modelo Testeados**:

* `hasRole()`
* `hasPermission()`
* `getAllPermissions()`
* `getAuthPassword()`
* `empresa()` (relación)
* `cargo()` (relación)
* `roles()` (relación)
* `createToken()` (Sanctum)

***

## ⚙️ Configuración Necesaria

### 1. Base de Datos de Testing

El archivo `phpunit.xml` está configurado para usar MySQL:

```xml
<env name="DB_CONNECTION" value="mysql"/>
<env name="DB_DATABASE" value="api_db_testing"/>
```

**Crear la base de datos**:

```bash
# Opción 1: Con sudo (si root requiere auth)
sudo mysql -e "CREATE DATABASE IF NOT EXISTS api_db_testing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Opción 2: Con usuario regular
mysql -u tu_usuario -p -e "CREATE DATABASE IF NOT EXISTS api_db_testing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
```

### 2. Variables de Entorno

El archivo `.env` debe tener:

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=api_db
DB_USERNAME=tu_usuario
DB_PASSWORD=tu_password
```

***

## 🚀 Ejecutar Tests

### Comandos Principales

```bash
# Todos los tests
php artisan test

# Solo tests Feature
php artisan test --testsuite=Feature

# Solo tests Unit
php artisan test --testsuite=Unit

# Test específico
php artisan test --filter AuthTest

# Con cobertura (requiere Xdebug)
php artisan test --coverage

# Detener en el primer error
php artisan test --stop-on-failure

# Modo verbose
php artisan test -v
```

### Ejecutar Tests Individuales

```bash
# AuthTest
php artisan test tests/Feature/AuthTest.php

# ProductoTest
php artisan test tests/Feature/ProductoTest.php

# PermissionTest
php artisan test tests/Feature/PermissionTest.php

# RoleTest
php artisan test tests/Unit/RoleTest.php

# UsuarioTest
php artisan test tests/Unit/UsuarioTest.php
```

***

## 📊 Cobertura de Tests

### Por Módulo

| Módulo             | Tests  | Cobertura                               |
| ------------------ | ------ | --------------------------------------- |
| **Autenticación**  | 11     | Login, Logout, Tokens, Permisos         |
| **Productos CRUD** | 12     | Create, Read, Update, Delete, Search    |
| **RBAC Sistema**   | 17     | Roles, Permisos, Asignación, Middleware |
| **Modelo Rol**     | 10     | Relaciones, Métodos, Validaciones       |
| **Modelo Usuario** | 16     | Relaciones, RBAC, Sanctum, Validaciones |
| **TOTAL**          | **66** | **Cobertura Completa**                  |

### Funcionalidades Testeadas

✅ **Autenticación**:

* Login con credenciales válidas/inválidas
* Logout y destrucción de tokens
* Múltiples tokens por usuario
* Expiración de tokens
* Usuario activo/inactivo

✅ **CRUD Productos**:

* Listar con paginación
* Crear con validaciones
* Actualizar registros
* Soft delete
* Búsqueda FULLTEXT
* Filtros (activo, empresa)
* Multi-tenancy

✅ **Sistema RBAC**:

* Asignación de roles a usuarios
* Múltiples roles por usuario
* Herencia de permisos
* Roles activos/inactivos
* Middleware de permisos
* Gestión de permisos por módulo

✅ **Validaciones**:

* Campos requeridos
* Unicidad (email, código)
* Tipos de datos
* Relaciones FK

✅ **Seguridad**:

* Autenticación requerida
* Verificación de permisos
* Aislamiento por empresa (multi-tenancy)
* Password hashing

***

## 🔧 Troubleshooting

### Error: "could not find driver"

**Problema**: SQLite no está instalado.

**Solución**: Se configuró MySQL en `phpunit.xml`. Crear base de datos:

```bash
sudo mysql -e "CREATE DATABASE IF NOT EXISTS api_db_testing;"
```

### Error: "Access denied for user"

**Problema**: Credenciales incorrectas.

**Solución**: Verificar `.env` o usar `sudo mysql` si root requiere autenticación.

### Error: "Table not found"

**Problema**: Migraciones no ejecutadas en base de testing.

**Solución**: `RefreshDatabase` trait ejecuta migraciones automáticamente.

### Tests lentos

**Problema**: Base de datos MySQL es más lenta que SQLite.

**Solución Alternativa**: Instalar SQLite:

```bash
sudo apt-get install php-sqlite3
# Luego cambiar phpunit.xml a sqlite :memory:
```

***

## 📈 Próximos Pasos

### FASE 4 COMPLETADA ✅

**Logros**:

* ✅ 66 tests implementados
* ✅ Cobertura completa de Auth, CRUD, RBAC
* ✅ Tests unitarios de modelos
* ✅ Helpers reutilizables en TestCase

### FASE 5: Documentación Swagger/OpenAPI

**Tareas Pendientes**:

1. Instalar paquete L5-Swagger
2. Documentar todos los endpoints
3. Agregar ejemplos de request/response
4. Configurar autenticación Bearer
5. Generar documentación interactiva

***

## 📝 Notas Importantes

### Configuración de Testing

El trait `RefreshDatabase` se usa en `TestCase.php` para:

* Ejecutar migraciones antes de cada test
* Limpiar base de datos después de cada test
* Garantizar estado limpio en cada ejecución

### Helpers Disponibles

```php
// En cualquier test que extienda TestCase:

// Crear datos de prueba
$empresa = $this->createEmpresa();
$usuario = $this->createUsuario();
$admin = $this->createAdminUsuario();

// Autenticación
$token = $this->actingAsUsuario($usuario);
$response = $this->authenticatedJson('GET', '/api/productos', [], $usuario);

// Seeds
$this->seedRoles();
$this->seedPermisos();
$this->assignAllPermissionsToRole($rol);
```

### Buenas Prácticas Aplicadas

1. **Arrange-Act-Assert**: Todos los tests siguen este patrón
2. **Nombres descriptivos**: `test_usuario_puede_hacer_login_con_credenciales_validas`
3. **Tests aislados**: Cada test es independiente
4. **Factories implícitas**: Helpers en TestCase reemplazan factories
5. **Cobertura completa**: Happy path + edge cases + validaciones

***

## ✅ Checklist de Verificación

* [x] TestCase.php con helpers configurado
* [x] AuthTest.php (11 tests) creado
* [x] ProductoTest.php (12 tests) creado
* [x] PermissionTest.php (17 tests) creado
* [x] RoleTest.php (10 tests) creado
* [x] UsuarioTest.php (16 tests) creado
* [x] phpunit.xml configurado para MySQL
* [ ] Base de datos `api_db_testing` creada
* [ ] Tests ejecutados exitosamente
* [ ] Documentación de FASE 4 completada

***

## 🎯 Comandos Rápidos

```bash
# Setup inicial
sudo mysql -e "CREATE DATABASE IF NOT EXISTS api_db_testing;"

# Ejecutar todos los tests
php artisan test

# Verificar que todo funciona
php artisan test --stop-on-failure

# Ver detalles de tests que fallan
php artisan test -v
```

***

**FASE 4 COMPLETADA** 🎉

Total de tests implementados: **66 tests** Archivos creados: **6 archivos** Cobertura: **Autenticación, CRUD, RBAC, Modelos**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/docs/archive/fase_4_testing_completada.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.