ContextQMD
Back to Wails

Cross-Platform Testing Guide for Wails v3

v3/TESTING.md

2.13.015.5 KB
Original Source

Cross-Platform Testing Guide for Wails v3

This document describes the comprehensive cross-platform testing system for Wails v3 examples, supporting Mac, Linux, and Windows compilation.

Overview

The testing system ensures all Wails v3 examples build successfully across all supported platforms:

  • macOS (Darwin) - Native compilation
  • Windows - Cross-compilation from any platform
  • Linux - Multi-architecture Docker compilation (ARM64 + x86_64)

Test Directory Structure

The testing infrastructure is organized in a dedicated test directory:

bash
v3/
ā”œā”€ā”€ test/
ā”‚   ā””ā”€ā”€ docker/
ā”‚       ā”œā”€ā”€ Dockerfile.linux-arm64    # ARM64 native compilation
ā”‚       ā””ā”€ā”€ Dockerfile.linux-x86_64   # x86_64 native compilation
ā”œā”€ā”€ Taskfile.yaml                     # Build task definitions
ā””ā”€ā”€ TESTING.md                        # This documentation

Benefits of the organized structure:

  • Separation of Concerns: Testing files are isolated from application code
  • Clear Organization: All Docker-related files in one location
  • Easier Maintenance: Centralized testing infrastructure
  • Better Git Management: Clean separation for .gitignore patterns

Available Commands

šŸš€ Complete Cross-Platform Testing

bash
# Build all examples for ALL platforms (macOS + Windows + Linux)
task test:examples:all

Total: 129 builds (43 examples Ɨ 3 platforms) + CLI code testing

All Examples (No DIR Parameter Needed)

bash
# Current platform only (all 43 examples + CLI code)
task test:examples

# All examples for specific Linux architectures
task test:examples:linux:docker           # Auto-detect architecture
task test:examples:linux:docker:arm64     # ARM64 native
task test:examples:linux:docker:x86_64    # x86_64 native

# CLI code testing only
task test:cli

Single Example Builds (Requires DIR=example)

bash
# macOS/Darwin single example
task test:example:darwin DIR=badge

# Windows cross-compilation single example
task test:example:windows DIR=badge

# Linux native builds (on Linux systems)
task test:example:linux DIR=badge

# Linux Docker builds (multi-architecture)
task test:example:linux:docker DIR=badge          # Auto-detect architecture
task test:example:linux:docker:arm64 DIR=badge    # ARM64 native
task test:example:linux:docker:x86_64 DIR=badge   # x86_64 native

Build Artifacts

All builds generate platform-specific binaries with clear naming:

  • macOS: testbuild-{example}-darwin
  • Windows: testbuild-{example}-windows.exe
  • Linux: testbuild-{example}-linux
  • Linux ARM64: testbuild-{example}-linux-arm64 (Docker)
  • Linux x86_64: testbuild-{example}-linux-x86_64 (Docker)

Example outputs:

text
examples/badge/testbuild-badge-darwin
examples/badge/testbuild-badge-windows.exe
examples/badge/testbuild-badge-linux-arm64
examples/badge/testbuild-badge-linux-x86_64

Validation Status

āœ… Production Ready (v3.0.0-alpha)

  • Total Examples: 43 examples fully tested
  • macOS: āœ… All examples compile successfully (100%)
  • Windows: āœ… All examples cross-compile successfully (100%)
  • Linux: āœ… Multi-architecture Docker compilation (ARM64 + x86_64)
  • Build System: Comprehensive Taskfile.yaml integration
  • Git Integration: Complete .gitignore patterns for build artifacts
  • Total Build Capacity: 129 cross-platform builds per test cycle

Supported Examples

