OpenHarmony 图形像素测试 Skill

OpenHarmony 图形像素测试

使用本技能为 OpenHarmony Rosen 图形像素比对框架生成符合仓库风格的 C++ 测试，目标目录通常是 graphic_test/test。

生成用例不只是写一个测试函数。好的结果需要选对测试目录和 RSGraphicTestType，遵循相邻文件风格，正确使用框架生命周期，注册所有需要保活的渲染节点，并在新增 .cpp 时更新 graphic_test/test/BUILD.gn。

关键禁令

不要在 GetRootNode()->AddChild(...)、AddChildToSubWindow(...) 或创建自定义 surface 后忘记 RegisterNode(...)；节点可能提前释放，截图会空白或不稳定。
不要把独立测试误写成 GRAPHIC_TESTS；只有明确需要同一 fixture 的多个 test surface 聚合成一张网格截图时才使用。
不要为普通 graphic test 新建 ohos_unittest target；新增 .cpp 应加入 graphic_test/test/BUILD.gn 里现有的分类 sources 数组。
不要凭空发明 Drawing helper、测试 helper 或 RenderService API；先查相邻文件和 framework 头文件。
不要在自动截图测试里无脑添加 FlushImplicitTransaction 和 sleep；只有手动截图、立即查询渲染结果或相邻测试需要时才添加。
不要使用无法保证存在的图片资源路径；优先复用同目录已有 /data/local/tmp/... 路径，或在代码里生成 PixelMap。

开始步骤

在工作区中定位真实的 graphic_test 根目录。
先读 graphic_test/graphic_test_framework/include/rs_graphic_test.h、rs_graphic_test_ext.h，再读与需求最接近的现有测试文件。
生成前先回答这些检查点：
- Purpose：我要验证哪一个具体渲染行为或截图差异？
- Existing：应该扩展已有测试文件，还是新建一个更合适？
- Type：这个场景对应哪个 RSGraphicTestType 和哪个测试宏？
- Pixels：截图中用什么颜色、图片、边框、网格或边界值让差异可见且稳定？
- Build：如果新增文件，应加入 test/BUILD.gn 的哪个 sources 数组？
确认场景后，只读取本技能中相关的参考文件：
- references/framework-lifecycle.md：框架生命周期、宏、截图、节点生命周期。
- references/test-taxonomy-build.md：测试放置位置和 test/BUILD.gn 更新规则。
- references/code-patterns.md：节点、图片、Canvas、动画、手动截图、子窗口、PixelMap 的惯用写法。
- references/templates.md：紧凑起始模板。
优先沿用本地相邻文件风格。参考文件解释模式；现有代码才是 include、helper 名称和 API 可用性的权威。
至少做文本级检查：宏名、namespace、include、RegisterNode、source list 入口，以及是否存在虚构 API。

生成流程

1. 判断测试归类

根据被测行为选择目录和 RSGraphicTestType：

| 场景 | 常用目录 | 常用类型 | | --- | --- | --- | | 节点外观、背景、前景、几何、内容显示 | rs_display_effect/property_display 或 rs_display_effect/content_display | CONTENT_DISPLAY_TEST | | 动画协议、曲线、自定义 modifier 动画 | rs_display_effect/animation | ANIMATION_TEST | | NG shader/filter/effect/mask/shape 视觉效果 | rs_effect_feature/... | EFFECT_TEST | | PixelMap、font、symbol 等开放能力 API | open_capability/... | 通常是 CONTENT_DISPLAY_TEST，或沿用本地现有类型 | | 脏区、HWC、GPU composer、hybrid render、性能相关渲染 | rs_perform_feature/... | 沿用本地现有类型，常见为 CONTENT_DISPLAY_TEST、GPU_COMPOSER_TEST、HYBRID_RENDER_TEST | | surface capture、screen capture、多屏、无障碍、水印、render group | rs_func_feature/... | 通常是 CONTENT_DISPLAY_TEST | | 框架 surface 行为 | rs_framework/... | 通常是 CONTENT_DISPLAY_TEST | | Effect Kit NDK filter | effect_kit/... | EFFECT_TEST |

如果已有相关文件，优先扩展该文件；只有当新功能边界清晰、追加会让旧文件混乱时，才新增文件。

2. 选择测试宏

普通自动截图像素测试使用 GRAPHIC_TEST(TestClass, TYPE, TestName)。
GRAPHIC_TEST(TYPE, TestName) 只适合很小的默认 fixture 测试；真实测试文件多数会定义派生 fixture。
多个测试函数需要拼成同一张网格截图时使用 GRAPHIC_TESTS。保持共享 SetScreenSize，并记住输出文件名不包含单个 test name。
只有当测试必须手动控制截图时机、调用自定义 TestCaseCapture、在 FlushImplicitTransaction 后 sleep，或要避开自动截图时，才使用 GRAPHIC_N_TEST。
除非任务明确涉及录制/回放，否则不要使用 GRAPHIC_D_TEST。当前测试语料主要使用自动和手动测试。

