MaaXYZ/MaaFramework

基于图像识别的自动化黑盒测试框架 | An automation black-box testing framework based on image recognition

What is MaaFramework?

MaaFramework is an open‑source automation and black‑box testing framework built around image‑recognition. It lets developers write low‑code “pipelines” that watch a screen, recognise UI elements with computer‑vision, and then simulate mouse/keyboard (or touch) actions. The core library is written in modern C++20 and is packaged for many languages (Python, C#, Node, Go, Rust, etc.) and platforms (Windows, Linux, macOS, Android).

Why it matters

  • Image‑based UI automation – instead of needing internal hooks or accessibility APIs, you can control any graphical program (games, apps, web pages) by matching screenshots.
  • Low‑code, high‑extensibility – pipelines are described in a simple declarative format, yet you can plug in custom recognisers, controllers, or data sources.
  • Cross‑language bindings – the same engine can be used from Python, .NET, JavaScript/Node, Go, Rust, etc., making it easy to integrate into existing test suites.
  • Ecosystem – a growing set of community tools (GUIs, debuggers, log analysers, CLI helpers, skill libraries) surrounds the core, so you can build full‑featured bots or test rigs without starting from scratch.

Core concepts (as described in the README)

Concept What it is How you use it
Pipeline A low‑code “recipe” that strings together image‑matching steps, decision logic, and simulated inputs. Write a YAML/JSON file describing the sequence; the framework executes it automatically.
Project Interface (PI) v2 A protocol for packaging a whole automation project (resources, pipelines, configuration). Export or import a PI package to share or version‑control a bot/test suite.
Bindings Language‑specific wrappers (Python maafw, .NET Maa.Framework.Runtimes, Node @maaxyz/maa-node, etc.). Install via pip, NuGet, npm, cargo, or go modules and call the same C++ core from your preferred language.
Community tools GUIs (MFAAvalonia, MFW‑CFA, MXU, MWU), debuggers (MaaDebugger), log analysers (MaaLogAnalyzer, MaaLogs), CLI utilities (maafw‑cli, MaaCtl), and skill libraries for AI agents. Pick the tool that fits your workflow – e.g., use MaaDebugger to step through a pipeline, or MaaLogAnalyzer to visualise execution traces.

Getting started (quick‑start steps from the README)

  1. Visit the website – https://maafw.com/ for richer documentation.
  2. Read the quick‑start guide – docs/zh_cn/1.1-快速开始.md explains installing the language binding you need and running a sample pipeline.
  3. Integrate the library – Follow the integration docs (2.1-集成文档.md) for your language, then explore the API list (2.2-集成接口一览.md).
  4. Write a pipeline – Use the “Pipeline low‑code protocol” (3.1-任务流水线协议.md) to describe the steps your bot should perform.
  5. Explore community extensions – UI front‑ends, debuggers, and skill packs are listed under 社区项目.

Who might use MaaFramework?

Audience Typical use case
Game‑automation developers Build bots for mobile/PC games (e.g., “M9A” for Arknights, “MaaYYs” for Onmyoji) that rely on screen‑scraping and simulated taps.
QA engineers Create black‑box UI tests for applications where source code or accessibility hooks are unavailable.
AI‑agent researchers Use the framework as the “environment” for agents that need visual perception and actuation (e.g., via maafw-cli or MaaEvidenceKit).
Tool builders Develop custom GUIs, debuggers, or CI pipelines that orchestrate MaaFramework pipelines.

Where to find more

  • Source code – https://github.com/MaaXYZ/MaaFramework
  • Package repositories – PyPI (maafw), NuGet, npm (@maaxyz/maa-node), Go (maa-framework-go), crates.io (maa-framework).
  • Community hub – https://hub.maafw.com for shared pipelines, skills, and modules.
  • Documentation – English (README_en.md) and Chinese (README.md) versions, plus the website.

TL;DR

MaaFramework is a C++‑based, cross‑platform automation engine that uses computer‑vision to drive UI interactions. It offers a low‑code pipeline language, many language bindings, and a vibrant ecosystem of GUIs, debuggers, and CLI tools, making it suitable for game bots, UI testing, and AI‑agent environments.

Related

  • Project
    open-daimax/daimax-appbench

    An automated evaluation platform that uses vision models to test, score, and report on the quality of AI-generated applications across web, Android, and iOS platforms.

  • Project
    ok-oldking/ok-script

    ok-script is a Python-based computer vision automation framework that enables developers to create cross-platform scripts for Windows applications, games, and Android devices.

  • Project
    sb-ai-lab/LightAutoML

    An automated machine learning framework that allows users to create ML models via ready-to-use presets or by building custom pipelines for tabular, text, image, and time series data.

  • Project
    chaxiu/munk-ai

    A local-first, self-improving AI testing engine that automates product validation across Android, iOS, and Web by turning natural-language intent into real-device execution.

  • Project
    alicevision/Meshroom

    A node-based visual programming framework for 3D reconstruction and computer vision, enabling users to build complex data processing pipelines using AI and photogrammetry.