The system builds all 43 Wails v3 examples:

  • badge, badge-custom, binding, build
  • cancel-async, cancel-chaining, clipboard, contextmenus
  • dev, dialogs, dialogs-basic, drag-n-drop
  • environment, events, events-bug, file-association
  • frameless, gin-example, gin-routing, gin-service
  • hide-window, html-dnd-api, ignore-mouse, keybindings
  • menu, notifications, panic-handling, plain
  • raw-message, screen, services, show-macos-toolbar
  • single-instance, systray-basic, systray-custom, systray-menu
  • video, window, window-api, window-call
  • window-menu, wml

Recently Added (v3.0.0-alpha):

  • dev, events-bug, gin-example, gin-routing, gin-service
  • html-dnd-api, notifications

Platform Requirements

macOS (Darwin)

  • Go 1.23+
  • Xcode Command Line Tools
  • No additional dependencies required

Environment Variables:

bash
CGO_LDFLAGS="-framework UniformTypeIdentifiers -mmacosx-version-min=10.13"
CGO_CFLAGS="-mmacosx-version-min=10.13"

Windows (Cross-compilation)

  • Go 1.23+
  • No additional dependencies for cross-compilation

Environment Variables:

bash
GOOS=windows
GOARCH=amd64

Linux (Docker) - āœ… Multi-Architecture Support

Uses Ubuntu 24.04 base image with full GTK development environment:

Current Status: Complete multi-architecture Docker compilation system

  • āœ… ARM64 native compilation (Ubuntu 24.04)
  • āœ… x86_64 native compilation (Ubuntu 24.04)
  • āœ… Automatic architecture detection
  • āœ… All dependencies install correctly (GTK + WebKit)
  • āœ… Go 1.24 environment configured for each architecture
  • āœ… Native compilation eliminates cross-compilation CGO issues

Architecture Support:

  • ARM64: Native compilation using Dockerfile.linux-arm64
  • x86_64: Native compilation using Dockerfile.linux-x86_64 with --platform=linux/amd64
  • Auto-detect: Taskfile automatically selects appropriate architecture

Core Dependencies:

  • build-essential - GCC compiler toolchain (architecture-specific)
  • pkg-config - Package configuration tool
  • libgtk-3-dev - GTK+ 3.x development files
  • libwebkit2gtk-4.1-dev - WebKit2GTK development files
  • git - Version control (for go mod operations)
  • ca-certificates - HTTPS support

Docker Images:

  • wails-v3-linux-arm64 - Ubuntu 24.04 ARM64 native compilation (built from test/docker/Dockerfile.linux-arm64)
  • wails-v3-linux-x86_64 - Ubuntu 24.04 x86_64 native compilation (built from test/docker/Dockerfile.linux-x86_64)
  • wails-v3-linux-fixed - Legacy unified image (deprecated)

Docker Configuration

Multi-Architecture Build System

ARM64 Native Build Environment (test/docker/Dockerfile.linux-arm64)

dockerfile
FROM ubuntu:24.04
# ARM64 native compilation environment
# Go 1.24.0 ARM64 binary (go1.24.0.linux-arm64.tar.gz)
# Native GCC toolchain for ARM64
# All GTK/WebKit dependencies for ARM64
# Build script: /build/build-linux-arm64.sh
# Output: testbuild-{example}-linux-arm64

x86_64 Native Build Environment (test/docker/Dockerfile.linux-x86_64)

dockerfile
FROM --platform=linux/amd64 ubuntu:24.04
# x86_64 native compilation environment 
# Go 1.24.0 x86_64 binary (go1.24.0.linux-amd64.tar.gz)
# Native GCC toolchain for x86_64
# All GTK/WebKit dependencies for x86_64
# Build script: /build/build-linux-x86_64.sh
# Output: testbuild-{example}-linux-x86_64

Available Docker Tasks

Architecture-Specific Tasks

bash
# ARM64 builds
task test:example:linux:docker:arm64 DIR=badge
task test:examples:linux:docker:arm64

# x86_64 builds  
task test:example:linux:docker:x86_64 DIR=badge
task test:examples:linux:docker:x86_64

Auto-Detection Tasks (Recommended)

bash
# Single example (auto-detects host architecture)
task test:example:linux:docker DIR=badge

