MaaFramework: image-recognition black-box automation for app testing
基于图像识别的自动化黑盒测试框架 | An automation black-box testing framework based on image recognition
At a glance
- What is it?
- MaaFramework is a C++20 framework that drives a running application through screenshots and injected input instead of source access. It ships Python, Node.js, Go, Rust and C# bindings, and its Pipeline protocol lets you describe test flows in JSON rather than code.
- Who is it for?
- MaaFramework fits teams that already automate a GUI application and want to move test flows out of imperative code into declarative JSON pipelines, especially when the target runs on Windows, Linux, macOS or Android and cannot be instrumented. It is the wrong tool for unit testing, API testing, or any target whose UI you can call directly, because every assertion goes through a screenshot and a coordinate.
- Can I use it commercially?
- Yes, with conditions. LGPL-3.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What MaaFramework actually automates
MaaFramework targets a specific situation: you have a program you can run but cannot modify or instrument, and you want to verify or drive its behaviour from the outside. The README describes it as an "automation black-box testing framework based on image recognition", a rewrite that distils experience from the MAA project. The unit of work is a screenshot, not a function call.
That constraint decides who benefits. If you can import the code under test, call an API, or query a database, this framework adds latency and flakiness for nothing. It pays off when the target is a compiled desktop application, an Android app, or a game client where the only observable surface is pixels and the only input channel is mouse, keyboard or touch. The repository lists Windows, Linux, macOS and Android as supported platforms, so the same pipeline concept spans desktop and mobile targets.
There is a second audience the README does not stress: people who want to automate an application without writing much code. The Pipeline protocol is JSON, so a tester who can read a screenshot and edit a config file can build a flow. That is a real shift in who can maintain the automation.
Screenshots in, pipeline nodes out: the execution model
The mechanism is a loop. The framework captures the target window or device screen, matches it against recognition rules you declared, and on a match executes the node's action, then moves to the next node. Recognition and action are separate concerns, and both are described in data.
The Pipeline protocol document (docs/zh_cn/3.1-任务流水线协议.md) is the authoritative description of node structure, and the sample directory shows the shape of a project: sample/resource/ holds the assets the pipeline refers to, while sample/python/, sample/nodejs/, sample/cpp/ and sample/csharp/ show the same flow driven from different host languages. This is the part worth understanding before writing anything: the pipeline is the program, and your Python or C# code is the host that starts it and reacts to callbacks.
Because recognition is image-based, the cost model is unusual. A pipeline with many nodes and loose match thresholds will spend most of its time on template matching, and the failure mode is a silent mismatch rather than an exception. The framework gives you a debugger for this: MaaDebugger, listed in the README as the Pipeline debugger, lets you step through nodes and inspect what matched. Treat that tool as part of the framework, not an optional extra.
Installing the bindings and running a first pipeline
The README does not give a single install command. It points to the quick-start document, docs/zh_cn/1.1-快速开始.md, and to the code integration document, docs/zh_cn/2.1-集成文档.md, and both are in Simplified Chinese. The README badges indicate published packages for several ecosystems: MaaFw on PyPI, Maa.Framework.Runtimes on NuGet, @maaxyz/maa-node on npm, github.com/MaaXYZ/maa-framework-go/v3 for Go, and maa-framework on crates.io. Those badge links give the package names, but the README itself does not print an install command, so the exact invocation should come from the package page or from docs/zh_cn/2.1-集成文档.md.
After installation, the integration document is where the actual API lives. A host program typically initialises a controller, loads a resource directory, and posts a pipeline task. The README does not reproduce those calls, so the exact function names should come from docs/zh_cn/2.2-集成接口一览.md rather than from guesswork.
The repository layout tells you what a project needs. Assets and pipeline definitions live under a resource directory, mirroring sample/resource/, and the sample/interface.json file is the project interface descriptor, with sample/interface_zh.json and sample/interface_en.json as its localised variants. If you are building a UI on top of the framework, the ProjectInterfaceV2 protocol document (docs/zh_cn/3.3-ProjectInterfaceV2协议.md) defines that contract, and the community GUIs listed in the README consume it.
A first real use is small on purpose: take sample/resource/ as the starting point, point the host program at it, and run one pipeline node that matches a known screen and clicks a known control. The quick-start document is the only place the README directs a new user to for that first run, and it is in Chinese. An English reader should start with README_en.md and expect to move between the English readme and the Chinese docs.
Where image-based automation breaks down
The honest limitation is the recognition layer itself. Template matching is sensitive to resolution, scaling, theme, language and anti-aliasing. A pipeline tuned on one machine can fail on another with a different DPI setting, and the failure looks like a timeout rather than a clear error. Nothing in the README claims resolution independence.
The second limitation is speed. Every decision costs a screenshot and a match. A flow with dozens of nodes will not run at the speed of a direct API call, and on Android the capture path adds further latency. If your test suite needs to run thousands of cases per commit, this is the wrong layer.
The third is documentation language. The README is bilingual, but the four protocol and integration documents it links to are all under docs/zh_cn/. The English README exists, yet the deep material a developer needs for the Pipeline protocol is Chinese. The README does point to a hosted site at maafw.com and to a DeepWiki page for AI-assisted questions, which may carry translated content, but the repository itself does not promise an English equivalent of those documents.
Finally, the LGPL-3.0 licence is a real constraint for closed-source products. Static linking against an LGPL library is the classic problem case, and the repository does not offer guidance on it.
MaaFramework compared with SikuliX and Appium
SikuliX is the closest conceptual relative: it also drives a GUI through screenshots and image matching, and it is scripted in Python or Ruby rather than configured in JSON. The difference in approach is where the logic lives. SikuliX keeps control flow in your script, so branching, loops and assertions are ordinary code. MaaFramework moves the flow into the Pipeline protocol, a declarative graph of nodes, and the host language only starts tasks and receives callbacks. That is better for non-programmers editing flows and worse for anyone who wants complex conditional logic, since you are expressing it in a config format rather than a language.
Appium is the opposite trade. It drives mobile apps through platform automation APIs, so it can query the accessibility tree and address elements by identifier rather than by pixels. That is far more stable when it is available. MaaFramework is the choice when the accessibility tree is unavailable, unreliable, or when the same pipeline must also cover a desktop target. The README's platform list puts Windows, Linux, macOS and Android under one framework, which Appium does not attempt.
Neither comparison is a verdict. If your target is a standard Android app, Appium will usually be the more maintainable option, and image matching is a fallback rather than a default.
Maintenance, releases and the LGPL-3.0 question
The repository is not archived, and the last push was on 2026-09-15. Releases are frequent: v5.13.0 landed on 2026-09-07, preceded by v5.13.0-beta.6 on 2026-09-02 and v5.13.0-beta.5 on 2026-08-22. That cadence means the beta channel is a real channel, and pinning to a stable tag rather than tracking main is the safer default for a test suite you depend on.
Upgrade cost is concentrated in the Pipeline protocol and the binding APIs. The protocol document is versioned by document name (3.1, 3.3), and the Go module path carries a major version (maa-framework-go/v3), which suggests breaking changes are handled through version bumps rather than silent drift. The README does not document a migration guide or a rollback procedure for a framework upgrade, so a team adopting it should keep its resource directory under version control and test a pipeline against a new release before moving the pin.
The licence is LGPL-3.0, stated in LICENSE.md and shown in the README badge. For a test framework this usually matters less than for a shipped product, because test tooling is often not distributed. It matters a great deal if you embed the framework in a tool you ship to customers. The repository does not give linking guidance, and this article is not legal advice; the concrete step is to check whether your distribution model triggers the LGPL relinking obligation before you build on it.
Editorial conclusion
MaaFramework fits teams that already automate a GUI application and want to move test flows out of imperative code into declarative JSON pipelines, especially when the target runs on Windows, Linux, macOS or Android and cannot be instrumented. It is the wrong tool for unit testing, API testing, or any target whose UI you can call directly, because every assertion goes through a screenshot and a coordinate. Before adopting it, read docs/zh_cn/3.1-任务流水线协议.md end to end, build one pipeline that clicks a button and verifies the next screen, and confirm the LGPL-3.0 obligations against how you plan to distribute the binaries.
Frequently asked questions
Is MaaFramework a framework in the programming sense?
Yes. It is a C++20 library with bindings for Python, Node.js, Go, Rust and C#, and it inverts control: your code starts tasks and receives callbacks while the framework runs the screenshot-and-match loop described by the Pipeline protocol.
What does MaaFramework mean in a project context?
In a project it is the layer that drives a running application from the outside, using image recognition for observation and injected input for actions, with flows declared as JSON pipeline nodes rather than written as imperative test code.
What is the definition of a framework as used here?
The README describes MaaFramework as an automation black-box testing framework based on image recognition, a rewrite that distils experience from the MAA project. The framework supplies the runtime, the recognition engine and the pipeline executor; you supply the resource directory and the host program.
What does a framework mean in business, and does that sense apply to MaaFramework?
The business sense of a framework is a set of agreed practices or structures. MaaFramework is the software sense: a library plus a runtime that your test project is built on top of.
Community notes