Build and test¶
TL;DR
Install the .NET 10 SDK, clone the repo and run dotnet build windows/GameControllerForZwift.sln on Windows. The build downloads the native SDL2 library once and checks its SHA256 hash. Run the tests with dotnet test. Warnings are errors, and formatting is checked with dotnet format, so keep the build clean.
What you need¶
- Windows 10 or 11 for the full solution. The WPF app and its tests only build on Windows.
- .NET 10 SDK.
windows/global.jsonasks for SDK10.0.100withrollForward: latestFeature, so any newer 10.0 feature band works. - An editor such as Visual Studio 2026, Visual Studio Code or Rider. Visual Studio needs the ".NET desktop development" workload for WPF.
The Core, Network and Gamepad libraries, their tests and ZwiftLanProbe also build on Linux and macOS. CI uses that for the formatting check.
Everything that belongs to the app lives in windows/: the solution, global.json, Directory.Build.props, build/, src/, tests/ and tools/. The commands on this page run from the repo root.
Build¶
git clone https://github.com/VoltageSolutions/GameControllerForZwift.git
cd GameControllerForZwift
dotnet build windows/GameControllerForZwift.sln
Run the app:
dotnet run --project windows/src/Presentation/GameControllerForZwift
SDL2 download¶
The app reads controllers through the native SDL2 library. windows/build/Sdl2.targets (imported by the Gamepad project) takes care of it:
- On Windows only, before the build needs it, it downloads
SDL2-2.30.10-win32-x64.zipfrom the official SDL GitHub releases intowindows/.cache/sdl2/. - It checks the zip's SHA256 hash against the value in the targets file. If the hash does not match, the zip is deleted and the build fails.
- It unzips
SDL2.dlland copies it next to the app in both build and publish output.
The download happens once. Later builds reuse windows/.cache/sdl2/SDL2.dll.
Building offline
Put SDL2.dll (version 2.30.10, win32-x64) into windows/.cache/sdl2/ yourself and the build skips the download.
Tests¶
| Project | Kind | What it covers | Runs on |
|---|---|---|---|
GameControllerForZwift.Core.UnitTests |
Unit | Mapping, profiles, JSON converters, analog values, DataIntegrator |
Any OS |
GameControllerForZwift.Gamepad.UnitTests |
Unit | SDL power level mapping, USB device lookup | Any OS |
GameControllerForZwift.Network.UnitTests |
Unit | Direct Connect framing and sessions, UUIDs, keypad frames, analog input, mDNS profile, replies that match the known-good Zwift Ride presentation | Any OS |
GameControllerForZwift.Network.IntegrationTests |
Integration | MdnsAdvertiser and ZwiftRideOutputService over real sockets |
Any OS |
GameControllerForZwift.UnitTests |
Unit (WPF) | App startup, view models, converters, controls, navigation | Windows |
GameControllerForZwift.UITests |
UI | Drives the real app with Appium and WinAppDriver (About and Settings pages) | Windows, with WinAppDriver and Appium installed |
The tests use xUnit and NSubstitute. Run them all with:
dotnet test windows/GameControllerForZwift.sln
Or run one project:
dotnet test windows/tests/GameControllerForZwift.Network.UnitTests
UI tests need extra tools
The UI tests need WinAppDriver and an Appium server with the Windows driver. CI installs both. Locally, you can skip that project and run the others.
Code quality¶
windows/Directory.Build.props applies to every project:
| Setting | Effect |
|---|---|
AnalysisLevel = latest-recommended |
The recommended set of .NET code analyzers is on. |
EnableNETAnalyzers = true |
Analyzers run during the build. |
TreatWarningsAsErrors = true |
Any warning fails the build. |
.editorconfig only adjusts analyzer severities. For example, test projects may use underscores in test method names. Formatting follows the dotnet format defaults. Check it before you push:
dotnet format windows/src/Infrastructure/GameControllerForZwift.Network --verify-no-changes --severity error
The Lint job in Windows CI runs this check on Core, Network, Gamepad, the portable test projects and ZwiftLanProbe.
ARM smoke test¶
The ARM smoke test job in Windows CI runs the x64 builds from the Build job (framework-dependent and standalone) on a windows-11-arm runner. .github/scripts/smoke-test-app.ps1 starts the app under x64 emulation and checks that its log shows SDL2 initialized and devices enumerated. The Build job also uploads both builds as the app-win-x64 and app-win-x64-standalone artifacts (kept for 14 days), so you can copy them to a real ARM device.
Workflows¶
The GitHub Actions workflows live in .github/workflows/.
| Workflow | File | When it runs | What it does |
|---|---|---|---|
| Windows CI | windows-ci.yml |
Every pull request | Builds and publishes the app, runs the unit, integration and UI tests, checks formatting, the version, CodeQL and vulnerable packages, and uploads coverage. |
| Windows CD | windows-cd.yml |
Push to main (not for docs-only changes) |
Publishes both zips, creates the GitHub release and opens the next release branch. |
| Windows CodeQL and Coverage | windows-codeql-and-coverage.yml |
Push to main (not for docs-only changes) |
Refreshes the CodeQL alerts and Codecov coverage that pull requests compare against. |
| Docs CI | docs-ci.yml |
Pull requests that change the docs | Builds the docs site with --strict. |
| Docs CD | docs-cd.yml |
Push to main that changes the docs |
Builds and deploys the docs site to GitHub Pages. |
| Release Branch | release-branch.yml |
A release/vX.Y.Z branch is created |
Sets <Version> in windows/Directory.Build.props to match the branch name. |
Optional: the build watcher¶
windows/tools/dev/build-watcher.ps1 is a small helper for driving builds on a Windows machine from somewhere else, for example a remote session that can write files but has no shell there. Start it from the repo root:
powershell -ExecutionPolicy Bypass -File windows\tools\dev\build-watcher.ps1
It checks every 2 seconds for a file called .build-request in the repo root.
- An empty request runs
build,test-networkandtest-unit. - Otherwise list one keyword per line:
build,test,test-network,test-unit,clean, or a custom line that starts withdotnet.
While it works it renames the request to .build-running. It writes one log per step (build.log, test-network.log, test-unit.log, or step-N.log for custom lines) and finishes with .build-done, which lists the exit code and duration of each step. A failed build stops the sequence. The marker files are ignored by git.