Delphi E2E

Idioma de saida

Detecte o idioma da primeira mensagem. Padrao: pt-BR. Respeite overrides explicitos.

REGRA ZERO — plataforma e foco

1. Windows-only. Fora do Windows, recusar limpo e parar: pt-BR: "O /e2e depende da API user32.dll do Windows e nao funciona neste sistema." en-US: "/e2e relies on the Windows user32.dll API and does not work on this system." Nao sugerir adb nem caminho Android — esta explicitamente fora de escopo.
2. Nunca pedir foco. Proibido SetForegroundWindow, SetCursorPos, mouse_event e SendKeys. O harness usa PostMessage, WM_CHAR e PrintWindow. Roubar foco no meio da digitacao do usuario ja causou vazamento de texto para dentro do app.

Gate de seguranca — para e espera

Antes do PRIMEIRO clique, apresentar e aguardar confirmacao:

• os cenarios que pretende executar;
• quais gravam dados e o que gravam;
• em que modo vai rodar (primeiro plano / ao fundo);
• o unico pedido ao usuario: deixar a janela aberta, mesmo atras das outras — nao minimizar.

Regras invioláveis:

1. Nunca gravar por iniciativa propria — explorar, capturar, sair por Cancelar/Voltar/Esc.
2. Cenario que grava so roda se o usuario pediu e confirmou no gate. Senao: ⏭️ PULADO.
3. Capturar so a janela do app — PrintWindow garante isso por construcao.
4. Credenciais vem do projeto local; nunca ecoar senha em texto claro.
5. Declarar no relatorio: modo usado e estado final (app aberto/fechado, dados alterados/intactos).

Modo ao fundo. A flag --background do comando /e2e mapeia diretamente para Set-DelphiBackgroundMode -Enabled $true. Nao e uma chamada de setup unica: repetir em TODA invocacao PowerShell, junto do dot-source (ver "Carregar o harness") — cada invocacao e um processo novo e o estado do modo morre com o anterior. Default (flag ausente): primeiro plano — nao chamar Set-DelphiBackgroundMode, ou chama-la com -Enabled $false. Declarar no gate qual dos dois modos vai rodar.

Subir o app ja no fundo. Em modo ao fundo, mandar a janela para o fundo ao subir o app, nao so depois de cada clique:

$p = Start-Process -FilePath $exe -PassThru
$w = Wait-DelphiWindow -ProcessId $p.Id -TimeoutMs 10000  # espera a janela existir
Set-DelphiWindowBottom -ProcessId $p.Id                   # SO em modo ao fundo

Sem essa chamada a janela pula para a frente no Start-Process e fica la ate o primeiro clique — exatamente a interrupcao que a flag --background existe para evitar. Set-DelphiWindowBottom usa SWP_NOACTIVATE: manda ao fundo sem roubar foco.

Ciclo por cenario

Todo passo abaixo roda numa invocacao PowerShell que comeca pelo dot-source (ver "Carregar o harness") — sem ele, nenhuma dessas funcoes existe naquela invocacao.

1. Marcar o offset atual do log (Get-DelphiLogOffset) e a contagem de janelas (Get-DelphiFormWindowCount).
2. Reconduzir ao ponto de partida do cenario.
3. Executar os passos (Invoke-DelphiClick / Send-DelphiText / Send-DelphiKey).
4. Capturar (Get-DelphiShot) e conferir a captura antes de ler: Test-DelphiShotIsBlank -Path $png. Se der $true, nao ler — ver abaixo.
5. Ler a tela a partir do PNG.
6. Ler o delta do log (Get-DelphiLogDelta).
7. Reconferir Get-DelphiFormWindowCount e anotar se cresceu em relacao ao passo 1.
8. Emitir veredito.
9. Voltar ao estado base.

