organicmaps/organicmaps

Fork 18

[android] Automatized app screenshot generator for app stores #7350

New issue

Open

opened 2024-02-10 10:29:38 +00:00 by rtsisyk · 1 comment

rtsisyk commented

2024-02-10 10:29:38 +00:00

Owner

This ticket is a part of the bounty program. Fair remuneration will be awarded for the time and efforts spent on the implementation of this project. See details below.

OBJECTIVE

The task is to implement an automated screenshot generator for the Android application. The generator shall produce UI screenshots of an Android app while performing a pre-defined set of operations and test scenarios under specific system settings. Generated screenshots will be used in Google Play and other stores to demonstrate the functionality of the app.

USE-CASES

The implemented screenshot generator will be executed on a Mac or Linux laptop on a periodic basis to actualize app screenshots in Google Play and other stores for all supported locales/countries.

FUNCTIONAL REQUIREMENTS

CONFIGURATION

The implementation shall support automated generation of screenshots for all combinations of defined test cases, devices, and locales.

TEST CASES

The implementation shall provide a declarative way of defining the list of test cases in a configuration file or in a separate code file. Each test case shall be defined by UI operations with parameters, system theme, and screen orientation.

UI Operation: Route Planning

Plan a $type (pedestrian, car, cycling) route from $start_lat, $start_lon to $end_lat, $end_lon. Set the viewport to $lat, $lon with $zoom. Make a screenshot.

Example:

Start the $type (pedestrian, car, cycling) navigation from $start_lat, $start_lon to $end_lat, $end_lon. Set the current location to $lat, $lon with $zoom. Make a screenshot.

Example:

UI Operations: Map Browsing

Add bookmarks from the list of $lat, $lon coordinates. Set the viewport to $lat, $lon and zoom $zoom. Click on the bookmark #$n from the list to open the place information page. Make a screenshot.

Example:

Add a set of bookmarks (saved placed) to the map using the list of

UI Operations: Map Search

Start the search for $query in $lat, $lon viewport with $zoom. Make a screenshot.

Example:

System Theme

For each test case, the option to select either a light or dark theme must be available.

Screen Orientation

For each test case, the option to select portrait or landscape mode must be available.

LOCALES

The implementation shall generate screenshots for all the locales supported by the app.

DEVICES

The implementation shall use Android emulators to generator screenshots. The implementation should provide an automation (e.g., a script) to create and launch Android emulators with pre-defined settings, like model, screen size, disk size and others. The following 3 form-factors must be supported:

Phone
7-inch tablet
10-inch large-tablet

PROCESSING

Additional processing of screenshots, like rotating, adding frames, drawing graphics, putting texts is out of the scope of this project.

INTEGRATIONS

Automatic uploading of screenshots to Google Play and other stores is out of the scope of this project.

OUTPUTS

The implementation must generate screenshots in JPEG format with the best resolution/dimensions supported by Google Play. Files must be saved into the following directory structure:

android
├── en-US # locale
│   └── graphics
│       ├── large-tablet-screenshots # device
│       │   ├── 1.jpg # test case 1
│       │   ├── 2.jpg # test case 2
│       │   ├── 3.jpg # test case 3
│       │   ├── 4.jpg
│       │   ├── 5.jpg
│       │   ├── 6.jpg
│       │   ├── 7.jpg
│       │   └── 8.jpg
│       ├── phone-screenshots # device
│       │   ├── 1.jpg
│       │   ├── 2.jpg
│       │   ├── 3.jpg
│       │   └── 4.jpg
│       └── tablet-screenshots # device
│           ├── 1.jpg
│           ├── 2.jpg
│           ├── 3.jpg
│           ├── 4.jpg
│           ├── 5.jpg
│           ├── 6.jpg
│           ├── 7.jpg
│           └── 8.jpg

NON-FUNCTIONAL REQUIREMENTS

AUTOMATION

The screenshot generation process shall be fully automated to work without requiring human interaction while execution. The generation process should work smoothly from start to finish without requiring any manual steps in the middle of the process.

PERFORMANCE

The implementation must be scalable enough to produce at least 100 screenshots per hour on a typical laptop.

PLATFORMS

The implementation must fully support Ubuntu 22.04 and the latest actual version of macOS.

