Skip to content

Building and Testing

Michael Riddle edited this page Jul 27, 2026 · 10 revisions

Building & Testing

KHost Cue is a .NET 10 MAUI Blazor Hybrid app with Android, iOS, Windows and Mac Catalyst heads plus two xUnit test projects, all in one solution (KHost.Mobile.slnx, kept separate from the desktop KHost solution so MAUI workloads never slow that build). This page takes a contributor from a clean clone to a running app on a device or emulator, and covers how to verify a change before committing. For what the projects actually contain, see Architecture; for coding conventions, see Conventions.

Prerequisites

Host OS Needed
Any .NET 10 SDK + MAUI workload: dotnet workload install maui
Windows Builds the Android and Windows heads. Android SDK + JDK 17+ (see below if you don't have them). Cannot build iOS — see Gotchas.
macOS Builds Android, iOS, and Mac Catalyst. iOS needs a paired/local Mac — there is no iOS-on-Windows path. Mac Catalyst needs full Xcode, not just Command Line Tools (see Gotchas).

If you have neither the Android SDK nor a JDK, .NET Android can fetch both at the versions this project targets:

dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-android -t:InstallAndroidDependencies \
  -p:AndroidSdkDirectory=$HOME/Library/Android/sdk -p:JavaSdkDirectory=$HOME/Library/Android/jdk \
  -p:AcceptAndroidSDKLicenses=true

Then export ANDROID_HOME and JAVA_HOME at those paths, or every build needs the -p:AndroidSdkDirectory=… -p:JavaSdkDirectory=… flags. (Warnings on that command's first run come from the evaluation pass before the SDK exists — they clear once install finishes.)

Restore evaluates every declared TargetFramework, not just the one you build with -f. KHost.Mobile.csproj conditionally declares net10.0-android always, net10.0-ios on any non-Linux host, net10.0-windows10.0.19041.0 on Windows, and net10.0-maccatalyst on macOS. A single-head build fails until all the heads the current OS declares have workloads installed. Run this once per machine instead of chasing individual missing-workload errors:

dotnet workload restore KHost.Mobile/KHost.Mobile.csproj

Directory.Build.props applies TreatWarningsAsErrors + EnforceCodeStyleInBuild to every project in the repo — a .editorconfig style violation fails the build, not just an IDE squiggle.

Build commands

All commands assume the repo root as the working directory. -p:BaseOutputPath=./obj/_build redirects build output away from the IDE's bin//default obj/ so it doesn't get locked while Visual Studio / Rider has the solution open — include it on every build.

Target Command
Android (build only) dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-android "-p:BaseOutputPath=./obj/_build"
Android (build, deploy, launch) dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-android -t:Run "-p:BaseOutputPath=./obj/_build"
Windows (build) dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-windows10.0.19041.0 "-p:BaseOutputPath=./obj/_build"
Windows (run — fastest UI iteration, no emulator) dotnet run --project KHost.Mobile -f net10.0-windows10.0.19041.0 "-p:BaseOutputPath=./obj/_build"
Mac Catalyst (build — macOS only, dev preview, not a shipping target) dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-maccatalyst "-p:BaseOutputPath=./obj/_build"
Mac Catalyst (run) dotnet run --project KHost.Mobile -f net10.0-maccatalyst "-p:BaseOutputPath=./obj/_build"
iOS (simulator, build+deploy+launch — Mac only) dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-ios -t:Run "-p:BaseOutputPath=./obj/_build" "-p:_DeviceName=:v2:udid=<udid>"
Clients library alone dotnet build KHost.Mobile.Clients/KHost.Mobile.Clients.csproj

Mac Catalyst builds maccatalyst-arm64 only (Apple-silicon native; Debug would otherwise default to maccatalyst-x64, which runs under Rosetta) — that RID is scoped to the maccatalyst TFM in the csproj so it can't leak into other heads.

Deploying to a device or emulator

Android

Always deploy the Debug build with -t:Run, never adb install the APK. Debug keeps the .NET assemblies outside the APK (Fast Deployment) and relies on the MSBuild deploy target to push them to the device's files/.__override__/. A bare adb install launches the app then it immediately crashes with "No assemblies found in '.../.override/...'. Assuming this is part of Fast Deployment. Exiting." -t:Run does the push and starts the activity in one step. (For a self-contained APK that adb install can handle, build with -p:EmbedAssembliesIntoApk=true.)

Target a specific device when more than one is attached:

dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-android -t:Run \
  "-p:BaseOutputPath=./obj/_build" "-p:AdbTarget=-s <serial>"

Wireless adb: the port rotates every session. Read the current <ip>:<port> live off the phone (Settings → Developer options → Wireless debugging) — it isn't stable across reconnects, so a saved value from last session won't work — then adb connect <ip>:<port> before targeting that serial with -p:AdbTarget. If adb connect wedges (hangs, or connects but the device never shows in adb devices), adb kill-server && adb start-server and reconnect.

Emulator: Fast Deployment ships assemblies, not wwwroot. The Razor/JS/CSS assets are baked into the APK, not pushed by Fast Deployment, so a stale APK plus a fresh -t:Run (which only re-pushes assemblies) leaves C# calling into JS that isn't there — the WebView console shows something like Could not find 'khArtVisibility.register' and the Blazor circuit dies with "An unhandled error has occurred". This is easy to hit on an emulator started with -no-snapshot-save: a restart reverts /data (APK included) while the next -t:Run only restores assemblies, so the two drift apart. Fix: adb uninstall khost.mobile then redeploy with -t:Run. Note an uninstall re-runs the first-run tutorial, whose full-screen overlay swallows every tap until it's dismissed.

iOS simulator

xcrun simctl list devices available          # find the target udid
xcrun simctl boot <udid>                     # boot it first
dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-ios -t:Run \
  "-p:BaseOutputPath=./obj/_build" "-p:_DeviceName=:v2:udid=<udid>"

-t:Run can stall on the iOS simulator even when the build succeeded. If the log reaches Build succeeded but nothing installs, skip MSBuild's deploy and install the bundle directly — safe here because, unlike Android's Fast Deployment, the simulator bundle carries its own assemblies:

xcrun simctl install <udid> KHost.Mobile/obj/_buildDebug/net10.0-ios/iossimulator-arm64/KHost.Mobile.app
xcrun simctl launch  <udid> khost.mobile

The cold-iOS-build "hung at actool" gotcha

A cold iOS build looks dead at the asset-catalog compile step: _CoreCompileImageAssets shells out to xcrun actool, which prints nothing for several minutes while it works. A foreground build sitting silent that long looks stuck and invites getting killed — which is how a simulator ends up still running last month's build. Run it detached and tail the log instead (*.log is gitignored):

dotnet build KHost.Mobile/KHost.Mobile.csproj -f net10.0-ios "-p:BaseOutputPath=./obj/_build" -v:n > ios-build.log 2>&1 &
tail -f ios-build.log

The log's last line names the current phase; external tool execution … actool means it's still working, not stuck. A genuinely stuck actool is a different signature (see the Mac Catalyst Xcode gotcha below) — check ps -Ao pid,etime,comm | grep -iE 'actool|ibtool' to tell a working actool (present, accumulating etime) from an absent one.

Always deploy what you just built

Deploy the build you just made to every emulator/simulator you're about to look at — never trust what's already installed. An emulator/simulator keeps its last install indefinitely, so a months-old build sits there looking current and you end up reviewing code that isn't yours. Building alone installs nothing; only a -t:Run deploy (or the manual simctl install above) does. Verify the version rather than assuming:

# Android
adb -s <serial> shell dumpsys package khost.mobile | grep versionName

# iOS — look at CFBundleVersion, which is <ApplicationVersion> in the csproj
xcrun simctl listapps <udid> | grep -A12 khost.mobile

Back up device data before deploying to a physical device

No exceptions — back it up first. Deploying with -t:Run normally updates the app in place and keeps on-device data (files/*.json, shared_prefs/), but a few things silently force an uninstall + reinstall that wipes singers, song lists, tonight sets, venues and settings:

  • A signing-key mismatch — a build from a different machine, or a regenerated debug keystore (~/.android/debug.keystore) — fails to install over the existing app and the tooling falls back to uninstall + reinstall.
  • An ApplicationId/package-id change.
  • A manual uninstall to troubleshoot a launch crash.

Back up first with the file-based backup script (scripts/*.cs, run via dotnet run — no separate build/publish step):

dotnet run scripts/backup-device-data.cs -- backup                 # timestamped .tar.gz -> device-backups/ (gitignored)
dotnet run scripts/backup-device-data.cs -- list                   # what backups exist
dotnet run scripts/backup-device-data.cs -- inspect <file.tar.gz>  # peek inside one
dotnet run scripts/backup-device-data.cs -- restore <file.tar.gz>  # push a backup back onto the device
#   -s, --serial <serial>   target one of several attached devices (also honors $ANDROID_SERIAL)
#   restore also takes -y/--yes to skip the confirmation

It pulls the app's private data via adb run-as khost.mobile (Debug builds only, no root) into the gitignored device-backups/. restore force-stops the app and puts the data back — relaunch to see it.

Clearing the scratch folders

Both gitignored scratch folders grow without bound — a backup is ~48 MB per run, and the UI walkers drop a PNG per screenshot — so a day of on-device work can leave over a gigabyte behind:

dotnet run scripts/cleanup-scratch.cs --                    # keep the 3 newest backups, clear all shots
dotnet run scripts/cleanup-scratch.cs -- --dry-run          # show what would go, delete nothing
dotnet run scripts/cleanup-scratch.cs -- --keep 5           # keep the 5 newest backups
#   --backups-only / --shots-only   limit it to one folder

Backups are the only safety net against a redeploy that reinstalls, so the newest --keep are always retained (--keep 0 empties the folder and warns). Screenshots are regenerated by the walkers, so all of them go. Only the script's own artifacts are touched — a khost-mobile-*.tar.gz and image files respectively — so anything else parked in either folder survives.

<MauiVersion> is pinned — don't "clean it up"

KHost.Mobile.csproj pins <MauiVersion>10.0.80</MauiVersion>, overriding the workload's default (10.0.20) on purpose. 10.0.20 crashes immediately on launch on Android 16 / API 36 — a .NET 10 MAUI root-fragment regression: "No view found for id … for fragment NavigationRootManager_ElementBasedFragment" (dotnet/maui #35418 / #31581). If this launch crash reappears after a workload update, bump MauiVersion to the latest serviced 10.0.x on NuGet (same feature band, newer patch) and confirm the fix with adb logcat for the "No view found" FATAL.

Testing

Two xUnit projects, both targeting plain net10.0 — neither needs the MAUI workload. Each references KHost.Mobile.Clients normally (a plain library, no MAUI dependency), which is how the Matching/ types below get exercised. But neither can reference the MAUI head (KHost.Mobile) directly — a net10.0 project can't reference a MAUI head — so the MAUI-free source under test (models, JSON stores) is pulled in instead via linked <Compile> items in each .csproj, pointing at files under KHost.Mobile/Models and KHost.Mobile/Services. The stores' only device dependency, the app-data path, is abstracted behind IAppDataDirectory; the integration project fakes it with TempAppDataDirectory, pointed at a real (but throwaway) temp folder.

Suite Command Covers
Unit dotnet test KHost.Mobile.UnitTests/KHost.Mobile.UnitTests.csproj "-p:BaseOutputPath=./obj/_build" Pure, no-I/O logic: playlist/metadata/lyrics parsers, Genres.Map, SongListItem computed properties, RatingScore, SurprisePicker, and the spelling-suggestion matching bar (Matching/TrackTextNormalizer, TrackSimilarity, TrackSuggestionFinder — see TrackTextNormalizerTests.cs, TrackSimilarityTests.cs, TrackSuggestionFinderTests.cs).
Integration dotnet test KHost.Mobile.IntegrationTests/KHost.Mobile.IntegrationTests.csproj "-p:BaseOutputPath=./obj/_build" The JSON stores (JsonFileSongListStore, JsonFileTonightStore, JsonFileVenueStore, JsonFileSingerStore, JsonFileLyricsCache) against a real temp folder — real file I/O and System.Text.Json serialization — via a fake IAppDataDirectory.

Both suites must pass before any commit or push — never commit or push with a failing (or unrun) suite. Test runs never touch device data (they use a throwaway temp folder), so the data-loss risk described above is specific to device deploys, not to running tests.

For the store pattern these tests exercise, see Data storage.

Driving the running UI

Neither test suite touches the UI. Gesture- and sheet-shaped changes (swipe, press-and-hold, bottom sheets) are verified by driving the app's Blazor WebView over the Chrome DevTools Protocol with the tools in playwright/ (Debug builds enable WebView debugging via AddBlazorWebViewDeveloperTools):

Folder Driver Target Why
playwright/device/ Full Playwright (khdrive.mjs) A physical device, and the Windows head Current WebView, Playwright's connectOverCDP handshake works.
playwright/emulator/ Raw CDP (cdp.mjs), Node's built-in WebSocket, no dependency The Android emulator The emulator's older WebView doesn't implement Browser.setDownloadBehavior, which Playwright calls on connect — it fails with "Browser context management is not supported" before reaching the page. Playwright's native Android API (_android.devices().webViews()) also doesn't work here: it returns nothing unless it can install a companion APK.

Both expose tap/swipeDown-style real-touch gestures (Input.dispatchTouchEvent), not a DOM .click() — needed for gestures wired through swipe.js (tap vs. hold vs. swipe) and khSheet (pull-down-to-dismiss) to actually fire. playwright/README.md is the canonical how-to: attach flow (adb forward to the WebView devtools socket), a walk_tutorial.mjs example per target, and the on-device gotchas (screenshot capture, sheet-stacking, seeding).

Screenshots

Two different capture flows, for two different purposes:

  • The README grid is shot from a physical device by playwright/device/shoot_docs.mjs (plus shoot_spelling.mjs for the spelling-suggestion ⚠, which needs a song with a pending suggestion, so it adds and removes a misspelled one). Attach per playwright/README.md, then node device/shoot_docs.mjs [name …]. Shots land at the device's native size — 1080 × 2400 from a Pixel 8, status/nav bars included — so re-shoot the whole grid from one device rather than mixing sources. Capture goes through adb exec-out screencap, not page.screenshot — CDP capture hangs on this WebView (current device heads and the emulator's older one alike); only navigation runs over CDP.
  • The mobile-preview target size is 786 × 1704 px — a 393 × 852 (iPhone 15/16) viewport at 2× device-pixel-ratio. This is what App.PinToMobilePreviewViewport pins the Mac Catalyst window to for layout preview; the docs grid no longer uses it.

Two traps in the docs-grid script silently photograph the wrong screen: sheets stack (e.g. detail → history), so close the last .sheet__close, not the first; and the venue/singer chip popovers are not sheets, so a sheet-close leaves them open to eat the next click. The script asserts what's on screen before every shutter for exactly this reason.

Gotchas

Gotcha Detail
iOS can't build on Windows Needs a paired Mac. A bare dotnet build on the solution from Windows surfaces iOS/Apple-toolchain errors that are not your code — build the Android head explicitly to verify on Windows, and use the Windows head for fast UI iteration; iOS is validated with a Mac in the loop.
Restore evaluates every declared TFM Even with -f, restore walks every TFM the csproj declares for the current host OS, so a single-head build fails until all of them have workloads. dotnet workload restore KHost.Mobile/KHost.Mobile.csproj fixes it.
Mac Catalyst needs full Xcode, not Command Line Tools Three separate checks, all of which look like build breakage but aren't: (1) xcode-select -p must point at /Applications/Xcode.app/Contents/Developer (sudo xcode-select -s …); (2) the license must be accepted (sudo xcodebuild -license accept) — xcodebuild -version succeeds without it, so it is not a valid check; read IDEXcodeVersionForAgreedToGMLicense from /Library/Preferences/com.apple.dt.Xcode instead; (3) xcodebuild -runFirstLaunch must have installed the extra components, or actool fails with ibtoold failed IDE initialization.
FileSystem.AppDataDirectory is the Data subfolder On unpackaged Windows it's %LOCALAPPDATA%\KHost\khost.mobile\Data\ (parent folders are the appxmanifest PublisherDisplayName=KHost and ApplicationId=khost.mobile) — not the parent khost.mobile\. Seeding/inspecting persisted state must target Data\. Pre-rename builds wrote to the legacy %LOCALAPPDATA%\User Name\com.companyname.khost.mobile\Data\, which current builds ignore.
Windows-head UI automation is flaky WebView2 swallows the first SendKeys burst after launch, and scroll position varies between launches (fixed click coordinates drift). For persistence checks, seed/read the JSON files under Data\ directly instead of driving the form; to drive the UI itself, use playwright/ (real CDP locators sidestep the SendKeys/coordinate flakiness).
FocusOnNavigate targets a nonexistent h1 The MAUI template's Components/Routes.razor has FocusOnNavigate Selector="h1"; no page in this app has an <h1>, so nothing auto-focuses on navigation. Harmless — just don't rely on autofocus.
Wireless-adb port rotates every session Read the current <ip>:<port> off the phone (Settings → Developer options → Wireless debugging) each time, then adb connect <ip>:<port>. A wedged adb connect clears with adb kill-server && adb start-server.
Emulator: stale APK + fresh assemblies breaks JS interop Fast Deployment (-t:Run) re-pushes .NET assemblies but not wwwroot — that's baked into the APK. A restarted -no-snapshot-save emulator reverts /data (APK included), so the next -t:Run restores only the assemblies and the two drift apart: C# calls JS that isn't there and the Blazor circuit dies. adb uninstall khost.mobile then redeploy.

Housekeeping

  • Don't commit or push unless explicitly asked.
  • /research/ is gitignored and must never be committed — it holds local planning/research notes and scratch data (this wiki draft included). Don't stage it, don't offer to commit it, and don't propose removing it from .gitignore.
  • Keep README.md (product-facing, including the screenshot grid) in sync with the app whenever a user-facing feature changes. This page is the canonical build/deploy/test command reference — keep it in sync whenever the build process changes; DEVELOPMENT.md keeps the design-notes rationale instead of its own command copy.

See also

  • Architecture — project layout and what each project owns.
  • Data storage — the JSON store pattern the integration tests exercise.
  • UI components — the Blazor component conventions the Playwright walkers drive.
  • Conventions — coding style and patterns for anyone contributing changes.

Clone this wiki locally