Captura preta nao e evidencia. Get-DelphiShot grava um PNG inteiramente preto quando a janela escolhida foi uma orfa invisivel — as armadilhas 2 e 3 documentadas em Get-DelphiWindow se manifestam exatamente assim, e o arquivo e gravado do mesmo jeito. Por isso toda captura passa por Test-DelphiShotIsBlank antes de ser lida. Ler um PNG preto leva a um dos dois piores desfechos possiveis: inventar o que estaria na tela, ou reportar ❌ FALHOU. A verdade e ⛔ BLOQUEADO — peguei a janela errada, nao sei se o app esta errado. Tratamento, nesta ordem: refazer a descoberta com Wait-DelphiWindow (o app pode estar minimizado ou ainda abrindo) e recapturar; persistindo, matar o processo e reabrir o .exe; persistindo ainda, ⛔ BLOQUEADO com a causa declarada.

Contagem de janelas FMT*. Get-DelphiFormWindowCount -ProcessId $ProcessId conta todas as janelas FMT* do processo — inclusive as invisiveis, que sao justamente as que denunciam form fechado e nao liberado. Medir no inicio e no fim de cada cenario; se a contagem sobe e nao volta ao longo da bateria, o relatorio traz o alerta de possivel vazamento de form. Isso nao altera o veredito do cenario: e um achado a parte.

Isolamento. Tentar reconduzir pela UI (Cancelar/Voltar/Esc), conferindo pelo screenshot. Apos 2 tentativas sem chegar, matar o processo e reabrir o .exe. Se nao conseguir reconduzir, o cenario sai ⛔ BLOQUEADO — nunca ❌ FALHOU. Relatorio que acusa bug onde so houve contaminacao de estado e pior que relatorio nenhum.

Entrega != efeito. Um PostMessage pode ser entregue e nao surtir efeito se o controle FMX nao estiver no estado esperado. Por isso o log e lido em paralelo: sem ele, "cliquei e nada aconteceu" vira ❌ FALHOU quando deveria ser ⛔ BLOQUEADO.

Ritmo. Dar tempo ao app recem-iniciado; clique cedo demais na primeira tela nao pega. A visibilidade da janela FMX pode levar mais de 3 segundos para estabilizar apos o start do processo. Por isso a primeira busca de janela depois do Start-Process usa Wait-DelphiWindow, nunca Get-DelphiWindow direto:

$w = Wait-DelphiWindow -ProcessId $ProcessId -TimeoutMs 10000

Wait-DelphiWindow faz o poll internamente e devolve o mesmo objeto de Get-DelphiWindow; esgotado o -TimeoutMs, lanca citando o ultimo erro real. Get-DelphiWindow lanca na primeira tentativa quando ainda nao ha FMT* visivel — e nao aceita timeout —, entao chama-la logo apos o start transforma "o app ainda esta abrindo" em falha de descoberta de janela. Depois que a janela apareceu, Get-DelphiWindow serve para o resto da bateria.

Fechar uma mensagem (MessageBox). Send-DelphiKey -ProcessId $ProcessId -WindowHandle $dlg.Handle -VirtualKey 13 (Enter) fecha o dialogo nativo #32770. -ProcessId e obrigatorio nesta funcao mesmo quando -WindowHandle ja aponta para o dialogo — nao omitir. E assim que se volta ao estado base depois de uma mensagem aparecer — sem isso, todo cenario seguinte comeca contaminado e sai ⛔ BLOQUEADO.

Verificar "apareceu mensagem?". Usar Get-DelphiDialog -ProcessId $ProcessId — se devolver nao-$null (guardado, por exemplo, em $dlg), ha um dialogo aberto; ler o texto capturando com Get-DelphiShot -ProcessId $ProcessId -Path $caminhoDoPng -WindowHandle $dlg.Handle. Nao usar heuristica indireta (ex.: "a janela principal ficou inerte, entao deve ter aberto uma mensagem") — Get-DelphiDialog e a fonte de verdade.

Vereditos

Fronteira com o build

Esta skill nao compila e nao ensina msbuild. Verificar se ha binario; se nao houver ou estiver mais velho que o fonte, carregar a skill delphi-build.

