AutoControl 是一个跨平台的 Python GUI 自动化框架，提供鼠标控制、键盘输入、图像识别、屏幕捕获、脚本执行与报告生成等功能 — 通过统一的 API 在 Windows、macOS 和 Linux (X11) 上运行。
- 鼠标自动化 — 移动、点击、按下、释放、拖拽、滚动，支持精确坐标控制
- 键盘自动化 — 按下/释放单一按键、输入字符串、组合键、按键状态检测
- 图像识别 — 使用 OpenCV 模板匹配在屏幕上定位 UI 元素，支持可配置的检测阈值
- 截图与屏幕录制 — 捕获全屏或指定区域为图片，录制屏幕为视频（AVI/MP4）
- 动作录制与回放 — 录制鼠标/键盘事件并重新播放
- JSON 脚本执行 — 使用 JSON 动作文件定义并执行自动化流程
- 报告生成 — 将测试记录导出为 HTML、JSON 或 XML 报告，包含成功/失败状态
- 远程自动化 — 启动 TCP Socket 服务器，接收并执行来自远程客户端的自动化命令
- Shell 集成 — 在自动化流程中执行 Shell 命令，支持异步输出捕获
- 回调执行器 — 触发自动化函数后自动调用回调函数，实现操作串联
- 动态包加载 — 在运行时导入外部 Python 包，扩展执行器功能
- 项目与模板管理 — 快速创建包含 keyword/executor 目录结构的自动化项目
- 窗口管理 — 直接将键盘/鼠标事件发送至指定窗口（Windows/Linux）
- GUI 应用程序 — 内置 PySide6 图形界面，支持交互式自动化操作
- 跨平台 — 统一 API，支持 Windows、macOS、Linux（X11）
je_auto_control/
├── wrapper/ # 平台无关 API 层
│ ├── platform_wrapper.py # 自动检测操作系统并加载对应后端
│ ├── auto_control_mouse.py # 鼠标操作
│ ├── auto_control_keyboard.py# 键盘操作
│ ├── auto_control_image.py # 图像识别（OpenCV 模板匹配）
│ ├── auto_control_screen.py # 截图、屏幕大小、像素颜色
│ └── auto_control_record.py # 动作录制/回放
├── windows/ # Windows 专用后端（Win32 API / ctypes）
├── osx/ # macOS 专用后端（pyobjc / Quartz）
├── linux_with_x11/ # Linux 专用后端（python-Xlib）
├── gui/ # PySide6 GUI 应用程序
└── utils/
├── executor/ # JSON 动作执行引擎
├── callback/ # 回调函数执行器
├── cv2_utils/ # OpenCV 截图、模板匹配、视频录制
├── socket_server/ # TCP Socket 服务器（远程自动化）
├── shell_process/ # Shell 命令管理器
├── generate_report/ # HTML / JSON / XML 报告生成器
├── test_record/ # 测试动作记录
├── json/ # JSON 动作文件读写
├── project/ # 项目创建与模板
├── package_manager/ # 动态包加载
├── logging/ # 日志记录
└── exception/ # 自定义异常类
platform_wrapper.py 模块会自动检测当前的操作系统并导入对应的后端，因此所有 wrapper 函数在不同平台上的行为完全一致。
pip install je_auto_controlpip install je_auto_control[gui]在 Linux 上安装前，请先安装以下系统包：
sudo apt-get install cmake libssl-dev- Python >= 3.10
- pip >= 19.3
| 包 | 用途 |
|---|---|
je_open_cv |
图像识别（OpenCV 模板匹配） |
pillow |
截图捕获 |
mss |
快速多屏幕截图 |
pyobjc |
macOS 后端（在 macOS 上自动安装） |
python-Xlib |
Linux X11 后端（在 Linux 上自动安装） |
PySide6 |
GUI 应用程序（可选，使用 [gui] 安装） |
qt-material |
GUI 主题（可选，使用 [gui] 安装） |
import je_auto_control
# 获取当前鼠标位置
x, y = je_auto_control.get_mouse_position()
print(f"鼠标位置: ({x}, {y})")
# 移动鼠标到指定坐标
je_auto_control.set_mouse_position(500, 300)
# 在当前位置左键点击（使用按键名称）
je_auto_control.click_mouse("mouse_left")
# 在指定坐标右键点击
je_auto_control.click_mouse("mouse_right", x=800, y=400)
# 向下滚动
je_auto_control.mouse_scroll(scroll_value=5)import je_auto_control
# 按下并释放单一按键
je_auto_control.type_keyboard("a")
# 逐字输入整个字符串
je_auto_control.write("Hello World")
# 组合键（例如 Ctrl+C）
je_auto_control.hotkey(["ctrl_l", "c"])
# 检查某个按键是否正在被按下
is_pressed = je_auto_control.check_key_is_press("shift_l")import je_auto_control
# 在屏幕上找出所有匹配的图像
positions = je_auto_control.locate_all_image("button.png", detect_threshold=0.9)
# 返回: [[x1, y1, x2, y2], ...]
# 找出单一图像并获取其中心坐标
cx, cy = je_auto_control.locate_image_center("icon.png", detect_threshold=0.85)
print(f"找到位置: ({cx}, {cy})")
# 找出图像并自动点击
je_auto_control.locate_and_click("submit_button.png", mouse_keycode="mouse_left")import je_auto_control
# 捕获全屏截图并保存
je_auto_control.pil_screenshot("screenshot.png")
# 捕获指定区域的截图 [x1, y1, x2, y2]
je_auto_control.pil_screenshot("region.png", screen_region=[100, 100, 500, 400])
# 获取屏幕分辨率
width, height = je_auto_control.screen_size()
# 获取指定坐标的像素颜色
color = je_auto_control.get_pixel(500, 300)import je_auto_control
import time
# 开始录制鼠标和键盘事件
je_auto_control.record()
time.sleep(10) # 录制 10 秒
# 停止录制并获取动作列表
actions = je_auto_control.stop_record()
# 重新播放录制的动作
je_auto_control.execute_action(actions)创建 JSON 动作文件（actions.json）：
[
["AC_set_mouse_position", {"x": 500, "y": 300}],
["AC_click_mouse", {"mouse_keycode": "mouse_left"}],
["AC_write", {"write_string": "Hello from AutoControl"}],
["AC_screenshot", {"file_path": "result.png"}],
["AC_hotkey", {"key_code_list": ["ctrl_l", "s"]}]
]执行方式：
import je_auto_control
# 从文件执行
je_auto_control.execute_action(je_auto_control.read_action_json("actions.json"))
# 或直接从列表执行
je_auto_control.execute_action([
["AC_set_mouse_position", {"x": 100, "y": 200}],
["AC_click_mouse", {"mouse_keycode": "mouse_left"}]
])可用的动作命令：
| 类别 | 命令 |
|---|---|
| 鼠标 | AC_click_mouse, AC_set_mouse_position, AC_get_mouse_position, AC_press_mouse, AC_release_mouse, AC_mouse_scroll, AC_mouse_left, AC_mouse_right, AC_mouse_middle |
| 键盘 | AC_type_keyboard, AC_press_keyboard_key, AC_release_keyboard_key, AC_write, AC_hotkey, AC_check_key_is_press |
| 图像 | AC_locate_all_image, AC_locate_image_center, AC_locate_and_click |
| 屏幕 | AC_screen_size, AC_screenshot |
| 录制 | AC_record, AC_stop_record |
| 报告 | AC_generate_html, AC_generate_json, AC_generate_xml, AC_generate_html_report, AC_generate_json_report, AC_generate_xml_report |
| 项目 | AC_create_project |
| Shell | AC_shell_command |
| 进程 | AC_execute_process |
| 执行器 | AC_execute_action, AC_execute_files |
import je_auto_control
# 先启用测试记录
je_auto_control.test_record_instance.set_record_enable(True)
# ... 执行自动化动作 ...
je_auto_control.set_mouse_position(100, 200)
je_auto_control.click_mouse("mouse_left")
# 生成报告
je_auto_control.generate_html_report("test_report") # -> test_report.html
je_auto_control.generate_json_report("test_report") # -> test_report.json
je_auto_control.generate_xml_report("test_report") # -> test_report.xml
# 或获取报告内容为字符串
html_string = je_auto_control.generate_html()
json_string = je_auto_control.generate_json()
xml_string = je_auto_control.generate_xml()报告内容包含：每个记录动作的函数名称、参数、时间戳及异常信息（如有）。HTML 报告中成功的动作以青色显示，失败的动作以红色显示。
启动 TCP 服务器，接收来自远程客户端的 JSON 自动化命令：
import je_auto_control
# 启动服务器（默认：localhost:9938）
server = je_auto_control.start_autocontrol_socket_server(host="localhost", port=9938)
# 服务器在后台线程中运行
# 通过 TCP 发送 JSON 动作命令即可远程执行
# 发送 "quit_server" 关闭服务器客户端示例：
import socket
import json
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(("localhost", 9938))
# 发送自动化命令
command = json.dumps([
["AC_set_mouse_position", {"x": 500, "y": 300}],
["AC_click_mouse", {"mouse_keycode": "mouse_left"}]
])
sock.sendall(command.encode("utf-8"))
# 接收响应
response = sock.recv(8192).decode("utf-8")
print(response)
sock.close()import je_auto_control
# 使用默认的 Shell 管理器
je_auto_control.default_shell_manager.exec_shell("echo Hello")
je_auto_control.default_shell_manager.pull_text() # 输出捕获的结果
# 或创建自定义的 ShellManager
shell = je_auto_control.ShellManager(shell_encoding="utf-8")
shell.exec_shell("ls -la")
shell.pull_text()
shell.exit_program()import je_auto_control
import time
# 方法一：ScreenRecorder（管理多个录像）
recorder = je_auto_control.ScreenRecorder()
recorder.start_new_record(
recorder_name="my_recording",
path_and_filename="output.avi",
codec="XVID",
frame_per_sec=30,
resolution=(1920, 1080)
)
time.sleep(10)
recorder.stop_record("my_recording")
# 方法二：RecordingThread（简易单一录像，输出 MP4）
recording = je_auto_control.RecordingThread(video_name="my_video", fps=20)
recording.start()
time.sleep(10)
recording.stop()执行自动化函数后自动触发回调函数：
import je_auto_control
def my_callback():
print("动作完成！")
# 执行 set_mouse_position 后调用 my_callback
je_auto_control.callback_executor.callback_function(
trigger_function_name="AC_set_mouse_position",
callback_function=my_callback,
x=500, y=300
)
# 带有参数的回调
def on_done(message):
print(f"完成: {message}")
je_auto_control.callback_executor.callback_function(
trigger_function_name="AC_click_mouse",
callback_function=on_done,
callback_function_param={"message": "点击完成"},
callback_param_method="kwargs",
mouse_keycode="mouse_left"
)在运行时动态加载外部 Python 包到执行器中：
import je_auto_control
# 将包的所有函数/类加入执行器
je_auto_control.package_manager.add_package_to_executor("os")
# 现在可以在 JSON 动作脚本中使用 os 函数：
# ["os_getcwd", {}]
# ["os_listdir", {"path": "."}]快速创建包含模板文件的项目目录结构：
import je_auto_control
# 创建项目结构
je_auto_control.create_project_dir(project_path="./my_project", parent_name="AutoControl")
# 会创建以下结构：
# my_project/
# └── AutoControl/
# ├── keyword/
# │ ├── keyword1.json # 模板动作文件
# │ ├── keyword2.json # 模板动作文件
# │ └── bad_keyword_1.json # 错误处理模板
# └── executor/
# ├── executor_one_file.py # 执行单一文件示例
# ├── executor_folder.py # 执行文件夹示例
# └── executor_bad_file.py # 错误处理示例直接将事件发送至指定窗口（仅限 Windows 和 Linux）：
import je_auto_control
# 通过窗口标题发送键盘事件
je_auto_control.send_key_event_to_window("Notepad", keycode="a")
# 通过窗口 handle 发送鼠标事件
je_auto_control.send_mouse_event_to_window(window_handle, mouse_keycode="mouse_left", x=100, y=50)启动内置图形界面（需安装 [gui] 扩展）：
import je_auto_control
je_auto_control.start_autocontrol_gui()或通过命令行：
python -m je_auto_controlAutoControl 可直接从命令行使用：
# 执行单一动作文件
python -m je_auto_control -e actions.json
# 执行目录中所有动作文件
python -m je_auto_control -d ./action_files/
# 直接执行 JSON 字符串
python -m je_auto_control --execute_str '[["AC_screenshot", {"file_path": "test.png"}]]'
# 创建项目模板
python -m je_auto_control -c ./my_project| 平台 | 状态 | 后端 | 备注 |
|---|---|---|---|
| Windows 10 / 11 | 支持 | Win32 API (ctypes) | 完整功能支持 |
| macOS 10.15+ | 支持 | pyobjc / Quartz | 不支持动作录制；不支持 send_key_event_to_window / send_mouse_event_to_window |
| Linux（X11） | 支持 | python-Xlib | 完整功能支持 |
| Linux（Wayland） | 暂不支持 | — | 未来版本可能加入支持 |
| Raspberry Pi 3B / 4B | 支持 | python-Xlib | 在 X11 上运行 |
git clone https://github.com/Intergration-Automation-Testing/AutoControl.git
cd AutoControl
pip install -r dev_requirements.txt# 单元测试
python -m pytest test/unit_test/
# 集成测试
python -m pytest test/integrated_test/- 主页: https://github.com/Intergration-Automation-Testing/AutoControl
- 文档: https://autocontrol.readthedocs.io/en/latest/
- PyPI: https://pypi.org/project/je_auto_control/
MIT License © JE-Chen