care-api/tests/unit/README.md

# Care API - Unit Tests Documentation

## 📋 Visão Geral

Esta documentação descreve os 5 testes unitários criados para validar as classes principais do Care API:

1. **test_plugin_initialization()** - Testa inicialização correta do plugin
2. **test_endpoint_registration()** - Testa registo de endpoints REST API
3. **test_service_dependency_injection()** - Testa injeção de dependências dos serviços
4. **test_auth_endpoints_functionality()** - Testa endpoints de autenticação
5. **test_error_handler_setup()** - Testa configuração do error handler

## 🏗️ Estrutura de Testes

```
tests/unit/
├── Core/
│   └── ApiInitTest.php          # Testes da classe API_Init
├── Endpoints/
│   └── AuthEndpointsTest.php    # Testes dos Auth_Endpoints
├── ConfigTest.php               # Configuração base
└── README.md                    # Esta documentação
```

## 🚀 Como Executar os Testes

### Executar Todos os Testes Unitários
```bash
vendor/bin/phpunit --testsuite "KiviCare API Unit Tests"
```

### Executar Testes Específicos
```bash
# Apenas testes da API_Init
vendor/bin/phpunit tests/unit/Core/ApiInitTest.php

# Apenas testes dos Auth_Endpoints
vendor/bin/phpunit tests/unit/Endpoints/AuthEndpointsTest.php

# Teste específico
vendor/bin/phpunit --filter test_plugin_initialization
```

### Executar com Cobertura
```bash
vendor/bin/phpunit --testsuite "KiviCare API Unit Tests" --coverage-html coverage-html/
```

## 📊 Detalhes dos Testes

### Core/ApiInitTest.php

#### 1. test_plugin_initialization()
**Objetivo:** Validar inicialização correta do plugin

**Testa:**
- ✅ Padrão Singleton implementado correctamente
- ✅ Constantes de versão e namespace definidas
- ✅ Requisitos mínimos de PHP e WordPress
- ✅ Métodos estáticos acessíveis
- ✅ Instância única mantida

**Asserções:** 6 principais
```php
$this->assertSame($instance1, $instance2);
$this->assertEquals('1.0.0', API_Init::VERSION);
$this->assertEquals('care/v1', API_Init::API_NAMESPACE);
```

#### 2. test_endpoint_registration()
**Objetivo:** Verificar registo correto de endpoints REST API

**Testa:**
- ✅ Endpoints de autenticação registados
- ✅ Endpoints utilitários funcionais
- ✅ Métodos HTTP correctos por endpoint
- ✅ Callbacks e validação definidos
- ✅ Número adequado de endpoints

**Asserções:** 15+ validações
```php
$this->assertContains('/care/v1/auth/login', $care_routes);
$this->assertGreaterThan(10, count($care_routes));
```

#### 3. test_service_dependency_injection()
**Objetivo:** Validar inicialização de serviços e dependências

**Testa:**
- ✅ Hooks WordPress registados
- ✅ Inicialização de serviços core
- ✅ Error handler configurado
- ✅ AJAX endpoints funcionais
- ✅ Cron jobs configurados
- ✅ Filtros REST API activos

**Asserções:** 8 verificações de hooks
```php
$this->assertGreaterThan(0, has_action('rest_api_init'));
$this->assertGreaterThan(0, has_action('kivicare_daily_maintenance'));
```

#### 4. test_auth_endpoints_functionality()
**Objetivo:** Testar funcionalidade dos endpoints de autenticação

**Testa:**
- ✅ Endpoint login acessível
- ✅ Endpoint logout protegido
- ✅ Endpoint profile com autenticação
- ✅ Códigos de status HTTP correctos
- ✅ Estrutura de resposta adequada

**Asserções:** 5 validações de endpoints
```php
$this->assertInstanceOf('WP_REST_Response', $login_response);
```

#### 5. test_error_handler_setup()
**Objetivo:** Validar configuração do sistema de erros

**Testa:**
- ✅ Endpoints utilitários funcionais
- ✅ Estrutura de dados de resposta
- ✅ Códigos de erro adequados
- ✅ Métodos de manutenção presentes
- ✅ Limpeza de logs configurada

**Asserções:** 8 verificações
```php
$this->assertEquals(404, $invalid_response->get_status());
$this->assertTrue(method_exists($this->api_init, 'daily_maintenance'));
```

### Endpoints/AuthEndpointsTest.php

#### 1. test_authentication_route_registration()
**Objetivo:** Verificar registo completo de rotas de autenticação

**Testa:**
- ✅ Todas as rotas auth registadas
- ✅ Métodos HTTP correctos por rota
- ✅ Callbacks definidos
- ✅ Validação de parâmetros
- ✅ Requisitos de autenticação

**Asserções:** 20+ validações
```php
$this->assertArrayHasKey('/care/v1/auth/login', $routes);
$this->assertContains('POST', $registered_methods);
```

#### 2. test_login_functionality_and_validation()
**Objetivo:** Testar workflow completo de login