O que fica aqui: localizar o .exe (conferir DCC_ExeOutput no .dproj — costuma ser .\bin, nao Win32\Debug) e conferir os pre-requisitos ao lado dele: sk4d.dll, .ttf, .db, config.ini, fbclient.dll. E territorio de runtime, nao de build, e e o passo mais esquecido.

Descoberta de log

Ordem: (a) usuario informa; (b) config.ini do diretorio do .exe (Log/LogFile/LogPath); (c) *.log/*.txt no diretorio do .exe modificados apos o start; (d) nada.

Os passos (b) e (c) ja estao implementados em Find-DelphiLogFile — usar a funcao, nao reescrever a busca:

$log = Find-DelphiLogFile -ExeDir $dirDoExe -StartedAfter $inicioDoProcesso

Devolve o caminho do log ou nada (caso d). Refazer a busca a mao com Get-ChildItem cai direto numa pegadinha ja corrigida dentro da funcao: -Include so filtra de fato quando -Path termina em \*; sem isso ele e silenciosamente ignorado e a busca nao devolve nada. Cabe a skill apenas o passo (a): se o usuario informou o caminho, usar o dele e nem chamar a funcao.

No caso (d): oferecer instrumentacao — os dois caminhos disponiveis estao documentados em references/logging-unit.md (unit de log minima para o app gravar eventos) e references/selftest-mode.md (modo self-test do proprio app). Se a oferta for recusada, degradar para veredito visual — declarando isso no relatorio, nunca em silencio.

Por que delta por byte offset, e nao reler o log inteiro

Get-DelphiLogDelta le a partir de um offset (Get-DelphiLogOffset marcado no inicio do cenario) em vez de reler o arquivo inteiro a cada cenario. Motivo: custo, nao falha de leitura. Uma bateria com dezenas de cenarios geraria um log que so cresce; reler tudo a cada cenario e comparar por substring seria inviavel (custo cresce quadratico com o numero de cenarios, e o ruido de eventos antigos polui a correlacao). O FileShare.ReadWrite usado na abertura do arquivo e defesa contra locks mais restritivos que o app possa aplicar no log (ex.: fmShareExclusive) — nao contorna uma falha de leitura do Get-Content, que sob fmShareDenyWrite (o modo mais comum de log aberto para escrita) ja le normalmente no PowerShell 5.1.

Carregar o harness

O diretorio do plugin e cache sobrescrito a cada atualizacao, e rodar .ps1 de la esbarra em ExecutionPolicy. Portanto: ler references/gui.ps1 e escrever em %TEMP%, carregando de la. Materializar o arquivo uma vez, no inicio:

$dst = Join-Path $env:TEMP 'delphi-e2e-gui.ps1'
Set-Content -Path $dst -Value $conteudoDoReferences -Encoding UTF8

TODA invocacao PowerShell recomeca do dot-source

Cada invocacao da ferramenta PowerShell e um processo novo, com uma sessao nova. Nada sobrevive de uma para a seguinte: as funcoes dot-sourcidas somem, e — pior, porque falha em silencio — $script:DelphiKeepBottom volta a $false, o que torna o modo ao fundo inerte em toda interacao depois da chamada que o ligou. Nao existe "chamada de setup" que valha para as seguintes.

Portanto toda invocacao PowerShell do /e2e comeca assim:

. "$env:TEMP\delphi-e2e-gui.ps1"
Initialize-DelphiGui
Set-DelphiBackgroundMode -Enabled $true   # SO em modo ao fundo — repetir aqui, toda vez
# ... e so entao os comandos do passo (Invoke-DelphiClick, Get-DelphiShot, ...)

Nao "otimizar" removendo o dot-source das chamadas seguintes por parecer repeticao inutil: sem ele, a invocacao seguinte nao conhece funcao nenhuma do harness. E omitir o Set-DelphiBackgroundMode num passo faz aquele passo rodar em primeiro plano — a janela sobe na frente do usuario no meio da bateria, sem nenhum aviso.