Тестирование и непрерывная интеграция

Надёжным фреймворкам для настольных приложений требуется безотказное тестирование. В Wails v3 применяется многоуровневая стратегия:

В этом документе объясняется, где находятся тесты, как их запускать и какими операциями управляет Taskfile.

Руководство по гонкам данных, на которое в более ранних черновиках ссылались как на pkg/application/RACE.md,

сейчас находится в v3/TESTING.md.

1. Соглашения о структуре каталогов

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

Рекомендации:

• Размещайте модульные тесты рядом с кодом (foo.go ↔ foo_test.go).
• Для пакетов pkg/ используйте тестирование по принципу чёрного ящика (package application_test), если это помогает поддерживать чистоту API.
• Общие фикстуры размещайте там, где они используются (в этом рабочем дереве нет централизованного пакета internal/testutil/ — вместо этого подключайте вспомогательные средства отдельно для каждого пакета).

2. Модульные тесты

Написание тестов

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

Рекомендации:

• Используйте stretchr/testify — он уже есть в go.mod.
• Отдавайте предпочтение табличным тестам, когда несколько входных данных, граничных случаев или ожидаемых результатов проверяют одно и то же поведение. Дайте каждому случаю описательное имя.
• При необходимости подменяйте платформозависимое поведение заглушками с помощью тегов сборки (foo_windows_test.go, foo_darwin_test.go, …).

Требования к покрытию

Для новой и изменённой логики ожидается покрытие операторов Go на уровне 100%. Измеряйте покрытие изменённого пакета, а не полагайтесь на процент покрытия всего репозитория:

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

Некоторые пути выполнения практически не поддаются тестированию в обычной тестовой среде — например, сбои, возникающие только на определённой платформе, поведение, зависящее от оборудования, или защитный резервный путь, который нельзя безопасно активировать. Сводите такие исключения к минимуму и описывайте каждый непокрытый путь в описании PR.

Локальный запуск

cd v3
go test ./... -cover

Также можно использовать Taskfile (указывайте реальные цели — сокращения 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. Интеграционные тесты

В v3/tests/ размещена инфраструктура межпакетных интеграционных тестов. Цели Taskfile test:example:* и test:examples:* запускают проверки сборки и запуска в darwin / windows / linux (включая матрицы GTK3 / GTK4 на базе Docker в Linux).

Готовые к запуску примеры находятся в v3/examples/. Цели тестирования выбирают и собирают

примеры, соответствующие платформе хоста или матрице CI.

Чтобы запустить набор дымовых тестов для платформы хоста, выполните:

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

4. Обнаружение гонок данных

Гонки данных приводят к фатальным сбоям в средах выполнения графического интерфейса.

Руководство по гонкам данных

В v3/TESTING.md описаны:

• Известные безопасные гонки данных и обоснование их подавления
• Порядок интерпретации трассировок стека, пересекающих границы Cgo (Linux GTK + WebKit2GTK)

Локальный набор тестов на гонки данных

go test -race ./...

У wails3 dev нет флага -race — поддерживаются следующие флаги CLI: --config, --port

и -s (включает HTTPS). Чтобы проверить среду выполнения с помощью детектора гонок данных,

соберите тестовое приложение с go build -race и запустите его напрямую.

5. Рабочие процессы GitHub Actions

Фактические файлы рабочих процессов в .github/workflows/ (сверено с рабочим деревом):

В этом рабочем дереве нет qodana.yaml и нет runtime.yml — в более ранних черновиках этой страницы упоминались оба, однако статический анализ выполняет только semgrep.yml, а пакет среды выполнения JS публикуется через publish-npm.yml.

Шаги CI соответствуют указанным выше целям Taskfile (task test:cli, task test:generator, task test:templates, task test:examples, …), поэтому вы можете в точности воспроизвести CI локально. Шаг быстрой проверки wails3 build в build-and-test-v3.yml вызывается без дополнительных флагов — у wails3 build нет флага -skip-package.

6. Локальное воспроизведение CI

Единой общей цели task ci нет. Чтобы воспроизвести CI, последовательно запустите реальные цели:

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

7. Устранение неполадок при сбоях тестов

8. Добавление новых тестов

1. Модульные тесты — создайте *_test.go и запустите go test ./...
2. Генератор / CLI — дополните тестовые случаи в internal/generator/testcases/ или internal/commands/*_test.go и повторно запустите task test:generator / task test:cli
3. Шаблоны / примеры — убедитесь, что поставляемые шаблоны по-прежнему собираются с помощью task test:templates

9. Карта ключевых файлов

В Wails v3 качество — не второстепенная задача. Благодаря модульным тестам, наборам тестов генератора и шаблонов, обнаружению состояний гонки и кроссплатформенной матрице CI вы можете уверенно вносить изменения, зная, что они успешно проходят проверку во всех поддерживаемых нами ОС. Успешного тестирования!