Building and Testing

Building and Testing

Toolchain

• Kotlin 2.4 with Jetpack Compose (Material 3)
• Android Gradle Plugin 9.x on Gradle 9.6+ (the wrapper pins the exact version)
• JDK 17 target (Android Studio's bundled JDK 21 works fine for building)
• compileSdk 36; phone minSdk 26 (Android 8.0+), watch minSdk 30 (Wear OS 3+)
• Two modules: :app (phone) and :wear (the Wear OS status tile)

Note: AGP 9 ships Kotlin support built in. Do not apply the org.jetbrains.kotlin.android plugin; the Kotlin version is pinned in the root build script.

Common commands

export JAVA_HOME="<path-to-jdk>"     # e.g. Android Studio's bundled JBR

./gradlew assembleDebug              # build both modules' debug APKs
./gradlew :app:testDebugUnitTest     # run unit tests
./gradlew :app:lintDebug             # run Android Lint (must pass)
./gradlew :wear:assembleDebug        # build just the Wear OS tile

The debug APKs land in app/build/outputs/apk/debug/ and wear/build/outputs/apk/debug/.

Wear OS module

The :wear module is a standalone Wear app (the status tile) with no Google Play Services. To try it on a Wear OS emulator or watch:

./gradlew :wear:assembleDebug
adb -s <wear-device> install -r wear/build/outputs/apk/debug/wear-debug.apk

# add the tile without hunting through the carousel:
adb -s <wear-device> shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SURFACE \
  --es operation add-tile \
  --ecn component dev.astoris.ursa/dev.astoris.ursa.wear.StatusTileService

The tile polls a public Kuma status page; point it at one via the tile's setup screen. See Wear OS.

Running against Uptime Kuma

Point the app at any reachable Kuma instance. For a quick local server:

docker run -d -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

From the Android emulator, the host machine is reachable at http://10.0.2.2:3001.

Git hooks

Committed files use ASCII punctuation (a plain -, not an em-dash or en-dash). A shared hook enforces this; enable it once after cloning:

git config core.hooksPath scripts/hooks

The same check runs in CI.

Continuous integration

Every push and pull request runs:

• an ASCII-punctuation check,
• assembleDebug, testDebugUnitTest, and lintDebug.

Dependabot keeps Gradle and Actions dependencies current, and workflow static analysis (zizmor) and CodeQL run as security checks. Releases and the changelog are generated from Conventional Commit messages.

Tests

Wire-format parsing and pure logic (the slow-response threshold evaluator, downtime formatting, snapshot/cert codecs) are covered by JVM unit tests, kept intentionally free of Android types so they run without a device. Add or update tests for any logic change.