首页
/ MaaFramework：智能视觉自动化测试框架实战指南

MaaFramework：智能视觉自动化测试框架实战指南

2026-03-16 03:03:00作者：宗隆裙
MaaFramework
基于图像识别的自动化黑盒测试框架 | A automation black-box testing framework based on image recognition
项目地址：https://gitcode.com/gh_mirrors/ma/MaaFramework

一、核心价值与典型应用场景

在当今软件测试领域，跨平台界面自动化始终是一项挑战。如何让测试脚本在不同设备、不同分辨率下保持稳定运行？如何处理动态界面元素的识别难题？MaaFramework作为一款基于图像识别的自动化黑盒测试框架，为解决这些问题提供了创新方案。

1.1 框架核心价值

MaaFramework的核心价值在于其"视觉智能+模块化架构"的独特组合：

  • 跨平台一致性：一套测试逻辑可在Windows、Android和macOS等多平台运行，解决传统自动化工具的平台碎片化问题
  • 视觉识别优势：无需依赖应用内部接口，通过图像识别实现真正的黑盒测试，适用于无源码或第三方应用场景
  • 灵活扩展机制：支持自定义识别算法和控制单元，满足特定业务场景需求

1.2 三大典型应用场景

移动应用兼容性测试
面对市场上数百种Android设备型号，如何快速验证应用在不同分辨率和系统版本上的表现？MaaFramework通过图像识别技术，实现一套脚本适配多种设备，大幅降低测试成本。

桌面软件自动化操作
企业级桌面应用通常具有复杂的UI交互，传统基于控件的自动化方案维护成本高。MaaFramework提供的视觉识别能力，可直接模拟用户视觉感知进行操作，更贴近真实使用场景。

游戏自动化测试
游戏界面元素丰富多变，传统自动化工具难以应对。MaaFramework的神经网络识别能力，能有效识别游戏角色、道具等动态元素，实现复杂游戏场景的自动化测试。

MaaFramework自动化测试流程

图1：MaaFramework从图像采集到操作执行的完整自动化流程

二、场景化实践指南

2.1 移动应用登录流程自动化

场景挑战
在不同品牌的Android设备上，应用登录界面元素位置可能因屏幕尺寸和分辨率而变化，传统基于坐标的自动化脚本维护困难。

实施步骤

  1. 环境准备

    # 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/ma/MaaFramework
cd MaaFramework

# 下载依赖项
python tools/maadeps-download.py

# 构建项目
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release -j$(nproc)

  2. 创建资源包 组织识别资源目录结构：

    login_test/
├── templates/
│   ├── username_field.png
│   ├── password_field.png
│   └── login_button.png
└── pipeline.json

  3. 编写自动化脚本

    # login_automation.py
import maa
import json
from pathlib import Path

class LoginAutomator:
    def __init__(self, resource_path):
        # 初始化框架
        maa.initialize()
        
        # 创建核心组件
        self.context = maa.Context()
        self.resource = maa.Resource()
        self.controller = maa.Controller()
        self.tasker = maa.Tasker()
        
        # 绑定组件关系
        self.context.bind_resource(self.resource)
        self.context.bind_controller(self.controller)
        self.context.bind_tasker(self.tasker)
        
        # 加载资源
        self.resource.load(resource_path)
    
    def connect_device(self, adb_address):
        """连接Android设备"""
        return self.controller.connect(f"adb://{adb_address}")
    
    def run_login_flow(self, username, password):
        """执行登录流程"""
        # 读取流水线配置
        pipeline_path = Path(__file__).parent / "pipeline.json"
        with open(pipeline_path, "r") as f:
            pipeline = json.load(f)
        
        # 动态替换凭证信息
        for task in pipeline["tasks"]:
            if task["name"] == "输入用户名":
                task["action"]["text"] = username
            elif task["name"] == "输入密码":
                task["action"]["text"] = password
        
        # 执行任务并等待完成
        task_id = self.tasker.append_pipeline(pipeline)
        while not self.tasker.is_task_done(task_id):
            maa.sleep(0.1)
        
        return self.tasker.get_task_result(task_id)
    
    def cleanup(self):
        """清理资源"""
        maa.uninitialize()

