Home

Awesome

commcare-android

CommCare is an easily customizable, open source mobile platform that supports frontline workers in low-resource settings. By replacing paper-based forms, frontline workers can use CommCare to track and support their clients with registration forms, checklists, SMS reminders, and multimedia.

This repository represents the Android version of CommCare. It depends on the CommCare Core repository, which contains the XForm engine and case/lookup table implementations.

End-to-End Development

CommCare Android is a mobile CommCare Platform client runtime, and requires a backend environment for full end-to-end usage and to test platform development.

If you don't have an access to another backend, or if you will be doing full platform development, after completing this setup you can follow the end-to-end development guide which explains how to establish a local environment for CommCare's full client/server software.

Setup

To set up an Android dev environment for commcare-android, do the following:

Go ahead and open Android Studio if this is your first time using it; it may take you through some sort of setup wizard, and it's nice to get that out of the way. If it's not the first time, ensure that there are no references to removed Java options in your environment, most commonly found are MaxPermSize and PermSize

Android Studio's default project space is ~/AndroidStudioProjects so I'm going to use that in the example. CommCare Android depends on CommCare Core, and CommCare Android expects the core directory to live side by side in your directory structure. You can acheive this with the following commands (in bash):

cd ~/AndroidStudioProjects
mkdir CommCare
cd CommCare
git clone https://github.com/dimagi/commcare-android.git
git clone https://github.com/dimagi/commcare-core.git

Building

Now you're basically ready to go. To build CommCare Android and get it running on your phone, plug in an android phone that

In Android Studio, hit the build button (a green "play" symbol in the toolbar). The first build will take a minute. Then it'll ask you what device to run it on

Enjoy!

Building from the command-line

CommCare has several different build variants. The normal build variant is commcare and can built built from the command-line with the following command:

cd commcare-android
./gradlew assembleCommcareDebug
# the apk can now be found in the build/outputs/apk/ directory

Unit Tests

The commcare-android repository uses Robolectric, which provides mocks, allowing you to run Android specific code on your local machine.

Run unit-tests from the command-line

cd commcare-android
./gradlew testCommcareDebug

and view the results from the output file generated.

Run unit-tests from Android Studio

Create a new Android Studio JUnit Build configuration using the following steps.

Instrumentation Tests

The commcare-android repository uses Espresso to write UI tests. You need to have two keys in your gradle.properties before being able to run any instrumentation tests. But make sure you never commit these keys to github.

HQ_API_USERNAME=<ASK_ANOTHER_DEV_FOR_KEY>
HQ_API_PASSWORD=<ASK_ANOTHER_DEV_FOR_KEY>

Run instrumentation-tests from the command-line

cd commcare-android
./gradlew connectedCommcareDebugAndroidTest

It's also a common requirement to run a particular test, such as when you’re fixing a bug or developing a new test. You can achieve the same in command-line using:

./gradlew connectedCommcareDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=<FULLY_QUALIFIED_NAME_OF_YOUR_TEST>

You can view the results from the output file generated.

Run instrumentation-tests from Android Studio

Before running tests from Android-Studio make sure you've disabled animations in your device. Note, this is only required when you're running tests from Android Studio

Go to Setting -> Developer Options, and under the Drawing section, switch all of the following options:

Window animation scale -> off
Transition animation scale -> off
Animator duration scale -> off

Create a new Android Studio Android Instrumented Test Build configuration using the following steps.

Run instrumentation-tests skipped on browserstack

cd commcare-android
./gradlew connectedCommcareDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.notAnnotation=org.commcare.annotations.BrowserstackTests

Code Style Settings

In order to comply with code style guidelines we follow, please use Commcare Coding Style file and Commcare Inspection Profile as your respective code style and inpection profile in Android Studio. To do so follow these instructions

  1. Copy the config files to your Android Studio installation as follows (Replace AndroidStudio3.0 with the respective directory for the AS version you are using) -
cp .android_studio_settings/inspection/CommCare\ Inpsection\ Profile.xml ~/Library/Preferences/AndroidStudio3.0/inspection/.

cp .android_studio_settings/codestyles/CommCare\ Coding\ Style.xml ~/Library/Preferences/AndroidStudio3.0/codestyles/.

  1. Restart Android Studio

  2. Go to AS preferences -> Editor -> Code Style and select Scheme as 'Commcare Coding Style' and to AS preferences -> Editor -> Inspections and select Profile as 'Commcare Inspection Profile'

Common Errors

If you experience the following exception when running individual tests from Android Studio Editor on Mac

No such manifest file: build/intermediates/bundles/debug/AndroidManifest.xml

If you are on a Mac, you will probably need to configure the default JUnit test runner configuration in order to work around a bug where IntelliJ / Android Studio does not set the working directory to the module being tested. This can be accomplished by editing the run configurations, Defaults -> JUnit and changing the working directory value to $MODULE_DIR$

Error on attempt to install CommCare app on phone: Unknown failure during app install

Android Monitor in Android Studio shows the following exceptions:

java.lang.RuntimeException: CommCare ran into an issue deserializing data while inflating type
    ...
Caused by: org.javarosa.core.util.externalizable.DeserializationException:
No datatype registered to serialization code [4b a9 e5 89]

Resolution: