Testes e integração contínua

Frameworks robustos para desktop exigem testes extremamente confiáveis. O Wails v3 emprega uma estratégia em camadas:

Este documento explica onde ficam os testes, como executá-los e o que o Taskfile orquestra.

As orientações sobre condições de corrida mencionadas em versões anteriores como pkg/application/RACE.md

estão atualmente em v3/TESTING.md.

1. Convenções de diretórios

v3/
├── internal/.../_test.go     # Unit tests for internal packages
├── pkg/.../_test.go          # Public API tests
├── tasks/events/generate.go  # Code generator for event constants (NOT a test harness)
├── tests/                    # Top-level integration test harness
└── TESTING.md                # Race / Cgo testing guidance

Diretrizes:

• Mantenha os testes unitários junto ao código (foo.go ↔ foo_test.go).
• Use o estilo de caixa-preta para pacotes pkg/ (package application_test) quando isso melhorar a organização da API.
• Os fixtures compartilhados ficam onde são usados (não há um pacote internal/testutil/ central nesta árvore — em vez disso, conecte os helpers em cada pacote).

2. Testes unitários

Como escrever testes

func TestEventConstants(t *testing.T) {
    assert.NotEmpty(t, events.Common.WindowFocus)
}

Recomendações:

• Use stretchr/testify — já incluído em go.mod.
• Prefira testes orientados por tabela sempre que várias entradas, casos extremos ou resultados esperados exercitarem o mesmo comportamento. Dê um nome descritivo a cada caso.
• Quando necessário, use stubs para substituir comportamentos específicos de plataforma, condicionando-os a tags de compilação (foo_windows_test.go, foo_darwin_test.go, …).

Cobertura esperada

Espera-se que a lógica nova e alterada tenha 100% de cobertura de instruções Go. Meça o pacote que você alterou em vez de depender de uma porcentagem para todo o repositório:

go test ./pkg/application -coverprofile=coverage.out
go tool cover -func=coverage.out

Alguns caminhos não podem ser testados de maneira razoável em um ambiente de testes normal — por exemplo, falhas exclusivas de determinada plataforma, comportamentos dependentes de hardware ou um fallback defensivo que não possa ser induzido com segurança. Mantenha essas exceções restritas e explique cada caminho não coberto na descrição do PR.

Execução local

cd v3
go test ./... -cover

Ou por meio do Taskfile (alvos reais — não há um atalho task test):

task test:cli            # CLI plumbing tests
task test:generator      # bindings generator round-trip tests
task test:templates      # build every shipped template
task test:infrastructure # supporting helpers
task test:examples       # exercise the example matrix (downloads as needed)
task test:all            # everything above
task sanity              # quick smoke check (also: sanity:gtk4)
task precommit           # what you should run before pushing

3. Testes de integração

v3/tests/ hospeda a infraestrutura de integração entre pacotes. Os alvos test:example:* e test:examples:* do Taskfile executam verificações de compilação e inicialização em darwin / windows / linux (incluindo matrizes GTK3 / GTK4 baseadas em Docker no Linux).

Os exemplos executáveis ficam em v3/examples/. Os alvos de teste selecionam e compilam

os exemplos adequados à plataforma host ou à matriz de CI.

Execute a suíte de testes de fumaça da plataforma host com:

task test:examples       # host
task test:examples:all   # full matrix (slow)

4. Detecção de condições de corrida

Condições de corrida de dados são fatais em runtimes de GUI.

Guia sobre condições de corrida

Consulte v3/TESTING.md para saber sobre:

• Condições de corrida benignas conhecidas e justificativa para suprimi-las
• Como interpretar rastreamentos de pilha que atravessam limites do Cgo (GTK no Linux + WebKit2GTK)

Suíte local de detecção de condições de corrida

go test -race ./...

wails3 dev não tem a opção -race — suas opções de CLI são --config, --port,

e -s (habilita HTTPS). Para exercitar o runtime com o detector de condições de corrida,

compile um aplicativo de teste com go build -race e execute-o diretamente.

5. Fluxos de trabalho do GitHub Actions

Arquivos reais de fluxo de trabalho em .github/workflows/ (verificados em relação à árvore):

Não há nenhum qodana.yaml nem nenhum runtime.yml nesta árvore — versões anteriores desta página mencionavam ambos, mas somente semgrep.yml abrange a análise estática, e o pacote JS do runtime é publicado por meio de publish-npm.yml.

As etapas de CI correspondem aos alvos do Taskfile acima (task test:cli, task test:generator, task test:templates, task test:examples, …), portanto você pode reproduzir localmente cada etapa da CI. A etapa de smoke test wails3 build em build-and-test-v3.yml é invocada sem flags adicionais — não existe a flag -skip-package em wails3 build.

6. Paridade entre verificações locais e CI

Não há um único alvo geral task ci. Reproduza a CI encadeando os alvos reais:

task precommit
task test:cli
task test:generator
task test:templates
task test:examples

7. Solução de problemas em testes com falha

8. Adição de novos testes

1. Unitário — crie *_test.go e execute go test ./...
2. Gerador / CLI — amplie os casos em internal/generator/testcases/ ou internal/commands/*_test.go e execute novamente task test:generator / task test:cli
3. Templates / exemplos — certifique-se de que os templates distribuídos ainda sejam compilados com task test:templates

9. Mapa dos principais arquivos

A qualidade não é deixada para depois no Wails v3. Com testes unitários, suítes de geradores e templates, detecção de condições de corrida e uma matriz de CI multiplataforma, você pode contribuir com confiança, sabendo que suas alterações passam em todos os sistemas operacionais compatíveis. Bons testes!