if __name__ == "__main__":
    automator = LoginAutomator("path/to/login_test")
    if automator.connect_device("127.0.0.1:5555"):
        success = automator.run_login_flow("test_user", "test_password")
        print(f"登录测试{'成功' if success else '失败'}")
    automator.cleanup()

  4. 定义流水线配置

    // pipeline.json
{
  "version": 2,
  "tasks": [
    {
      "name": "输入用户名",
      "action": {
        "type": "Click",
        "target": {
          "template": "username_field.png",
          "threshold": 0.8
        }
      },
      "post_delay": 300
    },
    {
      "name": "输入用户名",
      "action": {
        "type": "Input",
        "text": "",
        "target": {
          "template": "username_field.png"
        }
      }
    },
    {
      "name": "输入密码",
      "action": {
        "type": "Click",
        "target": {
          "template": "password_field.png",
          "threshold": 0.8
        }
      },
      "post_delay": 300
    },
    {
      "name": "输入密码",
      "action": {
        "type": "Input",
        "text": "",
        "target": {
          "template": "password_field.png"
        }
      }
    },
    {
      "name": "点击登录",
      "action": {
        "type": "Click",
        "target": {
          "template": "login_button.png",
          "threshold": 0.75
        }
      }
    }
  ]
}

效果验证
在至少3种不同分辨率的Android设备上执行脚本，验证登录流程的成功率。使用tools/analyze_log.py分析执行日志，确保平均识别耗时低于300ms，成功率达到95%以上。

2.2 桌面应用界面元素识别

场景挑战
企业级桌面应用通常包含复杂的自定义控件和动态界面元素，传统基于控件ID的识别方式稳定性差，维护成本高。

实施步骤

  1. 创建自定义识别器

    // CustomImageRecognizer.h
#pragma once
#include <MaaFramework/Vision/VisionBase.h>
#include <opencv2/opencv.hpp>

class CustomImageRecognizer : public MaaVision::VisionBase
{
public:
    MaaRectList analyze(const cv::Mat& image) override;
    
    void set_recognize_color(const cv::Scalar& lower, const cv::Scalar& upper)
    {
        lower_color_ = lower;
        upper_color_ = upper;
    }
    
private:
    cv::Scalar lower_color_;
    cv::Scalar upper_color_;
};

  2. 实现识别逻辑

    // CustomImageRecognizer.cpp
#include "CustomImageRecognizer.h"
#include <MaaFramework/Vision/VisionUtils.hpp>

MaaRectList CustomImageRecognizer::analyze(const cv::Mat& image)
{
    MaaRectList result;
    
    // 颜色过滤
    cv::Mat hsv, mask;
    cv::cvtColor(image, hsv, cv::COLOR_BGR2HSV);
    cv::inRange(hsv, lower_color_, upper_color_, mask);
    
    // 查找轮廓
    std::vector<std::vector<cv::Point>> contours;
    cv::findContours(mask, contours, cv::RETR_EXTERNAL, cv::CHAIN_APPROX_SIMPLE);
    
    // 处理轮廓
    for (const auto& contour : contours)
    {
        cv::Rect rect = cv::boundingRect(contour);
        if (rect.area() > 100) // 过滤小区域
        {
            result.emplace_back(MaaRect{
                static_cast<int32_t>(rect.x),
                static_cast<int32_t>(rect.y),
                static_cast<int32_t>(rect.width),
                static_cast<int32_t>(rect.height)
            });
        }
    }
    
    return result;
}

// 注册自定义识别器
REGISTER_VISION(CustomImageRecognizer, "ColorBasedRecognizer")

  3. 集成到自动化流程

    // desktop_automation.cpp
