Running and testing Scanly

Everything needed to install the debug app, use it on a device or emulator, and run the automated suites. Companion pages: setup.md (SDK, signing, variants) and testing.md (coverage inventory).

All Gradle commands below are from the Scanly repository root (Scanly/) in PowerShell.

What you need

Native libraries ship for arm64-v8a and armeabi-v7a only. A physical ARM phone is the most reliable target. An x86_64 emulator still runs (ARM translation) but LiteRT model calibration can SIGSEGV; the connected test suite isolates that so one crash does not abort the rest.

Confirm the SDK path in local.properties (sdk.dir=...). That file is local and must not be committed.

Open the project

cd Scanly

Open this folder in Android Studio (File → Open). Let Gradle sync. The only Android module is :app. Application id: in.c1ph3rj.scanly.

Run the app

Android Studio

1. Select the debug variant (not githubRelease / playStoreRelease).
2. Plug in a phone with USB debugging, or start an emulator (API 29+).
3. Run app (green play). Entry point is MainActivity.

First launch shows onboarding. Tap Get started to reach Home (Scan / Import / Folder). Later launches skip onboarding.

Command line (install debug APK)

# Build
./gradlew.bat assembleDebug

# See devices (status must be "device", not unauthorized / offline)
adb devices -l

# Install and launch
./gradlew.bat installDebug
adb shell am start -n in.c1ph3rj.scanly/.MainActivity

If adb devices is empty, Android Studio did not start a device, USB debugging is off, or the SDK platform-tools are not on PATH. Use the SDK copy:

& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" devices -l

First-run permissions

Grant camera when you want to scan. Gallery import uses the system photo picker (no storage permission on current SDKs).

Create an emulator if you have none

Android Studio: Device Manager → Create device → Pixel 7 (or similar) → a system image API 29+.

CLI example (adjust the system-image package to one you already have under Sdk\system-images):

$sdk = "$env:LOCALAPPDATA\Android\Sdk"
& "$sdk\cmdline-tools\latest\bin\avdmanager.bat" create avd `
  -n scanly_ui_test `
  -k "system-images;android-36.1;google_apis_playstore;x86_64" `
  -d pixel_7 --force

# Keep this process running
& "$sdk\emulator\emulator.exe" -avd scanly_ui_test -no-audio -no-boot-anim

In another terminal, wait until the serial shows device and boot is complete:

adb wait-for-device
adb shell getprop sys.boot_completed   # expect 1

Manual smoke path

After Home is visible:

1. Home — Scan / Import / Folder actions.
2. Library — All / Folders / Documents, search.
3. Tools — QR (scan or generate), PDF workspace.
4. Settings — Appearance, Storage & backup, Document detection.

Live camera, the system photo picker, SAF folder pick, share sheet, widgets, and Play in-app updates are manual-only (not in the automated UI suite).

Automated tests

Two layers:

Also useful:

./gradlew.bat lintDebug
./gradlew.bat assembleDebugAndroidTest   # compile instrumented tests without a device

JVM unit tests (no device)

./gradlew.bat testDebugUnitTest

Reports: app/build/reports/tests/testDebugUnitTest/index.html.

Flow tests that drive shipped use cases (not mocked UI) live under app/src/test/java/in/c1ph3rj/scanly/domain/usecase/:

Run one class:

./gradlew.bat testDebugUnitTest --tests "in.c1ph3rj.scanly.domain.usecase.DocumentLibraryFlowTest"

These tests use contract-complete in-memory repositories behind the existing interfaces. They do not exercise CameraX, Room, DataStore, WorkManager, or OpenCV on the JVM.

Instrumented / device UI tests

adb devices -l    # at least one line ending in "device"
./gradlew.bat connectedDebugAndroidTest

If Gradle reports No connected devices! while adb devices lists a phone, Gradle is not using the same adb. Set the SDK and serial, then retry:

$env:ANDROID_HOME = "$env:LOCALAPPDATA\Android\Sdk"
$env:ANDROID_SDK_ROOT = $env:ANDROID_HOME
$env:ANDROID_SERIAL = "<serial from adb devices>"   # e.g. emulator-5554
./gradlew.bat connectedDebugAndroidTest

Optional: turn off system animations (the build already sets animationsDisabled for the test runner):

adb shell settings put global window_animation_scale 0
adb shell settings put global transition_animation_scale 0
adb shell settings put global animator_duration_scale 0

Reports: app/build/reports/androidTests/connected/debug/index.html.

What the device UI suite does

ScanlyDeviceUiTest starts the real MainActivity (Hilt app process), not an isolated composable. Android Test Orchestrator clears app data before each test, so onboarding runs again. Camera and (on API 33+) notifications are granted; leftover system dialogs are dismissed.

Helpers live in ScanlyDeviceUiRobot.kt. Selectors are ScanlyTestTags in app/src/main/.../core/ui/ScanlyTestTags.kt (nav tabs and screen roots).

Also still run on device:

• OnboardingScreenTest — Compose onboarding layouts (setContent)
• OpenCvPageFilterProcessorTest — filter engine on device
• ExampleInstrumentedTest — package name

Run only the shell UI class:

./gradlew.bat connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=in.c1ph3rj.scanly.ScanlyDeviceUiTest

What device UI tests do not cover

Live CameraX capture, LiteRT corner/gate on a real camera, auto-capture, torch, system photo picker, SAF folder picker, Android share sheet, widget pin, Play in-app update UI, and a single NavHost marathon of every route.

Lint

./gradlew.bat lintDebug

Troubleshooting

Related docs

• setup.md — SDK levels, variants, signing
• testing.md — unit-test inventory and contribution expectations
• ../overview/user-guide.md — product workflows
• ../architecture/navigation.md — routes
• ../../README.md — project overview