テストと継続的インテグレーション

堅牢なデスクトップフレームワークには、確実なテストが不可欠です。 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）。
• API の健全性が向上する場合は、pkg/パッケージ（package application_test）にブラックボックス形式を使用します。
• 共有フィクスチャは、それを使用する場所に配置します（この作業ツリーには一元管理されたinternal/testutil/パッケージがないため、代わりにパッケージごとにヘルパーを組み込みます）。

2. 単体テスト

テストの記述

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

推奨事項：

• go.modにすでに含まれているstretchr/testifyを使用します。
• 複数の入力、エッジケース、または期待される結果で同じ動作を検証する場合は、可能な限りテーブル駆動テストを使用します。各ケースには、その内容が分かる名前を付けてください。
• 必要に応じて、プラットフォーム固有の差異をビルドタグ（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 の各環境でビルドおよび起動チェックを実行します（Linux では Docker ベースの GTK3 / GTK4 マトリックスを含みます）。

実行可能なサンプルはv3/examples/にあります。テストターゲットは、

ホストプラットフォームまたは CI マトリックスに適したサンプルを選択してビルドします。

ホストプラットフォーム用のスモークテストスイートは、次のコマンドで実行します。

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

4. 競合検出

GUI ランタイムにおいて、データ競合は致命的です。

競合ガイド

次の内容については、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 をローカルで一対一に再現できます。build-and-test-v3.yml のスモーク wails3 build ステップは、追加のフラグなしで呼び出されます。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 マトリックスがあるため、変更がサポート対象のすべての OS で正常に動作することを確認しながら、安心してコントリビュートできます。テストを楽しんでください！