# All examples (auto-detects host architecture)
task test:examples:linux:docker

Implementation Details

Key Fixes Applied in v3.0.0-alpha

1. Complete Example Coverage

  • Before: 35 examples tested
  • After: 43 examples tested (100% coverage)
  • Added: dev, events-bug, gin-example, gin-routing, gin-service, html-dnd-api, notifications

2. Go Module Resolution

  • Issue: Inconsistent replace directives across examples
  • Fix: Standardized all examples to use replace github.com/wailsapp/wails/v3 => ../..
  • Examples Fixed: gin-example, gin-routing, notifications

3. Frontend Asset Embedding

  • Issue: Some examples referenced missing frontend/dist directories
  • Fix: Updated embed paths from //go:embed all:frontend/dist to //go:embed all:frontend
  • Examples Fixed: file-association, notifications

4. Manager API Migration

  • Issue: Windows badge service using deprecated API
  • Fix: Updated app.CurrentWindow() ā†’ app.Windows.Current()
  • Files Fixed: pkg/services/badge/badge_windows.go

5. File Association Example

  • Issue: Undefined window variable
  • Fix: Added proper window assignment from app.Windows.NewWithOptions()
  • Files Fixed: examples/file-association/main.go

Build Performance

  • macOS: ~2-3 minutes for all 43 examples
  • Windows Cross-Compile: ~2-3 minutes for all 43 examples
  • Linux Docker: ~5-10 minutes for all 43 examples (includes image build)
  • Total Build Time: ~10-15 minutes for complete cross-platform validation (129 builds)

Usage Examples

Single Example Testing (Requires DIR Parameter)

bash
# Test the badge example on all platforms
task test:example:darwin DIR=badge              # macOS native
task test:example:windows DIR=badge             # Windows cross-compile
task test:example:linux:docker DIR=badge        # Linux Docker (auto-detect arch)

All Examples Testing (No DIR Parameter)

bash
# Test everything - all 43 examples, all platforms
task test:examples:all

# This runs:
# 1. All Darwin builds (43 examples)
# 2. All Windows cross-compilation (43 examples)  
# 3. All Linux Docker builds (43 examples, auto-architecture)

# Platform-specific all examples
task test:examples                           # Current platform (43 examples)
task test:examples:linux:docker:arm64       # ARM64 builds (43 examples)
task test:examples:linux:docker:x86_64      # x86_64 builds (43 examples)

Continuous Integration

bash
# For CI/CD pipelines
task test:examples:all       # Complete cross-platform (129 builds)
task test:examples           # Current platform only (43 builds)

Build Process Details

macOS Builds

  1. Sets macOS-specific CGO flags for compatibility
  2. Runs go mod tidy in each example directory
  3. Compiles with go build -o testbuild-{example}-darwin
  4. Links against UniformTypeIdentifiers framework

Windows Cross-Compilation

  1. Sets GOOS=windows GOARCH=amd64 environment
  2. Runs go mod tidy in each example directory
  3. Cross-compiles with go build -o testbuild-{example}-windows.exe
  4. No CGO dependencies required (uses Windows APIs)

Linux Docker Builds

  1. Auto-Detection: Detects host architecture (ARM64 or x86_64)
  2. Image Selection: Uses appropriate Ubuntu 24.04 image for target architecture
  3. Native Compilation: Eliminates cross-compilation CGO issues
  4. Environment Setup: Full GTK/WebKit development environment
  5. Build Process: Runs go mod tidy && go build with native toolchain
  6. Output: Architecture-specific binaries (-linux-arm64 or -linux-x86_64)

Troubleshooting

Common Issues (All Resolved in v3.0.0-alpha)

Go Module Resolution Errors

bash
Error: replacement directory ../wails/v3 does not exist

Solution: All examples now use standardized replace github.com/wailsapp/wails/v3 => ../..

Frontend Asset Embedding Errors

bash
Error: pattern frontend/dist: no matching files found

Solution: Updated to //go:embed all:frontend for examples without dist directories

