An Android application for calculating the distance between two railway stations. It calculates the distance between selected stations and utilizes the Google Maps API for data visualization on the map. The application is written in Kotlin and uses the latest practices and tools from the Android ecosystem.
- Searching for railway stations by name.
- Calculating the distance between selected stations.
- Displaying results on the map.
The application utilizes the following technologies and libraries:
- Kotlin
- Android Jetpack (Compose, ViewModel, Flow, Room) - Room is used to store data about stations and distances locally on the device, allowing for fast access and operations even without network access.
- Google Maps API
- Retrofit - for API communication
- Koin - as a dependency management system
- Coroutines - for asynchronous operation handling
- JUnit, MockK - for testing
- and others full list
To run the application, you have two options:
To run the application, you need a Google Maps API key. Obtain it from Create API keys and add it to the local.defaults.properties
file by replacing MAPS_API_KEY=DEFAULT_API_KEY
with your own API key.
You can download the latest APK version from the Releases section in the GitHub repository and install it directly on your Android device.
The application leverages JUnit5 and MockK for unit testing, focusing on the business logic to ensure the components of the application function correctly without the need for running an Android environment.
To run the unit tests, a JDK environment is required (version 17 is recommended) along with Gradle.
Unit tests can be run directly from Android Studio or via the command line. Instructions for both methods are provided below:
- Open the test class, e.g.,
StationSpanRepositoryTest
, in Android Studio. - Right-click on the class name or a specific test and select
Run 'StationSpanRepositoryTest'
orRun 'testName'
.
- Open a terminal in the root directory of the project.
- Execute the following command to run all unit tests:
./gradlew test
The application utilizes Android Jetpack Compose for building its user interface and the androidx.compose.ui.test
library for testing these UI components. UI tests focus on verifying user interactions with the application, such as searching for stations and calculating and displaying the distance between selected stations.
To run the UI tests, you will need:
- Android Studio environment with Android SDK installed.
- An Android Emulator installed and configured or a physical device connected.
UI tests can be run directly from Android Studio or using the command line. Below are the instructions for both methods:
- Open the test class
StationSearchDistanceTest
in Android Studio. - Right-click on the class name or a test method and select
Run 'StationSearchDistanceTest'
orRun 'testSearchAndDisplayDistanceBetweenStations'
.
- Open a terminal in the root directory of the project.
- Execute the following command to run all UI tests:
./gradlew connectedAndroidTest
The project uses GitHub Actions for automatically running unit tests for every pull request to the main
and dev
branches.
The CI process consists of the following steps:
- Check out code: Clones the repository for running GitHub actions.
- Install Unzip: Prepares the environment by installing necessary tools.
- Set up JDK 17: Configures Java Development Kit 17 for building Android projects.
- Set up Android SDK: Prepares the Android SDK environment for building and testing the application.
- Grant execute permission for gradlew: Ensures the Gradle wrapper script is executable.
- Run Check: Executes the
./gradlew check
command, which runs all configured checks, such as unit tests.
The workflow is defined in the .github/workflows
directory of the repository and is triggered for every pull request to the main
and dev
branches. It runs on a self-hosted runner, ensuring a consistent and controlled testing environment.
The CI process is designed to run on a self-hosted machine, which requires manual configuration. To replicate the CI environment or configure a new self-hosted runner, ensure the following requirements are met:
- Self-Hosted Runner: Follow GitHub's documentation to set up a self-hosted runner.
- JDK 17: Install JDK 17, which is required for building Android projects.
- Android SDK: Install and configure the Android SDK with necessary tools and platforms.
- Environment Variables: Set up any necessary environment variables, such as
ANDROID_HOME
, pointing to the location of the Android SDK.