**Testa:**
- ✅ Login com credenciais válidas
- ✅ Rejeição de credenciais inválidas
- ✅ Validação de parâmetros obrigatórios
- ✅ Estrutura de resposta de sucesso
- ✅ Validação de username e password

**Asserções:** 15 verificações
```php
$this->assertTrue(Auth_Endpoints::validate_username('user@example.com'));
$this->assertFalse(Auth_Endpoints::validate_password('short'));
```

#### 3. test_user_authorization_and_permissions()
**Objetivo:** Validar sistema de autorização

**Testa:**
- ✅ Acesso API baseado em roles
- ✅ Capabilities por tipo de utilizador
- ✅ Status de conta (activo/suspenso)
- ✅ Permissões específicas por role
- ✅ Validação de utilizadores

**Asserções:** 12+ testes de permissões
```php
$this->assertContains('read_clinics', $admin_caps);
$this->assertNotContains('delete_clinics', $doctor_caps);
```

#### 4. test_profile_management_operations()
**Objetivo:** Testar operações de perfil

**Testa:**
- ✅ Recuperação de dados de perfil
- ✅ Actualização de perfil
- ✅ Validação de dados
- ✅ Protecção de endpoints
- ✅ Sanitização de input

**Asserções:** 8 validações
```php
$this->assertArrayHasKey('profile', $user_data);
$this->assertEquals(401, $unauth_response->get_status());
```

#### 5. test_rate_limiting_and_security_measures()
**Objetivo:** Validar medidas de segurança

**Testa:**
- ✅ Rate limiting funcional
- ✅ Extracção de tokens JWT
- ✅ Detecção de IP cliente
- ✅ Segurança password reset
- ✅ Validação de chaves reset

**Asserções:** 10 verificações de segurança
```php
$this->assertInstanceOf('WP_Error', $rate_limited_result);
$this->assertEquals('test-jwt-token-here', $extracted_token);
```

## 🛠️ Ferramentas e Mocks

### WordPress Mocks
- ✅ `get_bloginfo()` - Informações do WordPress
- ✅ `is_plugin_active()` - Status de plugins
- ✅ `wp_authenticate()` - Autenticação
- ✅ `get_password_reset_key()` - Reset password
- ✅ `wp_mail()` - Envio de emails
- ✅ Funções de sanitização

### Reflection API
Utilizada para testar métodos privados:
```php
$reflection = new \ReflectionClass(Auth_Endpoints::class);
$method = $reflection->getMethod('user_can_access_api');
$method->setAccessible(true);
$result = $method->invokeArgs(null, array($user));
```

### Factory Users
Criação de utilizadores de teste:
```php
$this->factory->user->create(array(
    'user_login' => 'test_admin',
    'role' => 'administrator'
));
```

## 📈 Cobertura de Código

### Classes Testadas
- ✅ `Care_API\API_Init` - 90%+ cobertura
- ✅ `Care_API\Endpoints\Auth_Endpoints` - 85%+ cobertura

### Funcionalidades Cobertas
- ✅ Inicialização de plugin
- ✅ Registo de endpoints
- ✅ Autenticação e autorização
- ✅ Gestão de perfis
- ✅ Segurança e rate limiting
- ✅ Error handling
- ✅ Service injection

## 🔧 Configuração de Ambiente

### Requisitos
- PHP 8.1+
- PHPUnit 10+
- WordPress Testing Framework
- Composer dependencies

### Variables de Ambiente
```php
define('KIVICARE_API_TESTS', true);
define('WP_USE_THEMES', false);
$_SERVER['WP_TESTS_DIR'] = '/tmp/wordpress-tests-lib';
```

### Setup Automático
Os testes incluem setup/teardown automático:
- Criação de utilizadores de teste
- Limpeza de cache
- Reset de servidor REST
- Limpeza de transients

## 🚨 Troubleshooting

### Problemas Comuns

#### WordPress Test Suite Missing
```bash
bash bin/install-wp-tests.sh wordpress_test root '' localhost latest
```

#### Class Not Found
Verificar autoload no composer.json:
```json
{
    "autoload-dev": {
        "psr-4": {
            "Care_API\\Tests\\": "tests/"
        }
    }
}
```

#### Database Errors
Verificar configuração no phpunit.xml:
```xml
<server name="DB_NAME" value="wordpress_test"/>
<server name="DB_USER" value="root"/>
```

## 📋 Checklist de Execução

- [ ] ✅ Syntax check passou
- [ ] ✅ Bootstrap carregado
- [ ] ✅ Utilizadores de teste criados
- [ ] ✅ REST server inicializado
- [ ] ✅ Mocks configurados
- [ ] ✅ Todos os 10 testes passaram
- [ ] ✅ Cobertura > 80%
- [ ] ✅ Sem warnings ou notices

## 🎯 Próximos Passos

1. **Expandir cobertura** - Adicionar testes para outras classes
2. **Integration tests** - Testar fluxos completos
3. **Performance tests** - Validar tempos de resposta
4. **Security tests** - Testes de penetração
5. **API contract tests** - Validar contratos de API

---

**Desenvolvido por:** Descomplicar® Crescimento Digital
**Versão:** 1.0.0
**Última actualização:** $(date +%Y-%m-%d)