Building and Testing

Building and Testing

Toolchain

• Kotlin 2.4 with Jetpack Compose (Material 3)
• Android Gradle Plugin 9.3.2 on Gradle 9.7.1
• JDK 17 target (Android Studio's bundled JDK 21 works fine for building)
• compileSdk/targetSdk 37; phone minSdk 26, watch minSdk 30
• Two modules: :app (phone) and :wear (full Wear OS companion)

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
./gradlew :wear:testDebugUnitTest :wear:lintDebug
./gradlew -PursaWearBridge=true :app:assembleDebug # GitHub paired-watch variant

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 with dashboard, detail, tile, and complications. 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

Public mode polls a Kuma status page. Private mode requires the optional GitHub phone build and a real same-signed phone/watch pair. 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 are prepared and published manually from a reviewed release commit.

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.