Skip to main content

Documentation Index

Fetch the complete documentation index at: https://quashbugs.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Mahoraga setup & calibration

Mahoraga is the execution agent that runs on your Android device or emulator. It detects UI elements, executes test actions, captures screenshots, and reports results back to Quash. This page covers how to set it up and calibrate it for accurate test execution.

​
Installation

Mahoraga installs automatically when you connect a device to Quash:
  • Physical devices — installed on first connection. You will be prompted to allow the installation on your phone.
  • Emulators — pre-installed with permissions granted. No setup needed.
  • Cloud devices — pre-configured. No setup needed.
If Mahoraga does not appear after connecting, disconnect and reconnect the device. Quash will attempt installation again.

​
Accessibility setup (physical devices only)

Emulators and cloud devices come pre-configured — skip this section if you are not using a physical device. Mahoraga needs Android’s accessibility APIs to read UI elements, detect interactive components, perform actions, and capture screen hierarchy. Without accessibility enabled, Quash cannot identify where to tap or read text from the screen. To enable:
  1. Open the Mahoraga app on your device.
  2. Tap Accessibility Service.
  3. You will be redirected to Settings → Accessibility.
  4. Find Mahoraga in the services list and toggle it ON.
  5. Read the permission warning and tap Allow.
Verify it worked: a green checkmark appears next to Accessibility Service in the Mahoraga app. If the toggle will not stay on:
  • Restart the device and try again.
  • Go to Settings → Apps → Mahoraga → Storage → Clear Cache, then retry.
  • Disconnect the device from Quash and reconnect — Quash reinstalls Mahoraga automatically. Redo the accessibility setup.
  • Some manufacturer launchers (particularly MIUI on Xiaomi) block accessibility services. Temporarily switch to the default Android launcher and retry.

​
Bounding box calibration (physical devices only)

Bounding boxes are yellow outlines that show where Mahoraga detects UI elements. On physical devices, screen density differences can cause these to be offset — meaning Mahoraga taps in the wrong location. Emulators and cloud devices rarely need calibration. When to calibrate:
  • First time connecting a physical device
  • After a device software update
  • If tests are tapping wrong locations
How to calibrate:
  1. Open the Mahoraga app on your device.
  2. Toggle Overlay to ON. Yellow bounding boxes appear around UI elements.
  3. Check whether the boxes align with the actual buttons, fields, and text on screen.
  4. If misaligned, use the X/Y offset sliders to adjust:
    • X offset moves boxes left or right.
    • Y offset moves boxes up or down.
    • Start with small adjustments (±5 pixels).
  5. Test by running a simple task with a tap on a known button. If the tap lands correctly, calibration is done.
  6. Toggle Overlay to OFF.
After a device software update, always re-check alignment. OS updates frequently shift the coordinate system, especially on devices with display notches or navigation bar changes. These settings improve test reliability and reduce flakiness. All are in Settings → Developer Options on your Android device.
SettingValueWhy
USB DebuggingONRequired for device connection
Stay AwakeONPrevents screen timeout during tests
Animator Duration ScaleOFF or 0.5xFaster test execution, less waiting for transitions
Transition Animation ScaleOFF or 0.5xSame as above
Window Animation ScaleOFF or 0.5xSame as above
Disabling animations makes tests run 20–30% faster but means tests will not match real user experience. Use this for regression testing. For UX validation, leave animations on. Battery: disable battery optimisation for Mahoraga (Settings → Apps → Mahoraga → Battery → Don’t optimise). This prevents Android from killing Mahoraga during long test runs. Keep physical devices plugged in during testing.

​
Emulator performance

If your emulator is slow, check your AVD settings in Android Studio:
  • RAM: 4GB recommended (minimum 2GB). Do not exceed half your computer’s total RAM.
  • CPU Cores: 4 recommended (minimum 2).
  • Graphics: Hardware (automatic).
  • Boot: Quick Boot saves 30–60 seconds per startup.
For parallel emulators, allocate RAM proportionally: 2 emulators need roughly 8GB available, 4 emulators need 16GB.

​
iOS simulator notes

iOS simulators require minimal configuration. Enable Hardware → Keyboard → Connect Hardware Keyboard for direct typing from your Mac. No accessibility setup, developer options, or calibration is needed.

​
Tips for reliable testing

Pre-grant app permissions. Open your app manually before running tests and grant camera, location, and any other permissions it requests. This prevents permission dialogs from blocking Mahoraga during execution. Disable notifications on the test device. Popup notifications can cover UI elements and cause test failures. Use Do Not Disturb mode during test runs. Disable auto-updates. Unexpected app or OS updates mid-test can change behaviour or interrupt execution. Turn off auto-update in Play Store settings. Label devices clearly in Quash. When running parallel tests across multiple devices, rename them for easy identification — e.g., “Galaxy S21 - Android 13” or “Pixel 5 Emulator - API 33”. This makes device selection and report reading much easier.