cli-anything-krita 测试体系全解析从核心模块单元测试到真实 Krita 端到端验证【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本文以 krita 测试计划文档 为主线系统拆解 cli-anything-kritaCLI-Anything 生态中面向开源绘画软件 Krita 的命令行 Agent 适配层的分层测试方案test_core.py的纯数据单元测试、test_full_e2e.py的.kra生成与 CLI 子进程端到端测试并结合 core/project.py、core/session.py、core/export.py 等源码讲解被测对象与验证原理。读完本文你将掌握这套测试如何在不依赖图形界面的前提下验证项目创建 → 图层管理 → 滤镜 → 会话撤销/重做 → KRA 导出的完整 Agent 调用链以及如何把 45 个通过用例映射回真实功能实现。一、测试清单与分层策略TEST.md 的 Part 1 给出了两份测试文件的分工其被测对象覆盖了 krita_cli.py 暴露的全部命令组所对应的核心模块测试文件规模定位依赖test_core.py规划约 40 个用例实际落地 36 个纯逻辑单元测试使用合成数据无外部依赖不要求安装 Kritatest_full_e2e.py规划约 20 个用例端到端验证含真实 Krita 导出与子进程测试必须安装 Krita无降级容错需要特别说明的是test_core.py的文件头明确写了一句All tests use synthetic data — no external dependencies required这意味着整个核心逻辑项目状态、图层栈、会话快照、.kra打包都被设计为不依赖 Krita 进程的纯 Python 数据流只有真实渲染与命令行安装形态才需要真实环境——这正是 README 的 How it works 所描述架构Project JSON → Build .kra → Krita --export → Output verification的可测试性来源。二、Unit 测试test_core.py四个模块的覆盖分析TEST.md 把单元测试按源码模块分成四组实测每组用例全部通过。下面逐一结合源码说明每类用例验证的真实行为。2.1 project.py项目 JSON 状态机的完整生命周期被测对象是 core/project.py 的 10 个公共函数TEST.md 规划的 16 个用例可归纳为四类创建与默认值校验test_create_project_defaults断言create_project()的默认画布为 1920×1080、色彩空间RGBA、位深U8、分辨率 300、并自动携带一个名为Background的默认 paintlayertest_create_project_custom验证 4096×4096 CMYKAF32等自定义组合。从源码看create_project会对colorspace合法值RGBA/RGB/GRAYA/GRAY/CMYKA/CMYK、depthU8/U16/F16/F32、宽高与分辨率做参数校验并抛出带合法清单的ValueError。持久化往返test_save_and_open_project验证save_project→open_project的 round-trip。源码中save_project默认落盘为项目名.krita.json并写入 ISO-8601 的modified时间戳写入通过 utils/io.py 的locked_save_json完成——该函数在 Unix 上用fcntl.flock加排它锁实现原子写保证多进程/多 Agent 并发时不产生半截 JSONopen_project则只做含 version 与 canvas 字段的轻量 sanity check。图层栈增删改查test_add_layer_paintlayer/test_add_layer_grouplayer/test_add_layer_all_types覆盖 7 种合法图层类型paintlayer、grouplayer、vectorlayer、filterlayer、filllayer、clonelayer、filelayertest_remove_layer与test_remove_layer_not_found验证按名删除及删除不存在图层时抛出KeyErrortest_list_layers验证返回结构与堆栈顺序test_set_layer_property_opacity/visible/blending验证set_layer_property能改 opacity0–255 范围校验、可见性与混合模式。源码中add_layer还会拒绝重名图层。滤镜与画布test_add_filter/test_add_filter_with_config验证add_filter只接受VALID_FILTERS白名单中的 23 种滤镜blur、gaussian-blur、unsharp-mask、levels、curves、hue-saturation、emboss、halftone 等并把{name: ..., config: ...}追加到目标图层test_set_canvas与test_set_canvas_partial验证set_canvas仅更新传入字段部分更新特性后者是该组规划外新增的用例。2.2 session.py可持久化的撤销/重做历史core/session.py 的Session类用_snapshots列表 _current游标实现多级快照历史TEST.md 的 10 个用例基本逐条验证其语义test_session_snapshotsnapshot()深拷贝项目状态copy.deepcopy并追加时间戳与标签test_session_undo/test_session_redo验证指针前移/后移并返回恢复后的项目深拷贝test_session_undo_at_start/test_session_redo_at_end历史边界返回None对应 CLI 输出的nothing_to_undo/nothing_to_redotest_session_branch_discards_redo这是最关键的语义测试——undo 到中间位置后新建快照时snapshot()会先截断_current之后的全部 redo 状态代码中self._snapshots self._snapshots[:self._current 1]测试断言此后redo()返回None且历史长度收缩test_session_history返回{index, timestamp, label}元数据序列test_session_save_loadsave()把current游标与全部快照写入 JSON同样走locked_save_jsonload()还原后可继续 undo/redotest_session_clear清空全部快照并复位游标到 -1test_session_can_undo_redo布尔状态与历史位置的对应关系。这套机制在 CLI 层的落点是 krita_cli.py 的session undo/redo/history命令与status中的can_undo/can_redo输出。2.3 export.py.kra结构与导出预设计test_list_presets、test_get_supported_formats、test_export_presets_keys验证 core/export.py 中 14 个EXPORT_PRESETSpng、png-web、jpeg、jpeg-web、jpeg-low、tiff、tiff-lzw、psd、pdf、svg、webp、gif、bmp均包含extension/description等必需键格式去重后覆盖bmp/gif/jpg/pdf/png/psd/svg/tiff/webp。后三个用例直接验证.kra容器合规性。.kra本质是 ZIP 归档build_kra_from_project 用zipfile.ZIP_STORED不压缩写入结构test_kra_has_mimetype断言mimetype条目存在且内容为application/x-kra——依据 Krita/OpenDocument 惯例该条目必须是归档第一个且不压缩的文件这是TestKRAGeneration::test_create_project_add_layers_export_kra中names[0] mimetype进一步锁死的硬性要求test_kra_has_maindoc校验maindoc.xml存在且包含 Krita 命名空间http://www.calligra.org/DTD/krita、IMAGE的画布宽高/色彩空间/分辨率及 paintlayer 的visible、opacity、filename、uuid等属性test_kra_has_documentinfo校验documentinfo.xml携带 Dublin Core 的 title/creator/date 元数据。每个 paintlayer 还会在image_name/layers/安全文件名下写入一张由_make_blank_png手工构造含正确 IHDR/IDAT/IEND chunk 与 CRC的全透明 RGBA PNG测试通过zipfile.namelist()与魔数逐一验证。2.4 krita_backend.py真实可执行文件的发现与版本探测test_find_krita与test_get_version位于文件末尾的TestKritaBackend它们验证 utils/krita_backend.py 的四级搜索链KRITA_PATH环境变量显式覆盖 → PATH 上的krita/krita.exe→ Windows 常见安装目录C:/Program Files/Krita*/bin/...glob 排序取最新版→ macOS 的/Applications/krita.app/Contents/MacOS/krita。找不到时抛出的RuntimeError会携带_INSTALL_INSTRUCTIONS中的三平台安装指引。get_version解析krita --version首行取版本号如5.2.2。三、E2E 测试test_full_e2e.py的三级端到端验证TEST.md 的 E2E 规划与结果把真实环境验证切成三个递进层次源码见 test_full_e2e.py3.1 Full PipelineKRA 生成全链路TestKRAGeneration不调用 GUI只验证代码生成文档这条主链路test_create_project_add_layers_export_kra创建 1024×768 项目 → 追加 3 个图层 →build_kra_from_project产出.kra再解包核对mimetype为首条目且内容正确、maindoc.xml/documentinfo.xml齐备、文件体积大于 100 字节test_rich_project_kra基于 rich fixtureSketch/Colors/Effects 三层Effects 挂一个 radius3 的 blur 滤镜验证maindoc.xml能反映图层引用。3.2 CLI Subprocess安装形态下的命令行为TestCLISubprocess通过subprocess.run调用真实命令验证 CLI 作为安装命令可正常工作。其_resolve_cli辅助函数优先解析 PATH 中的cli-anything-krita找不到则回退到python -m cli_anything.krita.krita_cli开发模式并支持CLI_ANYTHING_FORCE_INSTALLED1强制要求安装形态。最终结果清单中的 7 个用例覆盖test_help--help返回 0 且输出含 kritatest_project_new_json--json project new -n SubTest -o test.json的 stdout 可被json.loads解析出statuscreated且文件真实落盘test_layer_workflowlayer add两次后layer list的 JSON 应为 3 层Background Sketch Colorstest_export_presets/test_filter_listexport presets与filter list的输出可解析且非空test_status状态结构包含project_loaded等字段test_full_workflow完整串起project new(512×512)→ 加层 →filter apply blur→project info断言layer_count 3→canvas resize 1024×1024→canvas info与下文真实场景严格对应。值得注意子进程测试通常用--json全局开关与--project/-p全局项目参数驱动依赖 krita_cli.py 中cli根命令的ctx.call_on_close自动保存机制dry-run 时跳过保存与_output的 JSON/人类可读双格式输出。3.3 Real Krita Export真实渲染边界TestRealKritaExport用真实 Krita 二进制执行krita --export --export-filename out in.kra并通过 PNG 魔数\x89PNG与 JPEG 魔数\xff\xd8校验产物真实性。它的跳过条件很能说明问题无头导出在 Windows 上需要显示服务器/虚拟显示测试注释与 Coverage Notes 明确指出这两例在 Windows 上 SKIPPEDKrita headless requires display而在带 Xvfb 的 Linux 上可通过——详见下文结果解读。四、现实工作流场景测试计划的验收用例TEST.md 在测试规划末尾列出 4 个贴近真实使用的工作流验收场景它们在仓库代码中均有对应的 CLI 实现可视为对单元与 E2E 测试的验收汇总数字绘画搭台Digital Painting Setup建画布 → 依次建立 Background / Sketch / Colors / Details 图层 → 分层调 opacity → 导出 PNG。对应layer add -t paintlayer --opacity N与export render out.png -p png照片修图管线Photo Editing Pipeline打开已有项目 → 添加调整图层 → 叠加 levels、hue-saturation 等滤镜 → 导出 JPEG。对应project openfilter apply levels/hue-saturationexport render out.jpg -p jpeg动画帧序列导出Animation Frame Export建项目、铺图层后导出帧序列。对应 CLI 的export animation dir -p png --basename frame底层调用 krita_backend.export_animation拼装--export-sequence/--export-filename/--export-sequence-start/--export-sequence-end参数并以frame*.pngglob 收集产物撤销/重做压力测试Undo/Redo Stress Test多操作 undo/redo 分支切换对应session snapshot/undo/redo/history命令组与 2.2 节的快照分支语义。五、测试结果解读与覆盖率说明TEST.md 的 Part 2 记录了最近一次运行2026-03-22的完整结果输出结论如下Summary: 45 passed, 2 skipped in 23.04s按模块拆分与 TEST.md 的 Coverage Notes 交叉核对分组结果说明单元测试TestProject17 TestSession10 TestExport7 TestKritaBackend236 passedproject、session、export、backend 四模块全覆盖纯合成数据、无外部依赖KRA 生成全链路TestKRAGeneration2 passedmimetype/maindoc.xml/documentinfo.xml 结构与顺序均正确CLI 子进程TestCLISubprocess7 passed命令以安装形态工作正常真实 Krita 导出TestRealKritaExport2 skippedtest_export_png与test_export_jpeg在无头 Windows 下需要显示服务在带 Xvfb 的 Linux 环境可正常通过45 36 2 7 恰好对上总计数被跳过的 2 例并不代表功能缺失而是运行环境决定测试边界的典型示例——文档给出的规避办法是在 Linux 上配合 Xvfb 虚拟显示运行这也为 CI 环境配置如 GitHub Actions xvfb-run提供了直接依据。六、如何在本仓库复现这套测试test_core 与 test_full_e2e 均位于 krita/agent-harness/cli_anything/krita/tests/ 目录安装与运行方式为cd krita/agent-harness pip install -e . cd cli_anything/krita/tests pytest test_core.py # 36 个单元用例无需安装 Krita pytest test_full_e2e.py # 需真实 Krita含子进程与渲染用例 pytest test_core.py test_full_e2e.py -v # 复现 TEST.md 中的完整运行前置条件与 krita/agent-harness 内模块 README 一致Python 3.10Krita 需按平台安装Windows 下载安装包、macOSbrew install --cask krita、Linuxsudo apt install krita或 Flatpakorg.kde.krita。若机器只装有 Krita 但没有图形会话如 CI可参考测试结果一节用 Xvfb 提供虚拟显示以解除两个真实导出用例的跳过。结语测试即文档的 Agent 时代实践通过 TEST.md 与源码的对照可以确认cli-anything-krita 的测试设计遵循一条清晰原则把与 Krita 无关的纯逻辑状态、会话、打包与强依赖真实二进制的渲染彻底分层前者用 36 个合成数据用例做到毫秒级全覆盖后者用端到端用例守住产出的.kra/PNG/JPEG 是真实 Krita 可接受、结构完全合规的文件这条底线。对于想要为 Agent 化工具链引入类似 CLI 适配层的开发者这套单元测试保逻辑、子进程测安装形态、真实二进制守渲染边界、工作流场景做验收的四层测试清单本身就是一份可复用的工程范式。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考