Automated Testing System

Test Match Mania Across All Android Versions

Zero setup required! Automated testing system with automatic Android SDK installation. Test Match Mania across 5 Android versions with comprehensive UI, gameplay, OTA, and performance testing. Screenshots are automatically captured on errors. Works on Linux, macOS, and Windows.

View Testing Docs Clone Repository

Testing System: v2.0.0 October 2025

Android Versions

API 24 to 33

Test Cases

Comprehensive Coverage

Test Categories

UI, Gameplay, OTA, Performance

100%

Automated

Zero Manual Effort

✨ Key Features

Perfect for contributors who want to ensure their changes work across all supported Android versions

🎯

Zero Setup Required

Automatic Android SDK installation

Auto-detects platform (Linux/macOS/Windows)
Downloads SDK automatically (~460 MB)
Installs essential components
Configures environment variables
Ready to test in 3-5 minutes

🔄

Multi-Version Testing

Test across 5 Android versions automatically

Android 7.0 (API 24) - Nougat
Android 8.0 (API 26) - Oreo
Android 9.0 (API 28) - Pie
Android 11 (API 30) - Current
Android 13 (API 33) - Tiramisu

📱

Comprehensive Tests

19 tests across 4 categories

UI Tests (7 tests)
Gameplay Tests (5 tests)
OTA Tests (4 tests)
Performance Tests (3 tests)

📸

Smart Screenshots

Automatic capture for debugging

Screenshot on every error
Key action captures
Test completion shots
Organized by session

📊

Detailed Reports

Professional HTML reports

Summary statistics
Screenshot gallery
Complete test logs
Pass/fail metrics

🌍

Cross-Platform

Works everywhere out of the box

Linux (all distributions)
macOS (10.15+)
Windows (WSL2/Git Bash)
Platform-specific guidance

🐧 Universal Linux Package Manager Support

Automatic dependency installation across all major Linux distributions!

🎉 Supports 10 Major Package Managers!

The testing system automatically detects your Linux distribution and offers to install all required dependencies (curl, wget, unzip, Java JDK) with a single confirmation. No manual package installation needed!

Debian/Ubuntu Family

apt

Ubuntu
Debian
Linux Mint
Pop!_OS
elementary OS

Red Hat Family

dnf

Fedora
RHEL 8+
CentOS Stream
Rocky Linux
AlmaLinux

yum

CentOS 7
RHEL 7
Oracle Linux 7

Arch Family

pacman

Arch Linux
Manjaro
EndeavourOS
Garuda Linux

SUSE Family

zypper

openSUSE
openSUSE Tumbleweed
SUSE Linux Enterprise

Independent Distributions

apk Alpine Linux

emerge Gentoo

xbps Void Linux

nix NixOS

Universal Package Manager

brew

Homebrew on Linux
Works on any distribution
Cross-distro package manager

⚡ How It Works

Auto-Detection: The script automatically detects your package manager
Dependency Check: Verifies if curl, wget, unzip, and Java JDK are installed
Single Prompt: Asks once if you want to install missing dependencies
Automatic Installation: Runs the appropriate package manager command
Ready to Test: Proceeds with Android SDK installation and testing

~95% Coverage

Covers approximately 95% of all Linux desktop and server installations

Example: Automatic Installation

$ ./install-android-sdk.sh

ℹ Detected platform: linux
ℹ Detected package manager: apt
⚠ Missing required tools: java/jdk

Automatically install missing tools? (Y/n): Y

ℹ Installing required tools...
✓ Tools installed successfully
✓ Android SDK installed successfully!

🚀 Quick Start Guide

Get started with testing in just 3 simple steps - no Android SDK setup required!

🎉 NEW: Automatic Android SDK Installation!

No manual setup required! The testing scripts automatically detect if Android SDK is missing and offer to install it for you. Just run the tests and press Y when prompted.

✅ Linux ✅ macOS ✅ Windows (WSL/Git Bash) ⚡ 3-5 minutes

1 Clone the Repository

