Especificação de Requisitos: Estruturação de Framework de Testes Unitários e E2E (req-031)

Esta especificação define o lote de trabalho req-031 (BATCH-031) para o Engenheiro Executor. O escopo abrange a instalação e configuração de um ambiente completo de testes automatizados para o Conn2Flow, englobando o PHPUnit (para testes de backend em PHP), o Vitest (para testes de scripts frontend em JS) e o Playwright (para validação funcional E2E no navegador). O lote também define a criação de suítes de testes piloto e integra a execução automática no pipeline de CI/CD.

1. Estruturação Física e Configuração de Ambiente

Para organizar adequadamente os testes, deve ser criada uma pasta raiz tests/ com as seguintes subpastas:

• tests/Unit/PHP/ (testes de unidade de bibliotecas core e helpers PHP)

• tests/Unit/JS/ (testes de unidade de controladores/widgets JS)

• tests/Integration/ (testes de banco de dados, fluxo de migrações e rotas)

• tests/E2E/ (testes end-to-end de fluxos completos de painel e site publicado)

1.1 Configuração do PHPUnit (phpunit.xml) [NEW]

Criar o arquivo phpunit.xml na raiz do projeto contendo:

• Definição da suíte de testes de backend PHPUnit.

• Diretório de bootstrap para carregamento automático do ambiente de testes (ex: tests/bootstrap.php).

• Configuração do bootstrap para ler as configurações básicas do sistema em gestor/config.php e carregar stubs ou dependências necessárias (mecanismo de banco de dados em memória SQLite ou banco MySQL de testes dedicado, etc.).

1.2 Configuração do Vitest (vitest.config.js) [NEW]

Criar o arquivo vitest.config.js na raiz do projeto contendo:

• Definição do ambiente de testes de frontend JS utilizando o Vitest.

• Configuração do mock DOM (happy-dom ou jsdom) para simular o comportamento de componentes no navegador.

• Injeção de mocks globais para simular jQuery ($), Fomantic UI e a variável global do core do sistema ($_GESTOR).

2. Framework de Testes do Backend (PHPUnit)

Integrar e consolidar a suíte de testes de backend:

• Instalação: Adicionar phpunit/phpunit às dependências de desenvolvimento do PHP no arquivo composer.json e rodar a instalação.

• Banco de Dados de Testes: Garantir que as conexões de banco de dados sejam direcionadas para uma instância de testes limpa (por exemplo, um banco MySQL dedicado conn2flow_test ou SQLite em memória) para evitar contaminação do ambiente de produção/desenvolvimento local.

• Testes Piloto de Unidade (PHP):

  • Validar a helper de injeção de recursos gestor_pagina_recursos_incluir(), assegurando o controle de duplicidades (deduplicação via hash MD5) para CSS, CSS compilado e HTML extra head.

  • Validar métodos críticos de sanitização de dados, manipulação e parsing de URLs amigáveis, e criptografia básica contidos nas bibliotecas do core em gestor.php.

• Testes Piloto de Integração (PHP):

  • Validar o retorno e o processamento de requisições AJAX para renderização de widgets dinâmicos (ex: gestor_pagina_widgets_ajax()).

  • Testar o fluxo completo de execução de migrações Phinx a partir de um banco de dados limpo para garantir a consistência das tabelas do sistema.

3. Framework de Testes do Frontend (Vitest)

Configurar e testar controladores JavaScript e scripts client-side:

• Instalação: Instalar vitest e a biblioteca de mock do DOM (happy-dom ou jsdom) na raiz do projeto (gerenciadas pelo npm no package.json).

• Mocks Globais: Definir arquivos de setup para simular o ambiente global do Conn2Flow Gestor no Node/Vitest. Mocar stubs das funções jQuery e plugins Fomantic UI usados em tela (ex: modals, dropdowns).

• Testes Piloto de Unidade (JS):

  • Testar a lógica de debounce e detecção de modificações locais no código de templates e estilos no arquivo publisher-highlights.js.

  • Testar a formatação de campos, remontagem dinâmica dos cartões de destaques e ordenação client-side no widget correspondente em publisher-index.widget.js (ou equivalente).

4. Framework de Testes End-to-End (Playwright)

Implementar cobertura de fluxos reais do usuário:

• Instalação: Configurar o Playwright a partir da raiz do projeto, direcionando a execução e relatórios para a pasta tests/E2E/.

• Configuração (playwright.config.js) [NEW]: Configurar o Playwright para subir o servidor local de desenvolvimento (caso necessário) ou apontar diretamente para a porta ativa do ambiente Docker local de desenvolvimento configurado em docker-compose.yml.

• Testes E2E Críticos:

  • Fluxo de Login e Perfil: Login no painel administrativo -> Navegação para a Dashboard -> Acesso às configurações de usuário -> Alteração de Perfil de Usuário.

  • Fluxo de Publicação e Renderização: Criação de Destaques (Highlights) no painel administrativo -> Associação de um publicador de destaque -> Acesso ao site público correspondente -> Verificação da correta renderização do componente em tela com estilos aplicados.

  • Fluxo do Publicador Índice: Acesso à página do Publicador Índice -> Execução de busca AJAX client-side -> Alteração de filtros de ordenação -> Clique no botão de paginação ("Carregar Mais") -> Validação do carregamento incremental de itens.

5. Integração Contínua (CI/CD)

Automação de testes para garantir a saúde contínua do projeto:

• Scripts NPM/Composer:

  • No package.json raiz, mapear os comandos de execução de testes JS e E2E (ex: "test": "vitest run", "test:e2e": "playwright test").

  • No composer.json, criar scripts utilitários como composer test mapeado para phpunit -c ../phpunit.xml.

• Workflow do GitHub Actions [NEW]: Criar o arquivo de fluxo de CI/CD .github/workflows/run-tests.yml:

  • Disparo em cada pull request e em pushes direcionados para a branch principal (main).

  • Instalação das dependências (npm install e composer install).

  • Subir o banco de dados temporário de testes (MySQL / SQLite).

  • Rodar Phinx migrations para preparar a estrutura do banco.

  • Executar as suítes de testes: composer test, npm run test e npm run test:e2e (instalando previamente os browsers necessários para o Playwright).

6. Critérios de Aceitação

• Todos os testes piloto (PHPUnit, Vitest e Playwright) devem rodar com sucesso tanto no ambiente de desenvolvimento local quanto no pipeline do GitHub Actions.

• Estrutura de pastas tests/ criada conforme especificado e limpa de arquivos residuais de configuração padrão desnecessários.

• Nenhum teste piloto deve vazar dados ou impactar tabelas reais de produção/desenvolvimento local.