DEPENDENCIES

The implementation must provide all the required instructions and scripts needed for the initial setup and launch of the generator, such as installation of system packages, installation of Android SDK/NDK, Android Studio setup, initial configuration of emulators, etc. The cumulative manual effort to run the generator must not surpass 10 minutes.

DOCUMENTATION

The declarative configuration of test cases must have comments and examples. All configuration options must have descriptions.

ARCHITECTURE

The proposed way is to use Espresso for automating UI test cases and tools.fastlane:screengrab for generating screenshots. If such a design chosen, the entire implementation may be integrated into the main Gradle configuration of Android app.

The alternative way is to automate all things externally by using Android platform tools and app's API for automating UI operations.

THE BOUNTY PROGRAM

Express your interest in this project by providing a free-form proposal in this thread or via hello@organicmaps.app email. Please follow the guidelines of Google Summer of Code on how to write a good proposal. A good proposal may have a delivery plan as well as rough estimations of time and efforts. Proposals with demonstrated a proof-of-concept implementation of UI automation and screenshot capturing will have higher chances of being selected.
Discuss details of your proposal with the mentor of this project (@rtsisyk) via Telegram chat, email, or video call.
Get the greenlight and start working in accordance with the agreed-upon plan.
Receive your bounty.

Proposals will be accepted in the next two weeks. We would like to see this project fully delivered before the end of March.

Upvote & Fund

We're using Polar.sh so you can upvote and help fund this issue.
We receive the funding once the issue is completed & confirmed by you.
Thank you in advance for helping prioritize & fund our backlog.