3. 构建 fixture

多数文件使用这种结构：

class ExampleTest : public RSGraphicTest {
public:
    void BeforeEach() override
    {
        SetScreenSize(screenWidth, screenHeight);
    }

private:
    const int screenWidth = 1200;
    const int screenHeight = 2000;
};

只有当测试刻意捕获子区域或全屏显示行为时，才使用 SetSurfaceBounds。涉及特殊显示截图、子窗口、手动截图时，应对照同功能区域已有文件。

4. 创建可见且确定的像素输出

像素比对测试需要清晰、稳定的画面：

除非测试裁剪或越界行为，否则把节点放在配置的屏幕范围内。
参数矩阵使用网格布局：根据 screenWidth、screenHeight、行列计算 sizeX、sizeY、x、y。
使用对比明显的背景、边框、图片内容，让期望差异可见。
测试属性钳制时覆盖边界值：负数、0、中间值、1、大值、非法枚举值等。
如果每个取值应该生成独立图片，用多个 GRAPHIC_TEST；如果取值应该在同一张截图中对比，用单个测试内的网格。

5. 正确添加并保活节点

每个加入场景并需要渲染的节点都应这样处理：

GetRootNode()->AddChild(testNode);
RegisterNode(testNode);

对于父子节点树，如果父节点或子节点的局部变量可能离开作用域，父子都要注册。对于子窗口，通过 GetRootNode()->AddChildToSubWindow(subId, node) 添加，并仍然调用 RegisterNode(node)。

6. 只在必要时 flush

自动测试通常依赖 TearDown() 统一 flush 和截图。当测试需要立即查询渲染结果、手动截图、提交节点后调用 surface/PixelMap API，或相邻测试已经采用显式提交模式时，再添加 RSTransactionProxy::GetInstance()->FlushImplicitTransaction()。

使用 FlushImplicitTransaction 时，需要 include transaction/rs_interfaces.h。

7. 新增文件时更新 BUILD.gn

新增 .cpp 时，必须更新 graphic_test/test/BUILD.gn，把相对路径插入匹配的 sources 数组，例如 rs_display_effect_sources、rs_effect_feature_sources、open_capability_sources、rs_func_feature_sources、rs_perform_feature_sources、rs_framework_sources 或 effect_kit_sources。

普通 graphic test 不要新建 ohos_unittest target。现有 RSGraphicTest target 已经汇总各分类 sources 数组。

完成前必要检查

声称完成前，至少运行快速文本检查：

rg -n "GRAPHIC_(N_)?TESTS?|RegisterNode|FlushImplicitTransaction" path/to/new_or_changed.cpp
rg -n "relative/path/to/new_file.cpp" graphic_test/test/BUILD.gn

然后确认：

文件有与相邻测试一致的 Apache copyright header。
include 与实际 API 使用匹配，没有残留模板垃圾。
代码位于 namespace OHOS::Rosen。
每个测试宏都使用正确 fixture、类型和唯一测试名。
每个需要渲染的场景节点都已加入 root 或 sub-window，并调用 RegisterNode。
手动截图测试在 flush/wait 后调用截图 helper，并使用 GRAPHIC_N_TEST。
新文件已加入正确的 source array。
没有残留占位调用，例如 DrawTextBlob(...)、paintSetColor 或虚构 helper 名称。

常见失败模式

| 失败现象 | 原因 | 修复 | | --- | --- | --- | | 截图空白 | 节点未添加、未注册或没有可见属性 | 添加 child，调用 RegisterNode，设置可见 bounds/color/image | | Drawing 代码编译失败 | 使用了泛化 Drawing API 签名，没有贴合本地风格 | 查看相邻 Drawing 测试，使用 Brush/Pen 和 AttachBrush/DetachBrush | | 测试未参与构建 | 新 .cpp 没加到 test/BUILD.gn 分类数组 | 把相对路径加入正确 sources list | | 输出分组错误 | 独立用例误用了 GRAPHIC_TESTS | 除非明确需要网格聚合，否则使用 GRAPHIC_TEST | | 自动截图前特殊查询存在竞态 | 查询渲染输出前没有提交事务 | 添加 FlushImplicitTransaction，并参考相邻测试的等待模式 | | 依赖资源的测试渲染为空 | 设备上缺少图片路径 | 复用同目录已有 /data/local/tmp/... 路径，或在代码中生成 PixelMap 数据 |

当前语料特点

当前 graphic_test/test 以 GRAPHIC_TEST 自动截图为主；GRAPHIC_N_TEST 大量用于脏区、surface、screen、水印和手动截图流程。GRAPHIC_TESTS 主要出现在 test_template 风格的网格聚合场景，应谨慎选择。

多数视觉属性测试不会在 C++ 中断言像素值，而是创建确定性的渲染场景，由框架把 PNG 保存到 /data/local/graphic_test/... 后再做比对。

Agent Skills: OpenHarmony 图形像素测试

Install this agent skill to your local

Skill Files