Manager API Errors

bash
Error: app.CurrentWindow undefined

Solution: Updated to use new manager pattern app.Windows.Current()

Build Warnings

Some examples may show compatibility warnings (e.g., notifications using macOS 10.14+ APIs with 10.13 target). These are non-blocking warnings that can be addressed separately.

Performance Optimization

Parallel Builds

bash
# The task system automatically runs builds in parallel where possible
task v3:test:examples:all    # Optimized for maximum throughput

Selective Testing

bash
# Test specific examples to debug issues
task v3:test:example:darwin DIR=badge
task v3:test:example:windows DIR=contextmenus

Performance Tips

Parallel Builds:

bash
# Build multiple examples simultaneously
task v3:test:example:darwin DIR=badge &
task v3:test:example:darwin DIR=binding &
task v3:test:example:darwin DIR=build &
wait

Docker Image Caching:

bash
# Pre-build Docker images
docker build -f Dockerfile.linux -t wails-v3-linux-builder .
docker build -f Dockerfile.linux-simple -t wails-v3-linux-simple .

Integration with Git

Ignored Files

All build artifacts are automatically ignored via .gitignore:

gitignore
/v3/examples/*/testbuild-*

Clean Build Environment

bash
# Remove all test build artifacts
find v3/examples -name "testbuild-*" -delete

Validation Results

Current Status (as of implementation):

  • āœ… macOS: All 43 examples compile successfully
  • āœ… Windows: All 43 examples cross-compile successfully
  • āœ… Linux: Multi-architecture Docker system fully functional

Build Time Estimates:

  • macOS: ~2-3 minutes for all examples
  • Windows: ~2-3 minutes for all examples (cross-compile)
  • Linux Docker: ~5-10 minutes for all examples (includes image build and compilation)
  • Complete Cross-Platform: ~10-15 minutes for 129 total builds

Future Enhancements

Planned Improvements:

  1. Automated Testing: Add runtime testing in addition to compilation
  2. Multi-Architecture: Support ARM64 builds for Apple Silicon and Windows ARM
  3. Build Caching: Implement Go build cache for faster repeated builds
  4. Parallel Docker: Multi-stage Docker builds for faster Linux compilation
  5. Platform Matrix: GitHub Actions integration for automated CI/CD

Platform Extensions:

  • FreeBSD: Add BSD build support
  • Android/iOS: Mobile platform compilation (when supported)
  • WebAssembly: WASM target compilation

Changelog

v3.0.0-alpha (2025-06-20)

šŸŽÆ Complete Cross-Platform Testing System

āœØ New Features

  • Complete Example Coverage: All 43 examples now tested (was 35)
  • Cross-Platform Validation: Mac + Windows builds for all examples
  • Standardized Build Artifacts: Consistent platform-specific naming
  • Enhanced Git Integration: Complete .gitignore patterns for build artifacts

šŸ› Major Fixes

  • Go Module Resolution: Standardized replace directives across all examples
  • Frontend Asset Embedding: Fixed missing frontend/dist directory references
  • Manager API Migration: Updated deprecated Windows badge service calls
  • File Association: Fixed undefined window variable
  • Build Completeness: Added 8 missing examples to test suite

šŸ”§ Infrastructure Improvements

  • Taskfile Integration: Comprehensive cross-platform build tasks
  • Performance Optimization: Parallel builds where possible
  • Error Handling: Clear build failure reporting and debugging
  • Documentation: Complete testing guide with troubleshooting

šŸ“Š Validation Results

  • macOS: āœ… 43/43 examples compile successfully
  • Windows: āœ… 43/43 examples cross-compile successfully
  • Build Time: ~5-6 minutes for complete cross-platform validation
  • Reliability: 100% success rate with proper error handling

Support

For issues with cross-platform builds:

  1. Check platform-specific requirements above
  2. Review the troubleshooting section for resolved issues
  3. Verify Go 1.24+ is installed
  4. Check build logs for specific error messages
  5. Use selective testing to isolate problems

References