From 6f84d6574ab76b1b1a325043f92ba3dd374d7344 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 17:43:59 +0800 Subject: [PATCH] docs: explain visual contracts, mount lifecycle and event test assertions --- src/runtime/endor_host/tests.rs | 133 ++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) diff --git a/src/runtime/endor_host/tests.rs b/src/runtime/endor_host/tests.rs index eebbe1a..e12939c 100644 --- a/src/runtime/endor_host/tests.rs +++ b/src/runtime/endor_host/tests.rs @@ -2830,6 +2830,7 @@ fn source_paint_overrides_native_commands_and_reacts_to_heap_field_writes() { /// paint 尝试写 self.tint,必须在写入前被只读保护拒绝并令会话 fault。 /// 原业务颜色不变,错误展开后宿主可正常直接写属性;另测非法颜色命令的发布拒绝。 fn source_paint_rejects_business_mutation_before_it_happens_and_restores_scope() { + // paint 正在只读范围内执行;夹具尝试修改早已存在的 rect.tint,而非刚创建的绘制结果。 let source = r##"class BadPaint: RectBlock { tint: String function paint(self: BadPaint, mount: Mount, geometry: Bounds): DisplayList { @@ -2840,7 +2841,9 @@ fn source_paint_rejects_business_mutation_before_it_happens_and_restores_scope() rect = BadPaint(100, 40, 0, "#DDEEFF", "#FF0000") page = Page() page.render(rect)"##; + // 先建立会话再执行,错误后仍能检查候选 VM 中的对象与保护范围。 let mut session = ReplSession::new(72).unwrap(); + // 页面加载触发首帧 paint,要求诊断明确来自 read-only 保护。 assert!( session .execute(source, "app.main") @@ -2849,8 +2852,11 @@ fn source_paint_rejects_business_mutation_before_it_happens_and_restores_scope() .to_string() .contains("read-only") ); + // 绘制失败应停止当前运行时;但停止状态不能替代检查写入确实没有发生。 assert!(session.is_faulted()); + // 绕过已停止会话的 execute 入口,直接取原业务对象验证错误后的真实状态。 let globals = session.candidate.globals.unwrap(); + // 全局 rect 应已在 paint 前构造完毕,必须保留其原身份与字段值。 let Value::Object(rect) = session .candidate .vm @@ -2860,15 +2866,18 @@ fn source_paint_rejects_business_mutation_before_it_happens_and_restores_scope() else { panic!("Block") }; + // tint 仍是构造时的红色,说明非法写入在发生前被阻止,而非失败后仅停止后续回调。 assert_eq!( session.candidate.vm.get_attr(rect, "tint").unwrap(), Value::Text("#FF0000".into()) ); + // 宿主直接写字段应恢复为可写,验证异常展开已退出 paint 的只读范围。 session .candidate .vm .set_attr(rect, "tint", Value::Text("#526AC7".into())) .unwrap(); + // 另用独立加载检查无效颜色的命令解码错误,与上面的业务写入拒绝分开覆盖。 let bad_color = include_str!("../../../examples/source-paint.endor").replace("#ED6A5A", "invalid color"); assert!(ReplSession::load(&bad_color, "app.main", 73, 1).is_err()); @@ -2878,13 +2887,19 @@ fn source_paint_rejects_business_mutation_before_it_happens_and_restores_scope() /// 生成 1100 个共享 rect 出现位置,使 Mount 变更通知超过单批容量。 /// 首次仍需完整产出 1100 条命令,随后无变更刷新为 None,避免通知溢出造成永久重绘。 fn source_paint_is_stable_when_mount_notifications_overflow_the_change_batch() { + // 复用源 paint 类与共享 rect 的定义,保留实际依赖读取行为。 let fixture = include_str!("../../../examples/source-paint.endor"); + // 截去原根容器及后续页面代码,随后构造大量共享出现位置。 let mut source = fixture[..fixture.find("root = Column").unwrap()].to_owned(); + // 创建一个无内边距和间距的 Column,使命令数量直接对应共享 rect 的出现次数。 source.push_str("root = Column(0, 0"); + // 1100 次出现使 Mount 通知超过单批容量;每次追加的是同一业务对象引用。 for _ in 0..1100 { source.push_str(", rect"); } + // 补齐页面入口,确保所有出现位置都经过正常挂载和源绘制。 source.push_str(")\npage = Page()\npage.render(root)"); + // 完成初始发布后检查没有遗漏命令,随后无变化刷新应为 None,不能持续误判失效。 let (mut session, document) = ReplSession::load(&source, "app.main", 74, 1).unwrap(); assert_eq!(document.frame.commands.len(), 1100); assert!(session.refresh_document().unwrap().is_none()); @@ -2894,6 +2909,7 @@ fn source_paint_is_stable_when_mount_notifications_overflow_the_change_batch() { /// 检查可选原生构造参数、可变子项和源子类字段在同一构造中的独立分段。 /// 错误类型在分配前拒绝,Block 数量不增;合法回调有效,并逐一验证已公开 UI 方法的 native signature。 fn constructor_options_and_subclass_fields_have_independent_contracts() { + // 加载省略可选原生参数、带源子类字段及可变子项的组合示例,走真实构造入口。 let (mut session, document) = ReplSession::load( include_str!("../../../examples/constructor-contracts.endor"), "app.main", @@ -2901,7 +2917,9 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { 1, ) .unwrap(); + // 文档必须结构有效,再核对字段位置与类型,防止构造参数分段串位。 document.validate().unwrap(); + // 首组逐项读取原生默认值、源字段、事件和列表成员,验证各段参数各归其位。 for (expression, expected) in [ ("rect.width", "180"), ("rect.radius", "0"), @@ -2911,16 +2929,19 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { ("items.count", "2"), ("ui.isInstance(items.at(0), TaggedRect)", "true"), ] { + // 同一会话内查询实际业务值;失败时附表达式,便于定位哪一段构造规则出错。 assert_eq!( session.execute(expression, "app.main").unwrap().value, expected, "{expression}" ); } + // 保存非法构造前的 Block 数量,后面检查类型拒绝是否发生在原生分配副作用之前。 let blocks = session .execute("ui.stats().blocks", "app.main") .unwrap() .value; + // 分别破坏原生参数、可变子项、源子类构造和 Type 参数,要求报告对应契约。 for (expression, expected) in [ ("TaggedRect(\"bad\", 60, \"tag\")", "expects Number"), ("TaggedColumn(0, 0, 7, \"tag\")", "expects Block"), @@ -2929,6 +2950,7 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { ("TaggedEvent(7, \"tag\")", "expects String"), ("ui.isSubtype(7, Block)", "expects Type"), ] { + // 错误调用必须返回 Err;不能靠无输出或错误对象被悄悄忽略来通过。 let error = session .execute(expression, "app.main") .err() @@ -2938,6 +2960,7 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { "{expression}: {error:#}" ); } + // 所有错误尝试结束后,业务 Block 数必须等于基线。 assert_eq!( session .execute("ui.stats().blocks", "app.main") @@ -2945,11 +2968,13 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { .value, blocks ); + // 合法回调继续可用,证明这些参数错误不会把健康会话永久停止。 session.execute("button.click()", "app.main").unwrap(); assert_eq!( session.execute("rect.color", "app.main").unwrap().value, "\"#237A45\"" ); + // 逐个检查公开 UI 入口的 native signature,防止仅部分函数注册了契约元数据。 for name in [ "open", "present", @@ -2972,6 +2997,7 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { "supports", "after", ] { + // 从当前桥接 ui 对象取得真实函数引用,避免验证一份与实际发布函数无关的描述。 let Value::Object(function) = session .candidate .vm @@ -2980,6 +3006,7 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { else { panic!("native Function") }; + // 读取对象存储中绑定到该 native 函数的签名;缺失元数据也必须使测试失败。 let signature = session .candidate .vm @@ -2987,6 +3014,7 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { .native_signature(function) .unwrap() .expect("published UI signature"); + // 使用同一 VM 类型表验证签名引用与结构,确保这些契约可由运行时实际使用。 signature .validate(session.candidate.vm.object_store()) .unwrap(); @@ -2997,8 +3025,11 @@ fn constructor_options_and_subclass_fields_have_independent_contracts() { /// 加载满足参数逆变/返回协变的视觉方法覆盖,验证测量和点击都按动态类型执行。 /// 再分别缩窄参数、放宽返回类型,检查类定义被对应 override 诊断拒绝。 fn source_overrides_accept_wider_inputs_and_more_specific_results() { + // 示例中 WideRect 放宽 measure 参数为 Object,返回更具体的 Sized,保留合法覆写基线。 let source = include_str!("../../../examples/method-contracts.endor"); + // 正常加载时解析覆写契约并执行动态 measure,先确认合法定义可发布。 let (mut session, document) = ReplSession::load(source, "app.main", 164, 1).unwrap(); + // 初始几何通过源 Mount API 读取,不能只凭类定义成功判定动态调用正确。 document.validate().unwrap(); assert_eq!( session @@ -3007,6 +3038,7 @@ fn source_overrides_accept_wider_inputs_and_more_specific_results() { .value, "180" ); + // 通过合法按钮回调改变原矩形宽度,再核对动态测量更新和一次点击计数。 session.execute("button.click()", "app.main").unwrap(); assert_eq!( session @@ -3019,6 +3051,7 @@ fn source_overrides_accept_wider_inputs_and_more_specific_results() { session.execute("count.value", "app.main").unwrap().value, "1" ); + // 从合法程序分别派生“参数变窄”和“返回变宽”,各用独立加载隔离错误。 for (source, reason) in [ ( source.replace("mount: Object", "mount: Point"), @@ -3029,6 +3062,7 @@ fn source_overrides_accept_wider_inputs_and_more_specific_results() { "override widens the return type", ), ] { + // 错误必须指向覆写的方差规则,而不是任意加载失败。 let error = ReplSession::load(&source, "app.main", 165, 1) .err() .expect("invalid override"); @@ -3040,6 +3074,7 @@ fn source_overrides_accept_wider_inputs_and_more_specific_results() { /// 把 Mount/Bounds 的名义类型、事件 Bool|String 选项及可空 Page.window/open 参数串联执行。 /// 合法空值和 union 分支互通,Number 选项则必须以 Bool | String 契约诊断拒绝。 fn nullable_page_methods_union_event_options_and_nominal_mount_bounds_compose() { + // 加载完整视觉协议示例,准备有效矩形、父容器和已打开的页面上下文。 let (mut session, _) = ReplSession::load( include_str!("../../../examples/visual-protocols.endor"), "app.main", @@ -3047,6 +3082,8 @@ fn nullable_page_methods_union_event_options_and_nominal_mount_bounds_compose() 1, ) .unwrap(); + // 按顺序执行:先保存 Mount,再测试 Bounds、联合选项、断连及可空页面窗口。 + // None 表示只要求调用成功;Some 才对序列化后的返回值作精确断言。 for (expression, expected) in [ ("context = rect.mounts().at(0)", None), ("ui.isInstance(context.bounds(), Bounds)", Some("true")), @@ -3063,11 +3100,14 @@ fn nullable_page_methods_union_event_options_and_nominal_mount_bounds_compose() ("page.open(page.window())", None), ("ui.isInstance(page.window(), Window)", Some("true")), ] { + // 各表达式共享前一步建立的 context/listener;顺序是本用例的一部分。 let result = session.execute(expression, "app.main").unwrap(); + // 只比较显式声明的预期值,赋值语句等步骤主要用于建立后续检查条件。 if let Some(expected) = expected { assert_eq!(result.value, expected, "{expression}"); } } + // 数值 7 不属于 Bool | String 的任何分支,注册应给出联合类型诊断。 let error = session .execute("root.on(\"click\", page.close, 7)", "app.main") .err() @@ -3079,6 +3119,7 @@ fn nullable_page_methods_union_event_options_and_nominal_mount_bounds_compose() /// 向 measure/paint、几何方法、resize 和 setColor 传递错误名义类型。 /// 检查每项错误点名所需类型,业务颜色保持不变,随后合法 Constraints 测量仍返回受限宽度。 fn native_contracts_reject_wrong_types_before_geometry_or_window_effects() { + // 先加载合法页面,以有效业务对象为前提逐项测试原生接口的参数类型边界。 let (mut session, _) = ReplSession::load( include_str!("../../../examples/visual-protocols.endor"), "app.main", @@ -3086,9 +3127,11 @@ fn native_contracts_reject_wrong_types_before_geometry_or_window_effects() { 1, ) .unwrap(); + // 保存属于 rect 的真实 Mount;错误用例只破坏指定参数,不混入失效上下文。 session .execute("context = rect.mounts().at(0)", "app.main") .unwrap(); + // 覆盖 measure/paint 的名义类型、几何运算、窗口尺寸及颜色参数,分别要求对应类型名。 for (expression, expected) in [ ("rect.measure(context, Point(0, 0))", "expects Constraints"), ( @@ -3104,6 +3147,7 @@ fn native_contracts_reject_wrong_types_before_geometry_or_window_effects() { ("ui.window().resize(\"bad\", 700)", "expects Number"), ("rect.setColor(7)", "expects String"), ] { + // 每个非法调用必须返回契约错误,错误消息需区分具体被拒绝的参数。 let error = session .execute(expression, "app.main") .err() @@ -3113,6 +3157,7 @@ fn native_contracts_reject_wrong_types_before_geometry_or_window_effects() { "{expression}: {error:#}" ); } + // 先核对示例保存的原始颜色结果仍正确,再执行合法 Constraints 测量确认会话继续可用。 assert_eq!( session.execute("results.color", "app.main").unwrap().value, "\"#DDEEFF\"" @@ -3133,6 +3178,7 @@ fn native_contracts_reject_wrong_types_before_geometry_or_window_effects() { /// 执行示例内直接调用的原生视觉协议,比较托管 MeasureResult/Arrangement/DisplayList 与真实发布命令。 /// 局部命中允许点内/点外判断,但非法约束、错属 Mount 和已卸载上下文不得用于绘制。 fn native_visual_methods_use_managed_values_and_match_real_geometry() { + // 示例直接调用原生 measure/arrange/paint,并保存托管结果,供本测试与真实首帧对比。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/visual-protocols.endor"), "app.main", @@ -3140,7 +3186,9 @@ fn native_visual_methods_use_managed_values_and_match_real_geometry() { 1, ) .unwrap(); + // 确认文档合法后比较保存结果,覆盖原生协议返回值解码及其名义托管类型。 initial.validate().unwrap(); + // 依次检查受限测量尺寸、子项排列坐标和绘制颜色,保留各协议独立观察点。 for (expression, expected) in [ ("results.width", "120"), ("results.height", "60"), @@ -3148,15 +3196,19 @@ fn native_visual_methods_use_managed_values_and_match_real_geometry() { ("results.childY", "54"), ("results.color", "\"#DDEEFF\""), ] { + // 读取示例执行时保存的结果,避免在断言时重新调用协议改变待检数据。 assert_eq!( session.execute(expression, "app.main").unwrap().value, expected ); } + // 实际发布的矩形使用页面布局分配的 200×60,而直接受限测量返回 120;两种上下文不能混淆。 assert!(initial.frame.commands.iter().any(|command| matches!(command, RenderCommand::RoundedRect { width: 200.0, height: 60.0, color, .. } if color == "#DDEEFF"))); + // 取已发布 rect 的 Mount,后续命中与绘制检查都用这个有效的所属上下文。 session .execute("context = rect.mounts().at(0)", "app.main") .unwrap(); + // 本地坐标 (1,1) 位于矩形内,(-1,1) 位于外部,原生 hitTest 应分别返回 true/false。 assert_eq!( session .execute("rect.hitTest(context, Point(1, 1))", "app.main") @@ -3171,6 +3223,7 @@ fn native_visual_methods_use_managed_values_and_match_real_geometry() { .value, "false" ); + // Constraints 的最小宽度大于最大宽度,即使参数类型正确也必须拒绝。 assert!( session .execute( @@ -3179,11 +3232,13 @@ fn native_visual_methods_use_managed_values_and_match_real_geometry() { ) .is_err() ); + // rect 的 Mount 不属于 root,类型正确仍不能越过所属对象检查。 assert!( session .execute("root.paint(context, Bounds(0, 0, 10, 10))", "app.main") .is_err() ); + // 关闭页面后旧 Mount 已卸载,原 rect 也不能继续用这个上下文绘制。 session.execute("page.close()", "app.main").unwrap(); assert!( session @@ -3196,6 +3251,7 @@ fn native_visual_methods_use_managed_values_and_match_real_geometry() { /// 先 invalidate paint 再 invalidate layout,对比 measured 为 0 和 1。 /// 两者都可发布但不替换 Mount;无关查询不发布,未知失效类别明确报错。 fn explicit_invalidation_publishes_once_preserves_mount_and_remeasures_only_when_requested() { + // 以稳定已发布页面为起点,单独观察显式 paint/layout 失效请求的不同工作量。 let (mut session, _) = ReplSession::load( include_str!("../../../examples/visual-protocols.endor"), "app.main", @@ -3203,15 +3259,19 @@ fn explicit_invalidation_publishes_once_preserves_mount_and_remeasures_only_when 1, ) .unwrap(); + // 在源全局保存原 Mount 引用,供失效后的身份比较使用。 session .execute("context = rect.mounts().at(0)", "app.main") .unwrap(); + // 读取原引用的显示值作为身份基线,避免仅凭相同几何误认同一出现位置。 let original = session.execute("context", "app.main").unwrap().value; + // 仅使 paint 失效也应发布新文档,但 measured 统计必须为零。 let update = session .execute("rect.invalidate(\"paint\")", "app.main") .unwrap() .document .unwrap(); + // 检查新文档有效,再读取本次更新的测量数,不把发布成功当作未重测的证据。 update.validate().unwrap(); assert_eq!( session @@ -3220,6 +3280,7 @@ fn explicit_invalidation_publishes_once_preserves_mount_and_remeasures_only_when .value, "0" ); + // 显式 layout 失效应发布并重新测量,随后统计要求恰好一个测量。 assert!( session .execute("rect.invalidate(\"layout\")", "app.main") @@ -3234,6 +3295,7 @@ fn explicit_invalidation_publishes_once_preserves_mount_and_remeasures_only_when .value, "1" ); + // 两种失效都应保留原 Mount 身份,不通过销毁重建来刷新。 assert_eq!( session .execute("rect.mounts().at(0)", "app.main") @@ -3241,6 +3303,7 @@ fn explicit_invalidation_publishes_once_preserves_mount_and_remeasures_only_when .value, original ); + // 无关的只读查询不能再发布一帧,验证失效已被消费完。 assert!( session .execute("results.width", "app.main") @@ -3248,6 +3311,7 @@ fn explicit_invalidation_publishes_once_preserves_mount_and_remeasures_only_when .document .is_none() ); + // 未知失效类别应明确报错,不能默认为最宽泛的重排而掩盖调用错误。 assert!( session .execute("rect.invalidate(\"unknown\")", "app.main") @@ -3259,6 +3323,7 @@ fn explicit_invalidation_publishes_once_preserves_mount_and_remeasures_only_when /// 加载共享子项生命周期示例,通过日志计数检查每个出现位置各自挂载。 /// 普通颜色更新不重复 onMount;关闭时子先父后卸载,保存的旧 Mount 永久失效,重开创建新出现位置。 fn mount_hooks_run_per_occurrence_settle_and_unmount_before_parent() { + // 共享 child 在树中出现两次;生命周期日志区分业务对象与每个独立出现位置。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/mount-lifecycle.endor"), "app.main", @@ -3266,17 +3331,21 @@ fn mount_hooks_run_per_occurrence_settle_and_unmount_before_parent() { 1, ) .unwrap(); + // 首帧已完成钩子引起的状态变化,文档应有效且日志顺序已经稳定。 initial.validate().unwrap(); + // 父先挂载,两个 child 出现随后挂载;最后一个子通知序号为 3。 for (expression, expected) in [ ("log.mounted.value", "2"), ("log.parentMounted", "1"), ("log.childMounted", "3"), ] { + // 逐项读取真实业务日志,避免只比较总次数而遗漏父子通知顺序。 assert_eq!( session.execute(expression, "app.main").unwrap().value, expected ); } + // 保存旧 Mount 后仅改颜色;这是普通数据刷新,不能再次调用 onMount。 session .execute( "saved = child.mounts().at(0)\nchild.setColor(\"#237A45\")", @@ -3290,6 +3359,7 @@ fn mount_hooks_run_per_occurrence_settle_and_unmount_before_parent() { .value, "2" ); + // 关闭页面应发布空 Mount 树,并对两个 child 出现各执行一次 onUnmount。 let closed = session .execute("page.close()", "app.main") .unwrap() @@ -3303,6 +3373,7 @@ fn mount_hooks_run_per_occurrence_settle_and_unmount_before_parent() { .value, "2" ); + // 最后一个 child 卸载序号为 5,父卸载为 6,验证卸载阶段子先父后的顺序。 assert_eq!( session .execute("log.childUnmounted", "app.main") @@ -3317,11 +3388,13 @@ fn mount_hooks_run_per_occurrence_settle_and_unmount_before_parent() { .value, "6" ); + // 保留的旧句柄可查询 mounted=false,但不允许再读取有效布局边界。 assert_eq!( session.execute("saved.mounted", "app.main").unwrap().value, "false" ); assert!(session.execute("saved.bounds()", "app.main").is_err()); + // 重开页面创建新出现位置,总挂载次数增为 4;旧句柄仍不能复活。 session.execute("page.open()", "app.main").unwrap(); assert_eq!( session @@ -3340,6 +3413,7 @@ fn mount_hooks_run_per_occurrence_settle_and_unmount_before_parent() { /// 让两个页面使用同一业务根,然后切换活动页面。 /// 每次切换都卸载旧上下文并挂载新上下文;共享 Block 不能让旧 Mount 或 page() 指向继续复用。 fn page_switch_replaces_mount_context_even_for_shared_root() { + // 先打开包含共享 child 的初始页面,建立两个有效 Mount 及其日志基线。 let (mut session, _) = ReplSession::load( include_str!("../../../examples/mount-lifecycle.endor"), "app.main", @@ -3347,12 +3421,14 @@ fn page_switch_replaces_mount_context_even_for_shared_root() { 1, ) .unwrap(); + // 保存旧上下文,再让第二个页面使用同一业务根;活动页面切换仍必须重建 Mount 上下文。 session .execute( "saved = child.mounts().at(0)\nsecond = Page()\nsecond.render(root)", "app.main", ) .unwrap(); + // 新页面挂载两次、旧页面卸载两次;共享根不能使页面之间复用出现位置。 assert_eq!( session .execute("log.mounted.value", "app.main") @@ -3371,6 +3447,7 @@ fn page_switch_replaces_mount_context_even_for_shared_root() { session.execute("saved.mounted", "app.main").unwrap().value, "false" ); + // 新 Mount.page() 必须属于 second,防止业务对象相同却残留旧页面关系。 assert_eq!( session .execute("child.mounts().at(0).page()", "app.main") @@ -3378,6 +3455,7 @@ fn page_switch_replaces_mount_context_even_for_shared_root() { .value, session.execute("second", "app.main").unwrap().value ); + // 再激活原页面也会创建新的两个出现位置,总挂载数应由 4 变为 6。 session.execute("page.activate()", "app.main").unwrap(); assert_eq!( session @@ -3392,17 +3470,22 @@ fn page_switch_replaces_mount_context_even_for_shared_root() { /// onMount 向容器 append 新文字,最终文档应包含该结构变化,验证回调后继续收敛。 /// 另一个 onMount 传入错误 setText 参数,错误应停止共享运行时而非忽略生命周期失败。 fn lifecycle_hook_can_edit_container_without_session_lock_and_failure_stops_domain() { + // GrowingColumn 的 onMount 修改自身子项,验证生命周期回调允许正常结构编辑并继续收敛。 let source = r#"class GrowingColumn: Column { function onMount(self: GrowingColumn, mount: Mount): Unit { self.append(TextBlock("from hook")) } } root = GrowingColumn(0, 0) page = Page() page.render(root)"#; + // 从加载返回的首帧就应看到新增文字,不能等下次输入才补出钩子产生的内容。 let (_, document) = ReplSession::load(source, "app.main", 53, 1).unwrap(); + // 比较真实文字命令,确认 append 已进入最终布局/绘制结果。 assert!(document.frame.commands.iter().any( |command| matches!(command, RenderCommand::Text { value, .. } if value == "from hook") )); + // 另建独立会话测试错误钩子,避免前一合法结构变更影响失败路径。 let mut session = ReplSession::new(54).unwrap(); + // BrokenText 钩子给 setText 传数字,故障必须向会话传播,不能静默忽略生命周期错误。 let source = r#"class BrokenText: TextBlock { function onMount(self: BrokenText, mount: Mount): Unit { self.setText(1) } } @@ -3415,18 +3498,22 @@ fn lifecycle_hook_can_edit_container_without_session_lock_and_failure_stops_doma /// 在标准事件示例后附加 extra 语句,创建独立会话和初始完整文档。 /// 各路由测试只需描述额外监听器,即可共享相同父子树、计数器与默认事件配置。 fn event_session(extra: &str) -> (ReplSession, RenderDocument) { + // 下方事件路由测试调用本助手;追加语句可调整监听器,不必复制整份树和业务模型。 let source = format!( "{}\n{}", include_str!("../../../examples/events.endor"), extra ); + // 正常加载并收敛初始页面,向调用方返回会话和可用于事件版本校验的完整文档。 ReplSession::load(&source, "app.main", 41, 1).unwrap() } /// 按全局 button 的业务身份找给定文档中的可交互 Mount,模拟原生 click。 /// 事件使用该文档的会话与布局版本,返回派发后的完整文档,避免用过期目标绕过真实输入检查。 fn click_document(session: &mut ReplSession, document: &RenderDocument) -> RenderDocument { + // 事件测试助手从当前会话的名字表取得 button,保持业务身份与输入目标一致。 let globals = session.candidate.globals.unwrap(); + // 缺失或非对象说明夹具不满足约定,应直接失败而非挑选任意可交互节点。 let Value::Object(button) = session .candidate .vm @@ -3436,12 +3523,14 @@ fn click_document(session: &mut ReplSession, document: &RenderDocument) -> Rende else { panic!("Button") }; + // 同时按 Block ID 与 interactive 筛选,确保测试输入指向当前文档中的有效按钮出现位置。 let mount = document .frame .mounts .iter() .find(|mount| mount.interactive && mount.block_id == button.to_string()) .unwrap(); + // 携带传入文档的 session/layout_version 派发 click;要求有发布结果供调用方继续验证。 session .dispatch(&crate::events::Input { window: crate::window::MAIN_WINDOW, @@ -3464,14 +3553,18 @@ fn click_document(session: &mut ReplSession, document: &RenderDocument) -> Rende /// 通过原生输入路径触发一次 click,检查捕获、目标方法、目标监听器、冒泡依次记为 1/2/3/4。 /// 派发结束后的模型保留最后阶段信息,订阅令牌仍连接。 fn managed_event_route_orders_capture_method_listeners_and_bubble() { + // 基线事件夹具保留捕获、目标方法、目标监听器和冒泡四个阶段,不追加额外监听器。 let (mut session, initial) = event_session(""); + // 通过模拟原生 click 进入宿主路由,并验证回调产生的新文档结构有效。 click_document(&mut session, &initial).validate().unwrap(); + // 逐阶段核对同一个递增序列,既检查执行次数也检查阶段之间的先后关系。 for (field, expected) in [ ("captureStep", "1"), ("methodStep", "2"), ("targetStep", "3"), ("bubbleStep", "4"), ] { + // 按字段名读取源模型;每个字段由对应阶段回调写入,不能靠最终总数推断顺序。 assert_eq!( session .execute(&format!("model.{field}"), "app.main") @@ -3480,6 +3573,7 @@ fn managed_event_route_orders_capture_method_listeners_and_bubble() { expected ); } + // 模型保存的最后阶段应是 bubble;监听令牌仍连接,正常派发不自动退订。 assert_eq!( session.execute("model.phase", "app.main").unwrap().value, "\"bubble\"" @@ -3497,10 +3591,13 @@ fn managed_event_route_orders_capture_method_listeners_and_bubble() { /// 第一场景在捕获中断开尚未调用的目标监听器,必须跳过它但继续冒泡。 /// 第二场景在目标捕获中 stopPropagation,当前目标组仍执行,祖先冒泡被阻止。 fn disconnect_during_capture_skips_pending_listener_and_stop_preserves_current_group() { + // 在祖先捕获中追加断开 target 的回调;断开发生在目标监听器尚未轮到执行之前。 let (mut session, initial) = event_session( "function cancel(event: Event): Unit { target.disconnect() }\nconnection = root.on(\"click\", cancel, \"capture\")", ); + // 实际派发一次;捕获与目标方法仍执行,目标监听器跳过后冒泡成为第 3 步。 click_document(&mut session, &initial); + // 检查目标没有写入序号、冒泡继续执行且令牌已断开,三项共同界定同次派发的退订语义。 assert_eq!( session .execute("model.targetStep", "app.main") @@ -3522,9 +3619,11 @@ fn disconnect_during_capture_skips_pending_listener_and_stop_preserves_current_g .value, "false" ); + // 另建会话,在目标捕获组调用 stopPropagation;不沿用前一场景的已断开监听器。 let (mut session, initial) = event_session( "function stop(event: Event): Unit { event.stopPropagation() }\nconnection = button.on(\"click\", stop, \"capture\")", ); + // 重新派发后目标同组监听器仍为第 3 步,但祖先冒泡保持未执行的 0。 click_document(&mut session, &initial); assert_eq!( session @@ -3546,9 +3645,11 @@ fn disconnect_during_capture_skips_pending_listener_and_stop_preserves_current_g /// 目标捕获使用 stopImmediatePropagation,应连目标默认方法也跳过。 /// 代码派发 custom 事件可返回同一带 preventDefault 标记的 Event,结束后 phase 为 none,并允许再次派发。 fn immediate_stop_skips_target_method_and_code_dispatch_returns_cancelled_event() { + // 目标捕获阶段立即停止传播;祖先捕获已执行,但目标方法和后续监听器都应跳过。 let (mut session, initial) = event_session( "function stop(event: Event): Unit { event.stopImmediatePropagation() }\nconnection = button.on(\"click\", stop, \"capture\")", ); + // 总计数只能为祖先捕获贡献的 1,区分立即停止与仅阻止祖先冒泡。 click_document(&mut session, &initial); assert_eq!( session @@ -3557,9 +3658,11 @@ fn immediate_stop_skips_target_method_and_code_dispatch_returns_cancelled_event( .value, "1" ); + // 单独测试源码 dispatch:custom 监听器调用 preventDefault,返回 Event 保留取消标记。 let (mut session, _) = event_session( "function prevent(event: Event): Unit { event.preventDefault() }\nconnection = button.on(\"custom\", prevent)\nresult = button.dispatch(Event(\"custom\"))", ); + // 取消标记在返回对象上可见;派发退出后 Event.phase 应恢复 none。 assert_eq!( session .execute("result.isDefaultPrevented()", "app.main") @@ -3581,26 +3684,33 @@ fn immediate_stop_skips_target_method_and_code_dispatch_returns_cancelled_event( /// 回调失败后断开故障监听器,再派发同一 Event,验证活跃派发守卫已释放。 /// 另外保留订阅 token 却删除隐藏目标,回收后目标弱升级失败且 token 断开,证明它不强持有目标。 fn event_failure_releases_dispatch_guard_and_token_does_not_retain_target() { + // 复用有效事件页面,追加一个会因 page.render 参数错误而失败的独立事件监听器。 let (mut session, _) = event_session(""); + // 保留 failedEvent 句柄,错误后必须能重新派发同一对象以验证活跃守卫释放。 session.execute("function fail(event: Event): Unit { page.render(1) }\nfailing = button.on(\"failure\", fail)\nfailedEvent = Event(\"failure\")", "app.main").unwrap(); + // 第一次派发必须失败,确保后面的重用检查覆盖异常展开路径。 assert!( session .execute("button.dispatch(failedEvent)", "app.main") .is_err() ); + // 先移除故障回调,再用同一 Event 成功派发;若守卫泄漏,会误报重复派发。 session .execute( "failing.disconnect()\nbutton.dispatch(failedEvent)", "app.main", ) .unwrap(); + // 创建未挂载的按钮并保留订阅 token,随后只删除业务全局强引用。 session .execute( "orphan = Button(\"unmounted\")\ntoken = orphan.on(\"click\", model.target)", "app.main", ) .unwrap(); + // 取得名字表,便于准确删除 orphan,而保留 token 和其回调模型。 let globals = session.candidate.globals.unwrap(); + // 取目标对象句柄以创建弱引用;Rust 局部句柄不应成为 VM 的持久业务根。 let Value::Object(orphan) = session .candidate .vm @@ -3610,16 +3720,20 @@ fn event_failure_releases_dispatch_guard_and_token_does_not_retain_target() { else { panic!("Block expected") }; + // 弱句柄用于确认目标确实回收,不只检查 token 对外显示已断开。 let weak = session.candidate.vm.downgrade(orphan).unwrap(); + // 删除 orphan 的最后显式全局强引用;不删除 token,专门检查 token 不强持有目标。 session .candidate .vm .dict_delete(globals, &Value::Text("orphan".into())) .unwrap(); + // 沿真实桥接根集合执行回收,测试弱订阅与 GC 的组合行为。 session .bridge .reclaim(&mut session.candidate.vm, &mut session.candidate.roots) .unwrap(); + // 目标弱升级必须失败,且仍存活的 token 查询为未连接。 assert!(session.candidate.vm.upgrade(weak).unwrap().is_none()); assert_eq!( session @@ -3634,6 +3748,7 @@ fn event_failure_releases_dispatch_guard_and_token_does_not_retain_target() { /// 加载原生视觉子类,把旧 label 引用保存到 alias 后替换为新的源实例。 /// 共享转发应让 alias 读写新字段、更新多个绘制位置,同时旧属性存储的弱句柄可回收。 fn source_native_subclasses_share_live_fields_and_release_replaced_storage() { + // 加载带源字段的原生视觉子类,初始文档与类型查询先验证基线合法。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/native-subclasses.endor"), "app.main", @@ -3641,6 +3756,7 @@ fn source_native_subclasses_share_live_fields_and_release_replaced_storage() { 1, ) .unwrap(); + // 子类实例仍应满足 TextBlock/Page 原生名义类型,后续才测试替换与字段转发。 initial.validate().unwrap(); assert_eq!( session @@ -3656,8 +3772,11 @@ fn source_native_subclasses_share_live_fields_and_release_replaced_storage() { .value, "true" ); + // 额外保留旧业务引用,替换 label 后 alias 应通过共享转发访问新的属性存储。 session.execute("alias = label", "app.main").unwrap(); + // 取当前 label 对象,以其真实属性路径定位替换前的底层存储。 let globals = session.candidate.globals.unwrap(); + // 要求目标是原夹具中的 Block 对象,而非 Console 展示文本或另建实例。 let Value::Object(label) = session .candidate .vm @@ -3667,17 +3786,20 @@ fn source_native_subclasses_share_live_fields_and_release_replaced_storage() { else { panic!("Block expected") }; + // 读取属性转发链,末尾存储是本用例要检查是否被替换并回收的对象。 let path = session .candidate .vm .object_store() .attribute_path(label) .unwrap(); + // 只保存旧属性存储的弱句柄,避免测试本身强持有旧存储而阻止回收。 let previous = session .candidate .vm .downgrade(*path.last().unwrap()) .unwrap(); + // 用同名源实例替换 label,首次新文档应已显示新字段内容。 let updated = session .execute( r##"label = CustomStatus("replacement", 2, "#242422", "#237A45", "new field")"##, @@ -3686,24 +3808,29 @@ fn source_native_subclasses_share_live_fields_and_release_replaced_storage() { .unwrap() .document .unwrap(); + // 验证替换已经进入绘制结果,再检查旧存储回收与 alias 读写转发。 assert!(updated.frame.commands.iter().any( |command| matches!(command, RenderCommand::Text { value, .. } if value == "new field") )); + // 回收不再从共享业务身份可达的旧存储;alias 不能让过时属性存储继续存活。 session .bridge .reclaim(&mut session.candidate.vm, &mut session.candidate.roots) .unwrap(); + // 旧存储应消失,但 alias.message 必须仍读取替换后的 new field。 assert!(session.candidate.vm.upgrade(previous).unwrap().is_none()); assert_eq!( session.execute("alias.message", "app.main").unwrap().value, "\"new field\"" ); + // 点击原按钮触发业务更新,多个文字出现应共同看到替换后的字段值。 let updated = session .execute("button.click()", "app.main") .unwrap() .document .unwrap(); assert_eq!(updated.frame.commands.iter().filter(|command| matches!(command, RenderCommand::Text { value, .. } if value == "new field")).count(), 3); + // 最后从旧 alias 写入字段,新文档也应反映 changed field,覆盖双向转发。 let updated = session .execute("alias.message = \"changed field\"", "app.main") .unwrap() @@ -3718,6 +3845,7 @@ fn source_native_subclasses_share_live_fields_and_release_replaced_storage() { /// 完整源码加载后执行 Console 类型查询,再用原生 click 调用原程序中的源回调。 /// 两个共享文字都应变为 10 且 VM 健康,覆盖混合入口中源 ID/编译单元身份不冲突的行为。 fn loaded_program_console_and_native_events_share_unique_source_ids() { + // 先加载完整源码编译单元,保留其中源回调;随后追加 Console 单元并触发原生事件。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/managed-types.endor"), "app.main", @@ -3725,6 +3853,7 @@ fn loaded_program_console_and_native_events_share_unique_source_ids() { 1, ) .unwrap(); + // 在已有程序上执行 Console 类型查询,验证混合输入可以继续引用原对象和类型。 initial.validate().unwrap(); assert_eq!( session @@ -3733,12 +3862,14 @@ fn loaded_program_console_and_native_events_share_unique_source_ids() { .value, "true" ); + // 从初始帧找可交互按钮,用原帧版本构造原生 click,回调仍来自最初加载的源码。 let mount = initial .frame .mounts .iter() .find(|mount| mount.interactive) .unwrap(); + // 固定会话 ID 与加载一致,避免过期输入拒绝掩盖源 ID/编译单元冲突。 let event = crate::events::Input { window: crate::window::MAIN_WINDOW, session: 1, @@ -3751,8 +3882,10 @@ fn loaded_program_console_and_native_events_share_unique_source_ids() { tab_drop: None, screen_position: None, }; + // 派发原生输入后要求返回新文档并通过结构验证。 let updated = session.dispatch(&event).unwrap().document.unwrap(); updated.validate().unwrap(); + // 两处共享文字都应变为 10,同时 VM 保持健康,证明跨入口回调没有落到错误源码单元。 assert_eq!( updated .frame