amrka/ultimate-android repository overview

⁠Ultimate android emulator Image

It's a docker image, provides an easy way to have an android emulator working inside a docker container by running few simple commands or by using a simple docker-compose file, the image comes with the latest Android SDK, also the ability to run automation tests against multiple browsers using selenium.

The image is updated regularly every month.

⁠Feature

• Run android emulator in headless or in headed mode (through VNC)
• Support selenium driver, allowing remote execution against browsers
• Support chromedriver/geckodriver
• Support cloning private repository by passing few simple environment variables, allowing execution test inside the docker against browser or android
• Support Appium driver
• Support test execution for Nodejs or Maven projects
• Come with the latest JDK lts.
• Allure report, where you can visualize the report after the test execution

For any issues or questions please open a ticket on the GitHub repo : Github Repo⁠

⁠Setup

⁠Manual execution

Down below is the list of the main scripts to launch the relevant service, certain environment variables should be passed during starting the container.

1. Pull the docker image :

   docker pull amrka/ultimate-android:latest
   

   Copy

2. Start your container:

   docker run -it -d -p 5900:5900 --name androidImage --privileged amrka/ultimate-android    
   

   Copy

3. Launch the appium session :

   docker exec --privileged -it androidImage bash -c "appium -p 5900"
   

   Copy

4. Start the emulator in headless mode :

   docker exec --privileged -it androidImage bash -c "./start_emu_headless.sh"
   

   Copy

5. Cloning your repository (in case of execution inside the container) :

   docker exec --privileged -it androidImage bash -c "./clone_repo.sh"
   docker exec --privileged -it androidImage bash -c "./execute_test.sh"
   

   Copy

6. Starting selenium instance:

   docker exec --privileged -it androidImage bash -c "./clone_repo.sh"
   docker exec --privileged -it androidImage bash -c "./start_selenium.sh"
   

   Copy

7. Starting VNC server:

   docker exec --privileged -it androidImage bash -c "./bootstrap.sh"
   

   Copy

⁠Launch emulator in headed mode

1. You will have to start the docker container by using the following command:

   docker run -it -d -p 5900:5900 --name androidImage -e VNC_PASSWORD=password --privileged amrka/ultimate-android
   

   Copy

2. Instantiate the VNC service by running:

   docker exec --privileged -it androidImage bash -c "./bootstrap.sh"
   

   Copy

3. Connect to the VNC server via remmina or any VNC viewer, on:

   localhost:5900
   

   Copy

4. Open dash terminal in vnc viewer and right the following command:

   #: ./start_emu.sh
   

   Copy

*Note:

• start_emu.sh will launch the emulator in headed mode, so this shell script should not be used for integration with the pipeline (e.g. Jenkins), Use start_emu_headless.sh instead, you can run chrome/firefox in headed mode using vnc terminal as well
• For appium caps default name of the emulator is 'nexus' android 11, for tablet "pixel_c"
• It does not make sense to launch all services in docker-compose, just enable the service you need and comment on the others in the docker-compose file

⁠Cloning a git Repository

In order to clone your repository inside the docker container automatically, you will need to pass the env variables as shown below during container initialization, cloning repository will allow you to run test inside the container against either browsers or emulators using appium, note that relevant services should be triggered according to your need:

• BRANCH: Repository branch name

• GITHUB_USERNAME: GitHub username/Orgnization name

• GITHUB_TOKEN: Github personal token

• REPO_NAME: the exact name of the GitHub repository

• SCRIPT : using this command will allow you to execute certain test command such as "mvn clean test" or "npm run test" note you don't need to run npm I

• REPORT: Name of the reporting service 'only allure for now'

• REPORT_DIR: The expected root directory for allure-results folder, such as './report'

  docker run --privileged -it -d -p 5900:5900 --name androidImage -e BRANCH=win -e GITHUB_USERNAME=amrka -e GITHUB_TOKEN=test -e REPO_NAME=yourRepoName amrka/ultimate-android
  

  Copy

After running the command above you will be able now to run the following command to have your Repository clones in / directory:

docker exec --privileged -it androidImage bash -c "./clone_repo.sh"

Note: You can combine all VNC env var with the env above.

⁠Using Docker-compose

Using the docker-compose file will make initiating the service even easier, docker-compose YAML file provided has several services such as launching emulator with appium instance, starting selenium instance with specific web driver (firefox/chrome), cloning your test automation repo, and executing your test, launching VNC server, it's possible to disable/enable any service based on your need.

docker compose up  >> For mac with latest docker cli
docker-compose up  >> Other OS

⁠Environments

Provide the required Environments during container initializing, in case of manual execution

Check docker-compose file⁠

⁠Kill the container

• Run the following command to kill and remove the container:

  docker rm -f containerName
  

  Copy