git clone https://github.com/ssfdre38/match-mania.git
cd match-mania/emulator-testing

2 Run Tests (Automatic Setup!)

./run-comprehensive-tests.sh

✨ Magic happens here! If Android SDK is not found, the script will automatically:

Detect your platform (Linux/macOS/Windows)
Offer to download and install Android SDK (~150 MB)
Install essential components (platform-tools, emulator)
Download system images (~2-4 GB)
Configure environment variables
Start testing automatically!

⏱️ First-time setup: 3-8 minutes | Testing duration: 50-75 minutes

3 Review Results

# View HTML report (opens automatically)
reports/test_YYYYMMDD_HHMMSS_report.html

# Check screenshots
ls screenshots/

# Review logs
cat logs/test_YYYYMMDD_HHMMSS.log

📊 Professional HTML reports with pass/fail rates, screenshot gallery, and complete logs

💡 Manual SDK Installation (Optional)

Prefer to install Android SDK manually first? Run this command:

./install-android-sdk.sh

This downloads Android SDK (~460 MB total) and configures everything automatically.

📋 What Gets Tested

Comprehensive testing across all aspects of the application

📱

UI Tests

App launch verification
All UI elements check (14 elements)
Portrait layout verification
Landscape layout verification
Screen rotation testing
Button interaction testing
Card interaction testing

🎮

Gameplay Tests

Draw card functionality
Play card functionality
New game button
Game state persistence
AI turn processing

🔄

OTA Tests

Settings accessibility
Check for updates functionality
Version display verification
Update notification system

⚡

Performance Tests

App startup time monitoring
Memory usage tracking
Crash detection

✅ Automatic Error Handling

When any test fails, the system automatically captures a screenshot, logs the error details, and continues with the next test. All errors are included in the final HTML report with linked screenshots for easy debugging.

🔄 Test Execution Flow

Understanding how the automated testing system works

1 Initialize

Create unique test session ID
Setup logging infrastructure
Build APK if needed (auto-detected)
Prepare directories for results

2 For Each Android Version

Create or recreate Android Virtual Device (AVD)
Start emulator with optimized settings
Wait for complete boot (up to 3 minutes)
Install the Match Mania APK
Run complete test suite
Stop and cleanup emulator

⏱️ Duration: ~10-15 minutes per Android version

3 Test Suite Per Version

UI Tests: Verify all elements, layouts, and rotation
Gameplay Tests: Test card drawing, playing, and game flow
OTA Tests: Verify update checking and notifications
Performance Tests: Monitor startup, memory, and crashes

📸 Screenshots captured automatically on any error or at key points

4 Cleanup & Report

Stop all running emulators
Generate professional HTML report
Organize screenshots by test session
Archive complete logs for reference
Open report automatically in browser

Total Testing Time

50-75 minutes

19 tests × 5 Android versions = 95 total test executions

⚙️ Configuration

Easy customization via JSON configuration file

🔢

Android Versions

Enable or disable specific Android versions for testing

{
  "api_level": 30,
  "version": "11",
  "name": "R",
  "enabled": true
}

🎯

Test Categories

Choose which test categories to run

{
  "ui_tests": { "enabled": true },
  "gameplay_tests": { "enabled": true },
  "ota_tests": { "enabled": true }
}

📸

Screenshot Settings

Configure automatic screenshot capture

{
  "error": true,
  "test_end": true,
  "key_actions": true
}

📊 Test Results & Outputs

Professional reports, screenshots, and logs for comprehensive analysis

📄

HTML Reports

Professional test reports with comprehensive statistics

Summary statistics (total/passed/failed/errors)
Pass rate percentage
Screenshot gallery with captions
Complete test log
Timestamp tracking

📂 Location: reports/

📸

Screenshot Gallery

Automatic screenshot capture for debugging

Screenshots on every error
Test completion shots
Key action captures
Organized by test session

📂 Location: screenshots/
Format: {session}_{test}_{reason}_{timestamp}.png

📝

Detailed Logs

Complete test execution logs for analysis