This ticket is a part of the bounty program. Fair remuneration will be awarded for the time and efforts spent on the implementation of this project. See details below. # OBJECTIVE The task is to implement an automated screenshot generator for the Android application. The generator shall produce UI screenshots of an Android app while performing a pre-defined set of operations and test scenarios under specific system settings. Generated screenshots will be used in Google Play and other stores to demonstrate the functionality of the app. # USE-CASES The implemented screenshot generator will be executed on a Mac or Linux laptop on a periodic basis to actualize app screenshots in Google Play and other stores for all supported locales/countries. # FUNCTIONAL REQUIREMENTS ## CONFIGURATION The implementation shall support automated generation of screenshots for all combinations of defined **test cases**, **devices**, and **locales**. ### TEST CASES The implementation shall provide a declarative way of defining the list of test cases in a configuration file or in a separate code file. Each test case shall be defined by **UI operations with parameters**, **system theme**, and **screen orientation**. #### UI Operation: Route Planning Plan a `$type` (pedestrian, car, cycling) route from `$start_lat`, `$start_lon` to `$end_lat`, `$end_lon`. Set the viewport to `$lat`, `$lon` with `$zoom`. Make a screenshot. Example: <img src="/uploads/d7b88e49ecbe351e2bd69e9a0ed07bb1/bce430e5-0e2f-4aeb-8a05-c7c50d5f2ffb" width="350px"> #### UI Operation: Route Navigation Start the `$type` (pedestrian, car, cycling) navigation from `$start_lat`, `$start_lon` to `$end_lat`, `$end_lon`. Set the current location to $lat, $lon with $zoom. Make a screenshot. Example: <img src="/uploads/f1ee0db380e893f34b37f14d277fb62f/c4b889e1-1d99-467e-a1e6-22ced350e444" width="350px"> #### UI Operations: Map Browsing Add bookmarks from the list of $lat, $lon coordinates. Set the viewport to `$lat`, `$lon` and zoom `$zoom`. Click on the bookmark #$n from the list to open the place information page. Make a screenshot. Example: <img src="/uploads/c4f960d5e94f87a1c373e66a23472112/a593a717-08ad-410c-b79f-28cd0a28007b" width="350px"> Add a set of bookmarks (saved placed) to the map using the list of #### UI Operations: Map Search Start the search for $query in $lat, $lon viewport with $zoom. Make a screenshot. Example: <img src="/uploads/26cfe6e9912375fa7cb3bfa6d3a74815/3b01e078-db49-4f3e-9f2d-fa465c821fed" width="350px"> #### System Theme For each test case, the option to select either a light or dark theme must be available. #### Screen Orientation For each test case, the option to select portrait or landscape mode must be available. ### LOCALES The implementation shall generate screenshots for all the locales supported by the app. ### DEVICES The implementation shall use Android emulators to generator screenshots. The implementation should provide an automation (e.g., a script) to create and launch Android emulators with pre-defined settings, like model, screen size, disk size and others. The following 3 form-factors must be supported: - Phone - 7-inch tablet - 10-inch large-tablet ## PROCESSING Additional processing of screenshots, like rotating, adding frames, drawing graphics, putting texts is **out of the scope** of this project. ## INTEGRATIONS Automatic uploading of screenshots to Google Play and other stores is **out of the scope** of this project. ## OUTPUTS The implementation must generate screenshots in JPEG format with the best resolution/dimensions supported by Google Play. Files must be saved into the following directory structure: ``` android ├── en-US # locale │ └── graphics │ ├── large-tablet-screenshots # device │ │ ├── 1.jpg # test case 1 │ │ ├── 2.jpg # test case 2 │ │ ├── 3.jpg # test case 3 │ │ ├── 4.jpg │ │ ├── 5.jpg │ │ ├── 6.jpg │ │ ├── 7.jpg │ │ └── 8.jpg │ ├── phone-screenshots # device │ │ ├── 1.jpg │ │ ├── 2.jpg │ │ ├── 3.jpg │ │ └── 4.jpg │ └── tablet-screenshots # device │ ├── 1.jpg │ ├── 2.jpg │ ├── 3.jpg │ ├── 4.jpg │ ├── 5.jpg │ ├── 6.jpg │ ├── 7.jpg │ └── 8.jpg ``` # NON-FUNCTIONAL REQUIREMENTS ## AUTOMATION The screenshot generation process shall be fully automated to work without requiring human interaction while execution. The generation process should work smoothly from start to finish without requiring any manual steps in the middle of the process. ## PERFORMANCE The implementation must be scalable enough to produce at least 100 screenshots per hour on a typical laptop. ## PLATFORMS The implementation must fully support Ubuntu 22.04 and the latest actual version of macOS. ## DEPENDENCIES The implementation must provide all the required instructions and scripts needed for the initial setup and launch of the generator, such as installation of system packages, installation of Android SDK/NDK, Android Studio setup, initial configuration of emulators, etc. The cumulative manual effort to run the generator must not surpass 10 minutes. ## DOCUMENTATION The declarative configuration of test cases must have comments and examples. All configuration options must have descriptions. ## ARCHITECTURE The proposed way is to use [Espresso](https://developer.android.com/training/testing/espresso) for automating UI test cases and [`tools.fastlane:screengrab`](https://docs.fastlane.tools/actions/screengrab/) for generating screenshots. If such a design chosen, the entire implementation may be integrated into the main Gradle configuration of Android app. The alternative way is to automate all things externally by using Android platform tools and app's [API](https://omaps.app/test.html) for automating UI operations. # THE BOUNTY PROGRAM 1. Express your interest in this project by providing a free-form proposal in this thread or via hello@organicmaps.app email. Please follow [the guidelines of Google Summer of Code](https://google.github.io/gsocguides/student/writing-a-proposal) on how to write a good proposal. A good proposal may have a delivery plan as well as rough estimations of time and efforts. Proposals with demonstrated a proof-of-concept implementation of UI automation and screenshot capturing will have higher chances of being selected. 2. Discuss details of your proposal with the mentor of this project (`@rtsisyk`) via Telegram chat, email, or video call. 3. Get the greenlight and start working in accordance with the agreed-upon plan. 4. Receive your bounty. Proposals will be accepted in the next two weeks. We would like to see this project fully delivered before the end of March.  ## Upvote & Fund - We're using [Polar.sh](https://polar.sh/organicmaps) so you can upvote and help fund this issue. - We receive the funding once the issue is completed & confirmed by you. - Thank you in advance for helping prioritize & fund our backlog. <a href="https://polar.sh/organicmaps/organicmaps/issues/7350"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://polar.sh/api/github/organicmaps/organicmaps/issues/7350/pledge.svg?darkmode=1"> <img alt="Fund with Polar" src="https://polar.sh/api/github/organicmaps/organicmaps/issues/7350/pledge.svg"> </picture> </a>