#include <MaaFramework/MaaAPI.h>
#include "CustomImageRecognizer.h"

int main()
{
    // 初始化框架
    MaaInitialize();
    
    // 创建上下文
    MaaContextHandle context = MaaContextCreate(nullptr, nullptr);
    
    // 加载资源
    MaaResourceHandle resource = MaaResourceCreate(nullptr, nullptr);
    MaaResourceLoad(resource, "path/to/resources");
    MaaContextBindResource(context, resource);
    
    // 创建桌面控制器
    MaaControllerHandle controller = MaaControllerCreateForWin32(
        nullptr, nullptr, "窗口标题", 0, 0, 0, 0);
    MaaContextBindController(context, controller);
    
    // 获取自定义识别器
    auto* recognizer = MaaContextGetVision<CustomImageRecognizer>(context, "ColorBasedRecognizer");
    recognizer->set_recognize_color(cv::Scalar(0, 120, 120), cv::Scalar(10, 255, 255)); // 红色范围
    
    // 执行识别
    MaaRectList results = recognizer->analyze(MaaControllerGetImage(controller));
    
    // 处理识别结果
    for (const auto& rect : results)
    {
        // 点击识别到的区域
        MaaControllerClick(controller, rect.x + rect.width / 2, rect.y + rect.height / 2);
        MaaSleep(500);
    }
    
    // 清理资源
    MaaControllerDestroy(controller);
    MaaResourceDestroy(resource);
    MaaContextDestroy(context);
    MaaUninitialize();
    
    return 0;
}

效果验证
在不同窗口大小和主题模式下测试自定义识别器，验证其对目标颜色区域的识别准确率。通过调整颜色阈值参数，使识别准确率达到90%以上，误识率低于5%。

三、问题解决与系统设计

3.1 识别稳定性优化策略

常见陷阱

问题类型 典型原因 优化建议
模板匹配失败 光照条件变化、图像缩放变形 1. 使用多模板匹配
2. 调整匹配阈值
3. 启用图像预处理
识别速度慢 模板数量过多、图像分辨率高 1. 优化图像金字塔层级
2. 减少不必要的模板
3. 启用多线程处理
跨平台兼容性差 不同平台渲染差异 1. 使用相对坐标
2. 增加平台特定模板
3. 调整色彩容忍度

代码优化示例：

// 优化模板匹配性能
void optimize_template_matcher(MaaVision::TemplateMatcher& matcher)
{
    // 设置图像金字塔层级，减少计算量
    matcher.set_pyramid_levels(3);
    
    // 启用边缘检测，提高匹配鲁棒性
    matcher.enable_edge_detection(true);
    
    // 设置多尺度匹配，适应不同缩放比例
    matcher.set_scale_range(0.8, 1.2);
    matcher.set_scale_step(0.1);
    
    // 调整匹配阈值
    matcher.set_threshold(0.75);
}

3.2 大型自动化项目架构设计

模块化设计原则

  1. 资源管理层
    负责模板图片、模型文件等资源的统一管理，实现资源版本控制和动态加载。关键实现可见source/MaaFramework/Resource/ResourceMgr.cpp。

  2. 任务调度层
    基于有限状态机设计，管理复杂任务流程的跳转与依赖关系。核心代码在source/MaaFramework/Tasker/Tasker.cpp。

  3. 设备抽象层
    通过接口抽象不同平台的控制实现，确保上层逻辑与具体设备无关。参考source/MaaFramework/Controller/ControllerAgent.cpp的设计模式。

项目结构示例：

enterprise_automation/
├── config/              # 配置文件
├── resources/           # 识别资源
│   ├── common/          # 通用模板
│   ├── module_a/        # 模块A专用资源
│   └── module_b/        # 模块B专用资源
├── src/
│   ├── tasks/           # 任务定义
│   ├── recognizers/     # 自定义识别器
│   ├── controllers/     # 设备控制扩展
│   └── main.cpp         # 入口程序
└── tests/               # 单元测试