Main test log with all events
Emulator-specific logs
UI hierarchy dumps
Error stack traces

📂 Location: logs/

🔧 Troubleshooting Common Issues

Quick solutions to common problems you might encounter

🔍 Android SDK Not Found

Error: "Android SDK not found!"

Solution: The scripts offer automatic installation! Just press Y when prompted, or manually run:

./install-android-sdk.sh

🖥️ Emulator Won't Start

Common causes and solutions:

Another emulator running: adb emu kill
Linux - KVM not enabled: Check virtualization in BIOS, add user to kvm group
macOS - HAXM not installed: brew install --cask intel-haxm
Windows - WSL1: Upgrade to WSL2 for better emulator support

💿 System Image Missing

Solution: Run the setup script or install manually:

# Automatic (recommended)
./setup-system-images.sh

# Manual
sdkmanager "system-images;android-30;google_apis;x86_64"

🌍 Platform-Specific Issues

🐧 Linux

Install KVM: sudo apt install qemu-kvm
Add user to kvm group: sudo usermod -aG kvm $USER
Log out and back in for group changes to take effect

🍎 macOS

Install HAXM: brew install --cask intel-haxm
Grant Terminal full disk access in System Preferences
System Preferences → Security & Privacy → Privacy → Full Disk Access

🪟 Windows

Use WSL2 (not WSL1) for best emulator support
Use forward slashes in paths: C:/Android/Sdk
Git Bash works but WSL2 is recommended

Still having issues?

Check the complete troubleshooting guide in the README or open an issue on GitHub

Full Guide Report Issue

⭐ Best Practices

Tips for effective testing and quality assurance

🎯

Before Releases

Always run comprehensive tests before releasing new versions

Test on all supported Android versions
Review all screenshots for visual issues
Check test logs for warnings
Verify OTA updates work correctly

🔍

Review Results

Thoroughly analyze test outputs for quality assurance

Check HTML reports for pass rates
Review error screenshots immediately
Monitor performance metrics
Track issues across versions

📦

Maintain Tests

Keep your testing infrastructure up to date

Update system images periodically
Clean old test data (7+ days)
Archive important test reports
Update test cases as features evolve

📚 Documentation

Complete guides and references to help you get started

📖

Full Testing Guide

Complete documentation with examples and troubleshooting tips

View README

🔧

Configuration Reference

Test configuration file with all available options and settings

View Config

💻

Source Code

View and modify the testing scripts for your custom needs

Browse Code

🤝 Contributing

Use this testing system to ensure your changes work correctly before submitting pull requests

Before Submitting a Pull Request

Make your changes to the code
Run the comprehensive test suite
Fix any failing tests
Include test results in your PR description
Add screenshots of any UI changes

View on GitHub Testing Documentation

⚖️ Copyright & Attribution

Match Mania Testing System

License: MIT License

Repository: github.com/ssfdre38/match-mania

Third-Party Software & Tools

This testing system uses the following third-party software. We acknowledge and thank their creators:

Android SDK Tools

License: Android SDK License

Android Emulator
Android Debug Bridge (adb)
SDK Manager & Build Tools
System Images (API 24-33)

View License Terms

Android Open Source Project

License: Apache License 2.0

Components: Android OS System Images

View License

Other Open Source

Trademark Notices

Android™ is a trademark of Google LLC

All other trademarks and registered trademarks are the property of their respective owners.

Disclaimer

This testing system is independent software created for testing the Match Mania application. It is not affiliated with, endorsed by, or sponsored by Google LLC or The Android Open Source Project.

The testing system uses publicly available Android SDK tools in accordance with their respective licenses for the purpose of testing and quality assurance.

📄 Full Copyright Details

For complete copyright and attribution information:

View COPYRIGHT.md

Acknowledgments

We thank the following organizations and communities:

Google LLC for providing the Android SDK and development tools
The Android Open Source Project for the open-source Android platform
Free Software Foundation for GNU utilities and tools
Python Software Foundation for the Python programming language
Open source community for continuous contributions