3.3 性能优化与资源管理

内存优化策略

  1. 图像缓存管理
    实现LRU缓存淘汰策略，控制内存占用：

    // [资源缓存管理](https://gitcode.com/gh_mirrors/ma/MaaFramework/blob/b402c73f125dfde0d3c1b25461db116ed9691975/source/MaaFramework/Resource/ResourceMgr.cpp?utm_source=gitcode_repo_files)
void ResourceMgr::optimize_cache()
{
    // 设置缓存上限
    const size_t max_cache_size = 50; // 最多缓存50个图像资源
    
    while (image_cache_.size() > max_cache_size)
    {
        // 移除最久未使用的资源
        auto oldest = image_cache_.begin();
        image_cache_.erase(oldest);
    }
}

  2. 异步资源加载
    使用后台线程预加载即将使用的资源：

    // [异步资源加载](https://gitcode.com/gh_mirrors/ma/MaaFramework/blob/b402c73f125dfde0d3c1b25461db116ed9691975/source/MaaFramework/Resource/ResourceMgr.cpp?utm_source=gitcode_repo_files)
void ResourceMgr::preload_resources(const std::vector<std::string>& resource_ids)
{
    // 使用线程池异步加载资源
    for (const auto& id : resource_ids)
    {
        thread_pool_.enqueue([this, id]() {
            load_resource_sync(id); // 同步加载函数
        });
    }
}

性能监控
集成性能统计工具，监控关键指标：

# tools/performance_analyzer.py
import json
import matplotlib.pyplot as plt

def analyze_performance(log_file):
    """分析执行日志，生成性能报告"""
    with open(log_file, 'r') as f:
        logs = [json.loads(line) for line in f if line.strip()]
    
    # 提取识别耗时数据
    recognition_times = [log['duration'] for log in logs 
                        if log['type'] == 'recognition']
    
    # 计算统计指标
    avg_time = sum(recognition_times) / len(recognition_times)
    max_time = max(recognition_times)
    min_time = min(recognition_times)
    
    # 生成图表
    plt.figure(figsize=(10, 6))
    plt.hist(recognition_times, bins=20)
    plt.title('Recognition Time Distribution')
    plt.xlabel('Time (ms)')
    plt.ylabel('Frequency')
    plt.savefig('performance_report.png')
    
    return {
        'average': avg_time,
        'max': max_time,
        'min': min_time,
        'count': len(recognition_times)
    }

四、总结与展望

MaaFramework通过创新的图像识别技术和灵活的模块化设计，为跨平台自动化测试提供了强大解决方案。无论是移动应用、桌面软件还是游戏测试，都能通过其视觉智能能力实现高效、稳定的自动化测试流程。

随着AI技术的发展，MaaFramework未来将在以下方向持续演进：

  • 增强深度学习模型集成，提升复杂场景识别能力
  • 优化分布式测试架构，支持大规模设备集群管理
  • 完善低代码测试平台，降低自动化测试门槛

通过本文介绍的实践方法和优化策略，开发者可以快速构建高可靠性的自动化测试系统，应对不断变化的软件测试需求，提升产品质量和开发效率。

官方文档：docs/zh_cn/1.1-快速开始.md API参考：include/MaaFramework/MaaAPI.h

MaaFramework
基于图像识别的自动化黑盒测试框架 | A automation black-box testing framework based on image recognition
项目地址：https://gitcode.com/gh_mirrors/ma/MaaFramework
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
27
12
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
600
4.04 K
pytorchpytorch
Ascend Extension for PyTorch
Python
440
531
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
921
769
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
370
250
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.46 K
823
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
112
169
flutter_flutterflutter_flutter
暂无简介
Dart
845
204
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Java
69
21
MindSpeed-LLMMindSpeed-LLM
昇腾LLM分布式训练框架
Python
130
156