diff --git a/src/runtime/endor_host/tests.rs b/src/runtime/endor_host/tests.rs index a9623be..eebbe1a 100644 --- a/src/runtime/endor_host/tests.rs +++ b/src/runtime/endor_host/tests.rs @@ -2,10 +2,14 @@ //! 覆盖共享对象/独立 Mount、源覆盖、绑定、窗口、任务、取消、二维/三维投影及像素。局部辅助函数负责取统计值、收敛刷新和构造可重复输入。 //! 阅读时先看每个测试提交的 Endor 程序,再看后续变更与最终断言;编译成功、回调成功、文档发布成功是不同检查点。 //! +//! Rust 测试框架运行各 #[test],ReplSession 的测试同步入口负责排空实际 layout/paint,断言读取已完成文档。 +//! r# 原始字符串中的 Endor 是验收夹具,保持其源码/行号不变;Rust 注释解释夹具意图和随后观察的行为。 use super::*; use crate::document::{NamespaceState, RenderCommand}; +// 一次性模块执行/错误保留测试共用的真实示例,不在测试中另造只为通过断言的近似模块。 const EXAMPLE: &str = include_str!("../../../examples/hello.endor"); +// 页面脚本基线供多个源加载、替换、生命周期测试复用,include_str 在编译时嵌入。 const PAGE: &str = include_str!("../../../examples/page.endor"); /// 可选性能基准:分别测世界 UI 和普通三维场景在 1x/2x DPI 下的相机交互更新、变更绘制和同列表缓存绘制。 @@ -17,6 +21,7 @@ fn scene_interaction_performance() { use std::time::Instant; /// 对非空毫秒样本排序后返回均值、索引中位数和向上取整秩的 p95;调用方每组固定保留 30 次测量。 fn summary(mut values: Vec) -> String { + // total_cmp 提供稳定全序,下面按排序后的样本索引取统计值,不修改被测场景数据。 values.sort_by(f64::total_cmp); format!( "mean={:.3} p50={:.3} p95={:.3}ms", @@ -31,6 +36,7 @@ fn scene_interaction_performance() { ("scene3d", include_str!("../../../examples/scene3d.endor")), ] { for dpi in [1., 2.] { + // 逻辑视口保持 1024×800,后面仅物理像素倍率变化,避免混淆 DPI 与场景布局大小。 let (mut session, mut document) = ReplSession::load_with_viewport( source, "app.main", @@ -42,13 +48,19 @@ fn scene_interaction_performance() { }), ) .unwrap(); + // 软件输出尺寸按逻辑大小乘 DPI;同一组合复用像素缓冲,不把分配计入每帧绘制时间。 let (width, height) = ((1024. * dpi) as u32, (800. * dpi) as u32); + // u32 像素列表由真实软件渲染器覆盖,不用模拟绘图计数代替实际工作量。 let mut pixels = vec![0; (width * height) as usize]; + // 三种样本分别统计派发/刷新、变化列表绘制和同列表再次绘制,不把它们混为一个延迟。 let mut updates = Vec::new(); + // 相机刚变化后首次绘制耗时,和 source 更新/几何发布分开采样。 let mut draws = Vec::new(); + // 同一 DisplayList 的第二次绘制,用于观察缓存复用路径,不再推进源程序。 let mut cached = Vec::new(); // 连续做 33 轮,前三轮预热;每轮使用最新发布版本构造事件,避免基准测到过期输入拒绝。 for sample in 0..33 { + // 每次从最新帧找原始三维视口,身份与版本一致才测到有效 orbit 而非快速过期拒绝。 let target = document .frame .mounts @@ -71,8 +83,11 @@ fn scene_interaction_performance() { // update 只计派发与完整文档刷新;display_list 构造在后面的绘制计时范围之外。 let start = Instant::now(); document = session.dispatch(&input).unwrap().document.unwrap(); + // 统一转毫秒,sample>=3 后才保存预热之外的数值。 let update = start.elapsed().as_secs_f64() * 1000.; + // 显示列表构造不包含在下面 render 计时里,避免把两种阶段成本混为绘制耗时。 let list = document.display_list(dpi).unwrap(); + // 单独计首次变化帧的像素绘制时间。 let start = Instant::now(); crate::software_renderer::SoftwareRenderer::render( &list, @@ -83,6 +98,7 @@ fn scene_interaction_performance() { .unwrap(); // 第一次 render 测相机已变化时的绘制;立即用同一列表再画一次,单独统计缓存重用路径。 let draw = start.elapsed().as_secs_f64() * 1000.; + // 不改变 list/像素尺寸直接再次 render,观察缓存命中绘制,不再发第二次相机输入。 let start = Instant::now(); crate::software_renderer::SoftwareRenderer::render( &list, @@ -122,6 +138,7 @@ fn scene_interaction_performance() { /// 源 measure 直接读取 mount.layoutVersion 并将其作为宽度。 /// 只使 paint 失效后仍必须重新测量;通过新版本宽度和零缓存命中,防止把真实 Mount 读取错误缓存。 fn actual_mount_version_reads_still_bypass_measurement_cache() { + // measure 显式读取 Mount.layoutVersion,将宿主出现版本变成真实依赖,不能按静态对象结果复用。 let (mut session, initial) = ReplSession::load( r#" class Versioned: RectBlock { @@ -138,6 +155,7 @@ page.render(rect) 241, ) .unwrap(); + // 即使只请求 paint 失效,版本依赖仍要求重新测量,不能无条件沿用上轮宽度。 let next = session .execute("rect.invalidate(\"paint\")", "app.main") .unwrap() @@ -153,6 +171,7 @@ page.render(rect) /// 加载布局协商示例,验证同一段落两个出现位置分别获得 280/360 的宽度。 /// 加宽第一个出现位置后高度和后继 y 减小,第二个仍保持 360,且全部 Mount ID 不变。 fn source_allocations_and_measurement_limits_settle_before_publication() { + // 同一 paragraph 在两个约束下展示,验收源布局协商而非给两个独立对象写固定宽度。 let (mut session, initial) = ReplSession::load_with_viewport( include_str!("../../../examples/layout-negotiation.endor"), "app.main", @@ -164,28 +183,33 @@ fn source_allocations_and_measurement_limits_settle_before_publication() { }), ) .unwrap(); + // 保存所有出现身份,后面加宽只允许改变几何,不能销毁重建整棵 Mount 树。 let ids = initial .frame .mounts .iter() .map(|m| m.id) .collect::>(); + // 通过源 Mount API 读取第一个出现实际布局宽,验证不是只在绘图命令中临时缩放。 let width0 = session .execute("paragraph.mounts().at(0).bounds().width", "app.main") .unwrap() .value; + // 第二个出现属于同一业务对象,但有独立父约束,初始应为 360。 let width1 = session .execute("paragraph.mounts().at(1).bounds().width", "app.main") .unwrap() .value; assert_eq!(width0, "280"); assert_eq!(width1, "360"); + // 较窄约束使段落多行,记录原高度用于加宽后的 reflow 比较。 let height = session .execute("paragraph.mounts().at(0).bounds().height", "app.main") .unwrap() .value .parse::() .unwrap(); + // tail 在段落之后,段落高度变化必须传到后继 y,而不只是更新该段落绘制边界。 let y = session .execute("tail.mounts().at(0).bounds().y", "app.main") .unwrap() @@ -195,6 +219,7 @@ fn source_allocations_and_measurement_limits_settle_before_publication() { assert!(height > 20.0); assert!(y >= height + 12.0); assert!(source_measure_stat(&mut session, "layoutPasses") >= 2); + // 源按钮修改第一处宽度,再由正常刷新收敛和发布,不能直接从测试覆盖 Frame 几何。 let changed = session .execute("wide.click()", "app.main") .unwrap() @@ -209,12 +234,14 @@ fn source_allocations_and_measurement_limits_settle_before_publication() { .collect::>(), ids ); + // 变量名 wider 指加宽后的高度;文本行数减少时这个值应小于原 height。 let wider = session .execute("paragraph.mounts().at(0).bounds().height", "app.main") .unwrap() .value .parse::() .unwrap(); + // 同步观察 tail 上移,证明父布局已在发布前消费新的段落高度。 let moved = session .execute("tail.mounts().at(0).bounds().y", "app.main") .unwrap() @@ -242,6 +269,7 @@ fn source_allocations_and_measurement_limits_settle_before_publication() { /// 源 arrange 把子项宽高不断交换,构造不收敛的布局状态。 /// 加载必须报告 cycle,不能发布某个偶然中间态或依靠固定次数静默停止。 fn alternating_source_allocations_are_rejected_as_a_cycle() { + // 源 arrange 在父宽高之间交替指定孩子尺寸,固定点不收敛,应作为 cycle 拒绝而非任意截断。 let source = r#" class Alternating: Column { function arrange(self: Alternating,mount: Mount,geometry: Bounds): Arrangement { @@ -254,6 +282,7 @@ class Alternating: Column { page=Page() page.render(Alternating(0,0,RectBlock(120,60))) "#; + // 从真实初始布局收敛得到错误,断言消息以区分预算耗尽和明确循环检测。 let error = ReplSession::load(source, "app.main", 1, 1).err().unwrap(); assert!( error.to_string().contains("did not converge (cycle)"), @@ -265,6 +294,7 @@ page.render(Alternating(0,0,RectBlock(120,60))) /// 源 paint 只提供 wrapWidth,省略成对需要的 wrapHeight。 /// 检查命令解码明确拒绝不完整文字边界,而非生成测量/绘制不一致的帧。 fn source_text_paint_rejects_incomplete_wrap_bounds() { + // 只写 wrapWidth 不写 wrapHeight,构造解码层必须拒绝的半套文本边界,不能容错生成另一种命令。 let source = r##" class Invalid: TextBlock { function paint(self: Invalid,mount: Mount,geometry: Bounds): DisplayList { @@ -282,6 +312,7 @@ class Invalid: TextBlock { page=Page() page.render(Invalid("invalid")) "##; + // 源类型与函数合法,失败应准确指向遗漏的 wrapHeight,证明进入了实际 PaintCommand 解码。 let error = ReplSession::load(source, "app.main", 1, 1).err().unwrap(); assert!(error.to_string().contains("wrapHeight"), "{error:#}"); } @@ -290,9 +321,12 @@ page.render(Invalid("invalid")) /// 分别对原生 TextBlock 和委托原生方法的源子类运行相同测试。 /// 共享文字在不同内边距下独立换行;视口变宽只更新几何、保留 Mount,直接测量和 setText 也应同步反映尺寸。 fn wrapped_text_tracks_each_occurrence_width_resize_and_sibling_geometry() { + // 长中文段落迫使换行,不能靠一个短词恰好装得下而漏测父约束对自然高度的影响。 let text = "中文段落随着宽度变化而换行,后面的对象跟随段落高度移动。".repeat(8); for custom in [false, true] { + // 原生 TextBlock 与源委托子类应走同一测量/绘制语义,分别执行避免共享一个偶然缓存结果。 let constructor = if custom { "Wrapped" } else { "TextBlock" }; + // 相同 paragraph 放到不同内边距容器,两个出现必须分别获得可用宽度和换行高度。 let source = format!( r#" class Wrapped: TextBlock {{ @@ -305,6 +339,7 @@ page=Page() page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) "# ); + // 初始逻辑宽 240、高度充足,测到换行而非可视裁剪导致的“只看到几行”。 let (mut session, initial) = ReplSession::load_with_viewport( &source, "app.main", @@ -316,7 +351,9 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) }), ) .unwrap(); + // resize 后身份必须保持,缓存/几何更新不应改已捕获的 Mount ID。 let ids: Vec<_> = initial.frame.mounts.iter().map(|m| m.id).collect(); + // 只取实际段落文本命令,排除 tail/其他文本,读取 wrap_bounds 的宽与高。 let commands: Vec<_> = initial .frame .commands @@ -327,6 +364,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) wrap_bounds: Some(bounds), .. } if value == &text => Some(*bounds), + // 非目标段落或无换行边界命令不参与这组独立出现比较。 _ => None, }) .collect(); @@ -336,6 +374,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) assert_eq!(commands[0][0], 240.0); assert_eq!(commands[1][0], 140.0); assert!(commands[1][1] > commands[0][1]); + // 文本绘制 y 也需跟随段落自然高度,不能只有 Mount 的虚拟几何更新。 let tail = initial .frame .commands @@ -346,6 +385,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) }) .unwrap(); assert!(tail >= commands[0][1] + 8.0); + // 只改变窗口逻辑宽,不重新执行 Endor 输入,验证 renderer/源协议在保留 VM 上重排。 let resized = session .resize(Some(crate::layout::Size { width: 400.0, @@ -362,6 +402,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) .map(|m| m.id) .collect::>() ); + // 两个父级仍相差 100 内边距,但分别在新宽度下重测,不能共享一个固定 wrapWidth。 let widths: Vec<_> = resized .frame .commands @@ -376,6 +417,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) }) .collect(); assert_eq!(widths, [400.0, 300.0]); + // 同字串加宽后的实际绘制行高和原来比较,排除仅命令宽字段被改、字形仍按旧行排的情况。 let heights: Vec<_> = resized .frame .commands @@ -390,6 +432,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) }) .collect(); assert!(heights[0] < commands[0][1]); + // 源代码显式在更窄 80 约束下 measure,验证协议返回高度也与 Frame 的宽约束相关。 let direct = session .execute( "paragraph.measure(paragraph.mounts().at(0),Constraints(0,0,80,2000)).height", @@ -403,6 +446,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) session .execute("paragraph.setText(\"short\")", "app.main") .unwrap(); + // 短文本恢复单行,但同业务对象的两个出现仍都在,不能用替换对象逃避共享布局更新。 assert_eq!( session .execute("paragraph.mounts().count", "app.main") @@ -424,6 +468,7 @@ page.render(Column(0,8,Column(0,8,paragraph,tail),Column(50,8,paragraph))) /// 加载回调签名示例,逐项尝试不匹配的事件/绑定/任务回调及参数个数。 /// 注册期错误不能使会话 fault;合法零参数与 Event 参数回调均可执行,最后检查底层方法实际 arity。 fn native_signatures_validate_registration_and_deliver_the_event_argument() { + // 使用带零参/单 Event 回调的真实示例,后续非法注册与合法分发都在同一份活 globals 中执行。 let (mut session, _) = ReplSession::load( include_str!("../../../examples/native-signatures.endor"), "app.main", @@ -438,6 +483,7 @@ fn native_signatures_validate_registration_and_deliver_the_event_argument() { r#"ui.after(ui,"bad",60000,received.set)"#, "count.increment(1)", ] { + // 逐个变坏回调种类或参数数量,错误应在注册/调用边界拒绝,健康运行时仍可继续接受输入。 assert!(session.execute(invalid, "app.main").is_err(), "{invalid}"); assert!( session.documents[&crate::window::MAIN_WINDOW] @@ -446,6 +492,7 @@ fn native_signatures_validate_registration_and_deliver_the_event_argument() { .is_none() ); } + // 合法单 Event 回调把 kind 保存到模型,渲染文字也应读取到 click,覆盖实际参数交付。 let document = session .execute("withEvent.click()", "app.main") .unwrap() @@ -469,7 +516,9 @@ fn native_signatures_validate_registration_and_deliver_the_event_argument() { "1" ); assert!(session.poll_tasks().unwrap().is_none()); + // 最后直接查 VM 元数据,检查绑定状态方法 set 的实际显式 arity,不只看错误字符串。 let globals = session.candidate.globals.unwrap(); + // received 是全局里真实状态对象,所有权仍由 globals 持有,这里只读取其句柄。 let Value::Object(received) = session .candidate .vm @@ -479,6 +528,7 @@ fn native_signatures_validate_registration_and_deliver_the_event_argument() { else { panic!("state") }; + // set 已捕获 receiver,只应接受一个新值,不能额外把 owner 计入未绑定参数。 let Value::Object(set) = session.candidate.vm.get_attr(received, "set").unwrap() else { panic!("set") }; @@ -492,6 +542,7 @@ fn native_signatures_validate_registration_and_deliver_the_event_argument() { /// 尝试错误字段赋值与构造,检查声明字段契约在原生分配副作用之前验证。 /// 已有值和窗口页面数量必须保持不变,随后合法点击仍能递增并发布文字。 fn checked_fields_reject_native_constructor_side_effects_and_preserve_live_values() { + // 声明字段具有真实语言注解,错误数字/字符串构造应在原生分配副作用之前失败。 let (mut session, _) = ReplSession::load( include_str!("../../../examples/field-contracts.endor"), "app.main", @@ -504,6 +555,8 @@ fn checked_fields_reject_native_constructor_side_effects_and_preserve_live_value r#"CounterText("bad", "wrong")"#, "Model(42)", ] { + // 三种错误分别覆盖已有字段写入、原生子类构造与普通类构造,均不能停掉健康域。 + // 保留真实诊断检查 field,避免一个无关语法错误也被测试当作字段类型检查通过。 let error = session.execute(invalid, "app.main").err().unwrap(); assert!(error.to_string().contains("field"), "{error:#}"); assert!( @@ -520,6 +573,7 @@ fn checked_fields_reject_native_constructor_side_effects_and_preserve_live_value session .execute("class CheckedPage: Page { count: Number }", "app.main") .unwrap(); + // 用页面数量作为构造副作用基线,错误 CheckedPage 字段不能偷偷把新页注册到窗口。 let pages = session .execute("ui.window().pages().count", "app.main") .unwrap() @@ -536,6 +590,7 @@ fn checked_fields_reject_native_constructor_side_effects_and_preserve_live_value .value, pages ); + // 前面错误不应破坏活值/回调,合法 click 仍把 9 递增成 10 并反映到实际文字命令。 let updated = session .execute("button.click()", "app.main") .unwrap() @@ -558,6 +613,7 @@ fn checked_fields_reject_native_constructor_side_effects_and_preserve_live_value /// 把 Numeric 视觉引用替换为 Textual,旧 alias 随共享转发指向新对象。 /// 字段检查必须按新类型执行;合法字符串赋值通过,数字写入和返回错误类型的绑定均被拒绝。 fn checked_fields_follow_shared_block_forwarding_and_binding_writes() { + // alias 保留原包装身份,block 替换到不同字段类型子类后,后续字段校验应沿共享转发找真实新类型。 let (mut session, _) = ReplSession::load( r#" class Numeric: TextBlock { value: Number } @@ -575,6 +631,7 @@ page.render(block) session .execute(r#"block = Textual("new", "kept")"#, "app.main") .unwrap(); + // 旧 Numeric 类型不能成为绕过新 Textual 字符串字段契约的入口。 assert!(session.execute("alias.value = 42", "app.main").is_err()); assert_eq!( session.execute("alias.value", "app.main").unwrap().value, @@ -583,6 +640,7 @@ page.render(block) session .execute(r#"alias.value = "updated""#, "app.main") .unwrap(); + // 合法 alias 写入必须从 block 另一名字可见,证明并非复制一份独立字段存储。 assert_eq!( session.execute("block.value", "app.main").unwrap().value, r#""updated""# @@ -598,32 +656,39 @@ page.render(block) /// 在容器中间插入子项,检查新稳定槽、后继 y 变化及旧 Mount 身份保留。 /// 越界、负位置和自包含循环在修改前失败;移除新槽后旧出现位置仍有效。 fn positional_insert_preserves_existing_slots_and_mounts_and_rejects_invalid_graphs() { + // 先建 head/tail 两条稳定组成边,中间插入新节点应只为新边分配 slot,而不改旧边身份。 let source = r#"head=TextBlock("head") tail=TextBlock("tail") list=Column(24,8,head,tail) page=Page() page.render(list)"#; + // 保存初始完整几何,后续所有比较沿同一持久 VM,不重载源码制造看似相同的出现。 let (mut session, initial) = ReplSession::load(source, "app.main", 1, 200).unwrap(); session .execute("held=tail.mounts().at(0)", "app.main") .unwrap(); + // 从真实源 Mount 查询稳定 ID,插入后仍应对应同一 tail 出现,只改变位置。 let id = session .execute("held.id", "app.main") .unwrap() .value .parse::() .unwrap(); + // 旧 y 来自插入前发布帧,以便与新帧的同身份出现对比。 let old = initial .frame .mounts .iter() .find(|mount| mount.id == id) .unwrap(); + // 插入位置 1 与新 slot 2 故意不同,防止把顺序下标误当稳定组成身份。 let inserted = session .execute("slot=list.insert(1,TextBlock(\"middle\"))", "app.main") .unwrap(); assert_eq!(inserted.value, "2"); + // 成功结构编辑应产生完整新文档,而非只返回一个槽号却未安排刷新。 let document = inserted.document.unwrap(); + // 同 ID 在新帧仍存在,表示保留出现身份;其 y 增加证明父布局实际插入了中间孩子。 let new = document .frame .mounts @@ -643,6 +708,7 @@ fn positional_insert_preserves_existing_slots_and_mounts_and_rejects_invalid_gra "list.insert(0,list)", "list.insert(-1,head)", ] { + // 超出插入缝、将自身包含成环和负位置都应在写入组成前失败,不把整个 VM 标故障。 assert!(session.execute(invalid, "app.main").is_err()); assert!(!session.is_faulted()); } @@ -651,6 +717,7 @@ fn positional_insert_preserves_existing_slots_and_mounts_and_rejects_invalid_gra "true" ); session.execute("list.remove(slot)", "app.main").unwrap(); + // 删除新边使用返回的稳定 slot,而非插入位置 1,旧 tail 仍保持同一 ID。 assert_eq!( session .execute("tail.mounts().at(0).id", "app.main") @@ -664,6 +731,7 @@ fn positional_insert_preserves_existing_slots_and_mounts_and_rejects_invalid_gra /// 先同窗重排再跨窗移动,确认调用 Page 源覆盖且保留 Page 业务身份。 /// 跨窗目标帧版本不匹配必须拒绝;合法迁移后旧 Mount 失效,新窗口页面表指向原 Page。 fn tab_drop_preserves_page_identity_calls_source_methods_and_rejects_stale_targets() { + // 示例同时提供多个 Page 和独立窗口,Page 源覆盖把迁移/重排调用次数写进模型计数。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/tab-placement.endor"), "app.main", @@ -672,7 +740,9 @@ fn tab_drop_preserves_page_identity_calls_source_methods_and_rejects_stale_targe ) .unwrap(); session.take_window_commands().unwrap(); + // Tab ID 与 Page 对象/Mount ID 不同,输入在标签路径用 mount 字段携带标签稳定身份。 let page = initial.frame.tabs[0].id; + // 同窗插入缝 3 测向后移动时的下标修正,而不是把页面重新创建到列表末尾。 let input = crate::events::Input { window: 1, session: 201, @@ -692,6 +762,7 @@ fn tab_drop_preserves_page_identity_calls_source_methods_and_rejects_stale_targe session .execute("held=list.mounts().at(0)", "app.main") .unwrap(); + // 同窗标签重排不应卸载内容,提前保留当前内容 Mount 以区分重排和跨窗迁移。 let mount = session.execute("held.id", "app.main").unwrap().value; session.dispatch(&input).unwrap(); assert_eq!( @@ -712,6 +783,7 @@ fn tab_drop_preserves_page_identity_calls_source_methods_and_rejects_stale_targe .value, session.execute("first", "app.main").unwrap().value ); + // 第二步改为跨窗口目标,两端都采用各自最新发布版本,不因用错源版本误判迁移失败。 let input = crate::events::Input { layout_version: session.documents[&1].frame.layout_version, tab_drop: Some(crate::events::TabDrop { @@ -721,12 +793,14 @@ fn tab_drop_preserves_page_identity_calls_source_methods_and_rejects_stale_targe }), ..input }; + // 只改坏目标版本,源端仍有效,验证目标校验不可被源窗口身份通过所替代。 let mut stale = input.clone(); stale.tab_drop.as_mut().unwrap().layout_version += 1; assert!(!session.accepts_tab_drop(&stale)); assert!(session.dispatch(&stale).is_err()); assert!(!session.is_faulted()); session.dispatch(&input).unwrap(); + // 合法跨窗会调用 moveToWindow 与 moveTab,业务 Page 身份不变,但旧出现应被卸载重建到目标窗。 assert_eq!( session.execute("calls.value", "app.main").unwrap().value, "3" @@ -755,6 +829,7 @@ fn tab_drop_preserves_page_identity_calls_source_methods_and_rejects_stale_targe /// Page.moveToWindow 覆盖只返回 self,模拟源程序拒绝跨窗移动。 /// 拖放不能强行改变窗口归属;随后 detach 使用独立入口,并排出带负桌面坐标的原生命令。 fn drop_respects_declined_source_moves_and_detach_queues_signed_desktop_position() { + // moveToWindow 源覆盖只返回 self 而不实际移动,宿主不能因为回调无错误就假定迁移已经发生。 let source = r#"class Declining: Page { calls: Object function moveToWindow(self: Declining, window: Window): Page { self.calls.increment() return self } @@ -766,8 +841,10 @@ fn drop_respects_declined_source_moves_and_detach_queues_signed_desktop_position target=Page() target.render(TextBlock("target")) target.open(other)"#; + // 初始命令先排空,最后只观察本次 detach 新产生的 MoveTo,而不是启动残留窗口命令。 let (mut session, initial) = ReplSession::load(source, "app.main", 1, 202).unwrap(); session.take_window_commands().unwrap(); + // 目标副窗真实存在,但源覆盖拒绝移动后不应继续去重排那个无关窗口的其他页。 let mut input = crate::events::Input { window: 1, session: 202, @@ -803,11 +880,13 @@ fn drop_respects_declined_source_moves_and_detach_queues_signed_desktop_position .value, "1" ); + // detach 是独立创建窗口入口,清掉 drop 元数据并添加负桌面坐标,覆盖多显示器布局。 input.kind = "tab-detach".into(); input.tab_drop = None; input.screen_position = Some([-400, 120]); input.layout_version = session.documents[&1].frame.layout_version; session.dispatch(&input).unwrap(); + // 命令只登记不实际操作 OS;新资源应为窗口 3,坐标仍为有符号 -400/120。 let commands = session.take_window_commands().unwrap(); assert!(commands.iter().any(|command| command.window == 3 && command.action == crate::window::Action::MoveTo { x: -400, y: 120 })); @@ -825,7 +904,9 @@ fn drop_respects_declined_source_moves_and_detach_queues_signed_desktop_position fn with_file_task_input(contents: &str, run: impl FnOnce(&std::path::Path)) { // 只需唯一递增值,不依赖它同步其他内存,Relaxed 足以保证不同测试取到不同序号。 static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + // 每个调用取不同后缀,嵌套 old/new 文件测试也不覆盖同一路径。 let id = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + // 临时目录加 PID/序号只隔离测试文件,不从源模型或当前工作目录推断文件位置。 let path = std::env::temp_dir().join(format!("tessera-text-task-{}-{id}.txt", std::process::id())); // 将文件删除绑定到栈生命周期,避免测试提前失败时留下临时文件。 @@ -833,9 +914,11 @@ fn with_file_task_input(contents: &str, run: impl FnOnce(&std::path::Path)) { impl Drop for Cleanup { // 清理失败不再次 panic,避免覆盖原测试故障或在异常展开时二次崩溃。 fn drop(&mut self) { + // 若 provider 尚在关闭句柄或文件已被移除,最佳努力清理失败不应遮住原断言失败。 let _ = std::fs::remove_file(&self.0); } } + // 守卫必须在 run 之前创建,闭包 panic 时也随栈展开删除本例临时输入。 let _cleanup = Cleanup(path.clone()); std::fs::write(&path, contents).unwrap(); run(&path); @@ -843,6 +926,7 @@ fn with_file_task_input(contents: &str, run: impl FnOnce(&std::path::Path)) { /// 生成 Loader 测试程序:readText 成功回调把 Task.result 写入未挂载的 target。 /// 路径先按 JSON 字符串转义再插入 Endor,tail 用于附加替换/取消等测试操作。 fn file_task_source(path: &std::path::Path, tail: &str) -> String { + // 使用 JSON 字符串转义 Windows/Unix 路径中的斜杠和引号,避免把路径内容拼成 Endor 语法。 let path = serde_json::to_string(&path.to_string_lossy()).unwrap(); format!( "class Loader {{\n target: TextBlock\n task: Object\n function apply(self: Loader): Unit {{ self.target.text = self.task.result() }}\n}}\ntarget = TextBlock(\"waiting\")\nloader = Loader(target,ui.state(0))\npage = Page()\npage.render(TextBlock(\"target stays hidden\"))\nloader.task = ui.readText(loader,\"read\",{path},loader.apply)\n{tail}" @@ -851,7 +935,9 @@ fn file_task_source(path: &std::path::Path, tail: &str) -> String { /// 直接从当前 VM globals 找到 loader.task,按托管类型的方法表调用 status。 /// 不通过 REPL execute 查询,避免状态观察自身引入一次输入、刷新或任务调度副作用。 fn file_task_state(session: &mut ReplSession) -> String { + // 直接查同一个持久 VM 的真实 globals,不执行一条额外 Console 输入改变 transcript/刷新轮次。 let globals = session.candidate.globals.unwrap(); + // loader 是测试程序保存任务的持有者,字典仍拥有它,这里只借身份定位 task 属性。 let Value::Object(loader) = session .candidate .vm @@ -861,9 +947,11 @@ fn file_task_state(session: &mut ReplSession) -> String { else { panic!("loader"); }; + // 即使 Task 已终态也可由 loader 保留;不能从 provider 弱索引推断其状态。 let Value::Object(task) = session.candidate.vm.get_attr(loader, "task").unwrap() else { panic!("Task"); }; + // 查询实际 Task 类型方法,保持与源 task.status() 相同的受检查方法入口。 let definition = session .candidate .vm @@ -871,6 +959,7 @@ fn file_task_state(session: &mut ReplSession) -> String { .type_of(task) .unwrap() .unwrap(); + // lookup_method 取得未绑定方法,所以下面 call 显式补一个 Task receiver。 let method = session .candidate .vm @@ -878,6 +967,7 @@ fn file_task_state(session: &mut ReplSession) -> String { .lookup_method(definition, "status") .unwrap() .unwrap(); + // 返回值必须是语言字符串,状态接口若变成 Nil/对象不能被测试静默格式化成看似合法状态。 let Value::Text(status) = session .candidate .vm @@ -892,8 +982,10 @@ fn file_task_state(session: &mut ReplSession) -> String { /// 短暂休眠让后台文件线程获得执行机会;取消/失败也算终态,超时则明确使测试失败。 fn complete_file_task(session: &mut ReplSession) { for _ in 0..1000 { + // 后台只填 mailbox,必须显式让 owning VM poll 才能执行回调或完成无回调 Task。 session.poll_tasks().unwrap(); if file_task_state(session) != "pending" { + // 不只 Completed,Cancelled/Failed 也结束等待,具体预期由各调用测试单独断言。 return; } std::thread::sleep(std::time::Duration::from_millis(1)); @@ -905,11 +997,15 @@ fn complete_file_task(session: &mut ReplSession) { /// 推进完成后仅新 UTF-8 内容写入 target;target 仍无 Mount,说明业务更新不依赖可见性。 fn file_task_updates_hidden_object_and_replacement_drops_old_delivery() { with_file_task_input("old", |old| { + // 两个真实文件内容不同,才可从 target.text 判断究竟哪一代请求获得交付。 with_file_task_input("new UTF-8 文本", |new| { + // 路径先转义再作为源字符串,中文文本用于覆盖 UTF-8 返回而非仅 ASCII 情形。 let path = serde_json::to_string(&new.to_string_lossy()).unwrap(); + // 保留旧 token 后同 owner/key 再读新文件,替换必须即时取消旧项而不靠旧结果晚到顺序碰巧正确。 let tail = format!( "old = loader.task\nloader.task = ui.readText(loader,\"read\",{path},loader.apply)" ); + // 源加载只创建任务,complete_file_task 才在后续轮询交付,target 从未被挂到页面。 let (mut session, _) = ReplSession::load(&file_task_source(old, &tail), "app.main", 282, 1).unwrap(); complete_file_task(&mut session); @@ -937,6 +1033,7 @@ fn file_task_updates_hidden_object_and_replacement_drops_old_delivery() { /// 二者都不能运行成功回调;后者需保留错误文本但不使共享 VM fault,目标文字仍为 waiting。 fn cancelled_file_task_never_runs_callback_and_missing_file_keeps_vm_live() { with_file_task_input("ignored", |path| { + // 在同一输入创建并 cancel,后台即使已经读完也不能越过失效租约执行成功回调。 let (mut cancelled, _) = ReplSession::load( &file_task_source(path, "loader.task.cancel()"), "app.main", @@ -950,7 +1047,9 @@ fn cancelled_file_task_never_runs_callback_and_missing_file_keeps_vm_live() { cancelled.execute("target.text", "app.main").unwrap().value, "\"waiting\"" ); + // 另一个未创建的后缀路径用于 provider 真实失败,不伪造任务 error 字段。 let missing = path.with_extension("missing"); + // 新独立会话区分 provider 错误与前一例主动取消状态,错误不应停整个 VM。 let (mut failed, _) = ReplSession::load(&file_task_source(&missing, ""), "app.main", 284, 1).unwrap(); complete_file_task(&mut failed); @@ -974,10 +1073,13 @@ fn cancelled_file_task_never_runs_callback_and_missing_file_keeps_vm_live() { /// 确认 result 的托管保留不依赖成功回调,且 error 为空字符串。 fn callback_free_file_task_retains_result_after_completion() { with_file_task_input("callback free", |path| { + // 同一文件接口省略 callback,仅靠保留的 Task.result 接收文字,检查 await 风格 API 的存值语义。 let path = serde_json::to_string(&path.to_string_lossy()).unwrap(); + // Holder 只保存 token,页面展示无关文本;成功结果不能依赖 target 可见或回调消费才存活。 let source = format!( "class Holder {{ task: Object }}\nloader = Holder(ui.state(0))\npage = Page()\npage.render(TextBlock(\"file\"))\nloader.task = ui.readText(ui,\"read\",{path})" ); + // 实际 VM 管理 Task 的拥有图,后台线程从不直接调用 Loader 或写源字段。 let (mut session, _) = ReplSession::load(&source, "app.main", 285, 1).unwrap(); complete_file_task(&mut session); assert_eq!(file_task_state(&mut session), "completed"); @@ -1002,6 +1104,7 @@ fn callback_free_file_task_retains_result_after_completion() { /// 以隐藏 Block 为 owner,用相同 key 替换定时任务。 /// 旧任务立即取消,新回调仅在 poll 后写入 2;另一个被显式取消的任务不能再改变状态。 fn owned_tasks_replace_cancel_and_update_unmounted_objects() { + // hidden Block 没有 Mount 仍可作业务 owner,两个动作故意写不同数值以观察同键替换胜出者。 let source = r#"class Action { state: Object value: Number @@ -1015,6 +1118,7 @@ fn owned_tasks_replace_cancel_and_update_unmounted_objects() { page.render(ui.textOf(state,"value")) old = ui.after(hidden,"load",0,first.apply) next = ui.after(hidden,"load",0,latest.apply)"#; + // 创建任务本身不交付,先看旧 status 和初始 0,再 poll 验证只有最新动作写 2。 let (mut session, _) = ReplSession::load(source, "app.main", 1, 190).unwrap(); assert_eq!( session.execute("old.status()", "app.main").unwrap().value, @@ -1040,6 +1144,7 @@ fn owned_tasks_replace_cancel_and_update_unmounted_objects() { ) .unwrap(); session.poll_tasks().unwrap(); + // 被主动 cancel 的第三任务不能覆盖此前完成结果,token.active 也必须投影为 false。 assert_eq!( session.execute("state.value", "app.main").unwrap().value, "2" @@ -1057,6 +1162,7 @@ fn owned_tasks_replace_cancel_and_update_unmounted_objects() { /// 并列创建 Page/Mount/Block/ui 作用域任务,再关闭并重开页面。 /// 页面与出现位置任务取消,业务对象和应用任务继续;跨窗迁移保留 Page 作用域但取消旧 Mount,关窗取消窗口任务。 fn tab_and_mount_tasks_cancel_while_block_and_app_owners_continue() { + // 相同 Action/共享 count 给不同 owner 类型建任务,计数差异直接揭示哪些作用域还获得交付资格。 let source = r#"class Action { state: Object function apply(self: Action): Unit { self.state.increment() } @@ -1066,6 +1172,7 @@ fn tab_and_mount_tasks_cancel_while_block_and_app_owners_continue() { leaf=TextBlock("owner") page=Page() page.render(leaf)"#; + // 先发布 leaf 的真实出现,再从源 mounts() 获取具体 owner,不能手写一个未挂载 Mount。 let (mut session, _) = ReplSession::load(source, "app.main", 1, 191).unwrap(); session .execute( @@ -1080,6 +1187,7 @@ fn tab_and_mount_tasks_cancel_while_block_and_app_owners_continue() { ) .unwrap(); for name in ["pageTask", "mountTask"] { + // close 后立刻 open 不应复活旧资格;页面与旧出现的任务都已在关闭边界被取消。 assert_eq!( session .execute(&format!("{name}.status()"), "app.main") @@ -1089,6 +1197,7 @@ fn tab_and_mount_tasks_cancel_while_block_and_app_owners_continue() { ); } session.poll_tasks().unwrap(); + // 只有 Block/ui 两个 owner 仍有效,count=2 同时排除错误地取消所有后台工作或全部继续的实现。 assert_eq!( session.execute("state.value", "app.main").unwrap().value, "2" @@ -1121,6 +1230,7 @@ fn tab_and_mount_tasks_cancel_while_block_and_app_owners_continue() { "app.main", ) .unwrap(); + // 窗口 owner 关闭即失效,即使源变量 other 还保留真实窗口对象也不能继续回调。 session.poll_tasks().unwrap(); assert_eq!( session @@ -1135,6 +1245,7 @@ fn tab_and_mount_tasks_cancel_while_block_and_app_owners_continue() { /// 只返回任务令牌而不保留临时 owner,检查弱作用域允许 owner 回收并取消任务。 /// 随后第一个回调失败应停止共享执行域,后续递增不发生;通过 VM 直接读值验证状态仍为 0。 fn orphan_task_scope_is_collectable_and_callback_failure_stops_remaining_work() { + // orphan 只返回 Task,owner 无外部根;后半段先排失败回调再排递增,检查共享故障域是否停止后续工作。 let source = r#"class Action { state: Object function apply(self: Action): Unit { self.state.increment() } @@ -1149,6 +1260,7 @@ fn orphan_task_scope_is_collectable_and_callback_failure_stops_remaining_work() page=Page() page.render(TextBlock("preserve")) token=orphan()"#; + // 加载后的回收边界应剪掉不可达 owner/作用域环,token 本身不反向强持有 owner。 let (mut session, _) = ReplSession::load(source, "app.main", 1, 192).unwrap(); assert_eq!( session.execute("token.active()", "app.main").unwrap().value, @@ -1162,7 +1274,9 @@ fn orphan_task_scope_is_collectable_and_callback_failure_stops_remaining_work() session.execute("broken=ui.after(ui,\"fail\",0,action.fail)\nlater=ui.after(ui,\"later\",0,action.apply)","app.main").unwrap(); assert!(session.poll_tasks().is_err()); assert!(session.is_faulted()); + // 故障域已拒绝 execute,直接只读 VM 属性验证值仍为 0,而不为了观察又执行用户代码。 let globals = session.candidate.globals.unwrap(); + // 原共享状态对象仍由 globals 持有;读取它不创建新根或恢复后续被停用的任务。 let state = match session .candidate .vm @@ -1185,6 +1299,7 @@ fn orphan_task_scope_is_collectable_and_callback_failure_stops_remaining_work() /// 验证源函数、原生函数和绑定方法属于 Function,而类型构造器不属于 Function。 /// 错误参数在函数体副作用前拒绝,错误返回在返回契约检查时拒绝;重定义同名类也不能改变旧实例/方法身份。 fn source_annotations_classify_functions_and_reject_before_body() { + // 示例同时含源函数、宿主工厂和绑定方法,类型对象虽可构造但不是 Function,需分别测试。 let (mut session, _) = ReplSession::load( include_str!("../../../examples/function-types.endor"), "app.main", @@ -1197,6 +1312,7 @@ fn source_annotations_classify_functions_and_reject_before_body() { "isInstance(ui.rect,Function)", "isInstance(actions.read,Function)", ] { + // 三种真实 callable 都应满足同一个 Function 名义契约,不用是否有某个同名属性做鸭子判断。 assert_eq!( session.execute(expression, "app.main").unwrap().value, "true" @@ -1215,6 +1331,7 @@ fn source_annotations_classify_functions_and_reject_before_body() { "app.main", ) .unwrap(); + // 参数错误必须在进入 checked 的 increment 之前拒绝,因此紧接着断言 state 仍为 0。 let error = session .execute("checked(\"wrong\")", "app.main") .err() @@ -1234,6 +1351,7 @@ fn source_annotations_classify_functions_and_reject_before_body() { session .execute("function wrong(): Number { return \"wrong\" }", "app.main") .unwrap(); + // 错误返回发生在函数体正常跑完之后的返回契约检查,消息应和参数错误有所区分。 let error = session.execute("wrong()", "app.main").err().unwrap(); assert!( error.to_string().contains("return expects Number"), @@ -1250,6 +1368,7 @@ fn source_annotations_classify_functions_and_reject_before_body() { "app.main", ) .unwrap(); + // 重定义名字只建立新 Type,不改变旧实例 actions 与此前 savedFunction 的真实身份/行为。 assert_eq!( session .execute("callNumber(savedFunction)", "app.main") @@ -1275,6 +1394,7 @@ fn source_annotations_classify_functions_and_reject_before_body() { /// 先由子窗口按钮回调制造运行时故障,再从宿主回收该窗口。 /// Mount 和页面根必须脱离,onUnmount 的 marker 不可递增;已停止 VM 不能因清理重新执行源代码。 fn stopped_window_teardown_detaches_mounts_without_running_source_hooks() { + // marker 只在 onUnmount 增长,子窗 click 另触发非法 resize 故障,用两条独立状态观察纯宿主退役。 let source = r#"class WatchedPage: Page { marker: Object function onUnmount(self: WatchedPage, mount: Mount): Unit { self.marker.increment() } @@ -1292,11 +1412,14 @@ fn stopped_window_teardown_detaches_mounts_without_running_source_hooks() { page=WatchedPage(marker) page.render(button) page.open(other)"#; + // 保存副窗发布帧和实际持久堆,故障后不重新加载一份“已经清理好”的模拟域。 let (mut session, initial) = ReplSession::load(source, "app.main", 1, 140).unwrap(); session .execute("held=button.mounts().at(0)", "app.main") .unwrap(); + // 故障后只能只读观察真实对象,不能经 execute 调用户函数来检查清理结果。 let globals = session.candidate.globals.unwrap(); + // lookup 仅从原 globals 借出对象身份,持有关系没有被测试添加新的长期根改变。 let lookup = |session: &ReplSession, name: &str| match session .candidate .vm @@ -1307,9 +1430,13 @@ fn stopped_window_teardown_detaches_mounts_without_running_source_hooks() { Value::Object(object) => object, _ => panic!("object"), }; + // held 故意保留旧叶 Mount,退役必须使它 mounted=false,而不能仅把它从窗口显示列表删去。 let held = lookup(&session, "held"); + // 真实窗口资源用于检查 Page 根是否解除拥有关系,和文档副本是否删窗分别验证。 let window = lookup(&session, "other"); + // marker 保持零证明故障清理没有重新进入 onUnmount 源代码。 let marker = lookup(&session, "marker"); + // 用目标 payload 的实际几何 ID 构造输入,当前 session/副窗版本来自初始发布值。 let mount = session .candidate .vm @@ -1334,6 +1461,7 @@ fn stopped_window_teardown_detaches_mounts_without_running_source_hooks() { .is_err() ); assert!(session.is_faulted()); + // 专用 retire_window 不调用源 Window.close/卸载钩子;正常生命周期与故障资源清理不能混为一路。 session.retire_window(2).unwrap(); assert!(!session.accepts_window(2)); assert!( @@ -1360,6 +1488,7 @@ fn stopped_window_teardown_detaches_mounts_without_running_source_hooks() { /// 加载多窗口示例,确认窗口共享业务计数但使用不重叠的 Mount。 /// 迁移保留 Page 身份、替换旧 Mount;关闭并清除全局引用后 Window 可回收,保留旧叶 Mount 也不能留住窗口上下文。 fn native_windows_share_business_state_move_pages_and_release_closed_contexts() { + // 真实多窗口示例在同一个 VM 共享 count,每窗只派生独立 Presentation/Mount,而非复制业务模型。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/windows.endor"), "app.main", @@ -1368,6 +1497,7 @@ fn native_windows_share_business_state_move_pages_and_release_closed_contexts() ) .unwrap(); assert_eq!(initial.windows.len(), 1); + // 全会话出现 ID 高水位应避免不同窗重号,防止输入凭窗口/出现值误指到另一展示。 let main_ids: std::collections::BTreeSet<_> = initial.frame.mounts.iter().map(|mount| mount.id).collect(); assert!( @@ -1378,11 +1508,13 @@ fn native_windows_share_business_state_move_pages_and_release_closed_contexts() .all(|mount| !main_ids.contains(&mount.id)) ); assert_eq!(initial.windows[&2].frame.session, initial.frame.session); + // 同一共享 count 更新应在两个窗的完整文档里同时看到新文字,而不是只刷新 current。 let changed = session .execute("count.increment()", "app.main") .unwrap() .document .unwrap(); + // 仅过滤实际文字命令判断状态投影,不从局部 ui.stats 或源 state 对象推断画面已同步。 let has_one = |frame: &crate::document::Frame| { frame .commands @@ -1393,7 +1525,9 @@ fn native_windows_share_business_state_move_pages_and_release_closed_contexts() session .execute("oldRight = rightButton.mounts().at(0)", "app.main") .unwrap(); + // 记录 Page 的 Console 对象身份表示,迁移后必须仍为同一个业务页。 let page = session.execute("right", "app.main").unwrap().value; + // 正常源方法迁移到主窗,旧副窗 Page 表清空,新 Mount 应在新上下文重建。 let moved = session .execute("right.moveToWindow(ui.window())", "app.main") .unwrap() @@ -1409,7 +1543,9 @@ fn native_windows_share_business_state_move_pages_and_release_closed_contexts() "1" ); assert!(session.execute("oldRight.bounds()", "app.main").is_err()); + // 从真实全局取得副窗身份,创建弱观察句柄后删除原全局强边以检验资源可回收性。 let globals = session.candidate.globals.unwrap(); + // 读取不额外 retain Window,避免测试自己保活对象而掩盖/制造 GC 结论。 let Value::Object(window) = session .candidate .vm @@ -1419,7 +1555,9 @@ fn native_windows_share_business_state_move_pages_and_release_closed_contexts() else { panic!("Window"); }; + // 弱身份只用于回收后探测,不能因为闭窗时仍有 Rust ObjectRef 数值就延长寿命。 let weak = session.candidate.vm.downgrade(window).unwrap(); + // 关闭后的最终完整文档应删除副窗,向已关闭资源 open 也必须被拒绝。 let closed = session .execute("other.close()", "app.main") .unwrap() @@ -1434,6 +1572,7 @@ fn native_windows_share_business_state_move_pages_and_release_closed_contexts() .unwrap(); session.execute("0", "app.main").unwrap(); session.candidate.vm.collect_cycles(); + // oldRight 仍可达不应通过出现的旧上下文反向保留整个 Window/desktop/Page 注册表。 assert!(session.candidate.vm.upgrade(weak).unwrap().is_none()); // 外部仍持有旧叶 Mount 时,关闭窗口的上下文也必须可释放;下一次 detach 创建新的资源编号。 let detached = session @@ -1461,6 +1600,7 @@ fn native_windows_share_business_state_move_pages_and_release_closed_contexts() /// 一次输入先关闭子窗口,再用非法 resize 使后续语句失败。 /// 先前关闭副作用仍存在,下一次成功输入必须清除残留展示;Page 可重新打开到主窗口。 fn failed_input_after_window_close_cannot_leave_owned_mounts_in_closed_context() { + // 从真实多窗堆开始,输入前一条 close 成功、后一条 resize 失败,验证 REPL 非事务语义的恢复。 let (mut session, _) = ReplSession::load( include_str!("../../../examples/windows.endor"), "app.main", @@ -1474,6 +1614,7 @@ fn failed_input_after_window_close_cannot_leave_owned_mounts_in_closed_context() .is_err() ); assert!(!session.accepts_window(2)); + // 下一次成功查询触发必要修复/发布,关闭副作用不回滚,旧窗也不能在缓存文档中残留。 let repaired = session.execute("right.window()", "app.main").unwrap(); assert_eq!(repaired.value, "nil"); assert!(repaired.document.unwrap().windows.is_empty()); @@ -1487,6 +1628,7 @@ fn failed_input_after_window_close_cannot_leave_owned_mounts_in_closed_context() session .execute("right.open(ui.window())", "app.main") .unwrap(); + // 已清理 Page 仍可按业务身份重开到主窗口,不能把正常关闭误当整个 Page 值被永久销毁。 assert_eq!( session .execute("right.window().id()", "app.main") @@ -1500,16 +1642,19 @@ fn failed_input_after_window_close_cannot_leave_owned_mounts_in_closed_context() /// 依次通过事件激活页面、修改 title、关闭页面、清空及重开。 /// 检查标签反映真实 Page 方法,稳定业务 ID 与递增展示 ID 各自正确,旧版本事件被桥接层拒绝。 fn tab_projection_uses_page_methods_and_rejects_old_presentations() { + // 页面标题/打开顺序来自真实 Window 注册表,最后一次 render 使 second 初始选中。 let source = r#"first = Page() first.title = "First" first.render(TextBlock("one")) second = Page() second.title = "Second" second.render(TextBlock("two"))"#; + // 保存初始 Tab ID 和版本供后续重命名/重开/过期输入比较,不按标题作为身份。 let (mut session, initial) = ReplSession::load(source, "app.main", 120, 1).unwrap(); assert_eq!(initial.frame.tabs.len(), 2); assert_eq!(initial.frame.tabs[0].title, "First"); assert!(initial.frame.tabs[1].active); + // 标签分派用 mount 字段承载 Tab ID,kind 明确为 tab-activate,不能误入内容几何命中。 let input = crate::events::Input { window: crate::window::MAIN_WINDOW, session: initial.frame.session, @@ -1522,6 +1667,7 @@ fn tab_projection_uses_page_methods_and_rejects_old_presentations() { tab_drop: None, screen_position: None, }; + // 真实页面 activate 切换选中投影并推进版本,随后同一输入应由桥接层拒绝。 let selected = session.dispatch(&input).unwrap().document.unwrap(); assert!(selected.frame.tabs[0].active); assert!(selected.frame.layout_version > initial.frame.layout_version); @@ -1532,6 +1678,7 @@ fn tab_projection_uses_page_methods_and_rejects_old_presentations() { .dispatch(&mut session.candidate.vm, &input) .is_err() ); + // 只改 title 不改 Page 身份,标签文字更新但第一页原稳定 Tab ID 保持。 let renamed = session .execute(r#"second.title = "Renamed""#, "app.main") .unwrap() @@ -1539,6 +1686,7 @@ fn tab_projection_uses_page_methods_and_rejects_old_presentations() { .unwrap(); assert_eq!(renamed.frame.tabs[1].title, "Renamed"); assert_eq!(renamed.frame.tabs[0].id, initial.frame.tabs[0].id); + // 按最新版本关闭 second,注册关系和焦点选择应同步到第一页,不使用静态 sidebar 假数据。 let closed = session .dispatch(&crate::events::Input { window: crate::window::MAIN_WINDOW, @@ -1564,6 +1712,7 @@ fn tab_projection_uses_page_methods_and_rejects_old_presentations() { .value, "nil" ); + // 最后一页关闭也必须发布版本更高的空标签帧,不能把 Some(None) 当作无刷新工作。 let empty = session .execute("first.close()", "app.main") .unwrap() @@ -1571,6 +1720,7 @@ fn tab_projection_uses_page_methods_and_rejects_old_presentations() { .unwrap(); assert!(empty.frame.tabs.is_empty()); assert!(empty.frame.layout_version > closed.frame.layout_version); + // 相同 Page 重开分配新展示 Tab ID,历史旧输入不能因业务对象相同再次变成有效。 let reopened = session .execute("second.open()", "app.main") .unwrap() @@ -1584,6 +1734,7 @@ fn tab_projection_uses_page_methods_and_rejects_old_presentations() { /// 同次成功输入的两次 resize 合并为最后尺寸,并保留 title/focus 命令。 /// 命令只消费一次;失败输入之前积累的 resize 也必须丢弃,不能送到原生窗口。 fn managed_window_requests_are_coalesced_and_failed_input_discards_pending_requests() { + // 空持久会话已有托管主 Window,命令登记不需要先 render 页面,也不在测试实际打开 OS 窗口。 let mut session = ReplSession::new(111).unwrap(); session .execute( @@ -1595,6 +1746,7 @@ fn managed_window_requests_are_coalesced_and_failed_input_discards_pending_reque "app.main", ) .unwrap(); + // 一次取完成功输入命令,两个 Resize 合并为最后一个,title/focus 保留独立动作顺序。 let requests = session.take_window_commands().unwrap(); assert_eq!(requests.len(), 3); assert!(matches!( @@ -1606,6 +1758,7 @@ fn managed_window_requests_are_coalesced_and_failed_input_discards_pending_reque )); assert!(matches!(&requests[1].action,crate::window::Action::SetTitle(title) if title=="Endor")); assert!(session.take_window_commands().unwrap().is_empty()); + // 输入先排合法 resize 再遇非法尺寸,待发布 outbox 整批丢弃,不能泄漏前半条原生命令。 assert!( session .execute("window.resize(1400,900)\nwindow.resize(0,600)", "app.main") @@ -1620,11 +1773,13 @@ fn managed_window_requests_are_coalesced_and_failed_input_discards_pending_reque /// 检查 Window.pages 真实持有打开页面,close 解除归属,重新 open 追加到当前顺序末尾。 /// 页面窗口关系保持双向一致,向非 Window 对象打开则明确失败。 fn window_page_roots_follow_open_close_and_creation_order() { + // 创建顺序与 render/open 登记关系明确分开,Page 存活不代表永远属于窗口页面表。 let source = r#"first = Page() second = Page() first.render(TextBlock("first")) second.render(TextBlock("second")) window = ui.window()"#; + // 所有查询保留同一真实 globals,close/open 后的窗口关系必须从资源模型更新而来。 let (mut session, _) = ReplSession::load(source, "app.main", 112, 1).unwrap(); assert_eq!( session @@ -1633,6 +1788,7 @@ fn window_page_roots_follow_open_close_and_creation_order() { .value, "2" ); + // 两页应指同一 Window;保存显示身份进行比较,不用标题或数组顺序猜归属。 let first = session.execute("first.window()", "app.main").unwrap().value; assert_eq!( first, @@ -1654,6 +1810,7 @@ fn window_page_roots_follow_open_close_and_creation_order() { "1" ); session.execute("first.open(window)", "app.main").unwrap(); + // 重开追加到注册表末尾,second 因此仍在 at(0),而不是按最初创建顺序强行插回 first。 assert_eq!( session .execute("window.pages().count", "app.main") @@ -1675,6 +1832,7 @@ fn window_page_roots_follow_open_close_and_creation_order() { /// 为 Page 建立弱句柄,close 后删除唯一全局绑定并运行循环回收。 /// 弱升级应失败,证明窗口的页面顺序记录不会把已关闭页面意外作为强根保留。 fn closed_page_is_not_kept_alive_by_window_page_order() { + // 简单页面保证唯一显式根就是全局 page;关闭+删绑定后窗口的顺序映射不得成为隐藏强根。 let (mut session, _) = ReplSession::load( "page = Page()\npage.render(TextBlock(\"page\"))", "app.main", @@ -1682,7 +1840,9 @@ fn closed_page_is_not_kept_alive_by_window_page_order() { 1, ) .unwrap(); + // 直接删 globals 避免用“page=nil”产生别名替换语义干扰这个生命周期断言。 let globals = session.candidate.globals.unwrap(); + // 借出身份后只建弱观察,不在测试手工 retain 新拥有根。 let Value::Object(page) = session .candidate .vm @@ -1692,6 +1852,7 @@ fn closed_page_is_not_kept_alive_by_window_page_order() { else { panic!("Page") }; + // close 解除 Window→Page 边,删除全局再收环,弱升级失败才证明没有意外保留。 let weak = session.candidate.vm.downgrade(page).unwrap(); session.execute("page.close()", "app.main").unwrap(); session @@ -1707,6 +1868,7 @@ fn closed_page_is_not_kept_alive_by_window_page_order() { /// 源 measure 内尝试 resize 原生窗口,加载应报告 read-only。 /// 窗口命令也属于副作用,不能因其延后执行而绕过布局只读保护。 fn rendering_cannot_enqueue_native_window_side_effects() { + // measure 返回值本身合法,唯一违规是排入延后 Resize,证明 outbox 也是受只读保护的副作用。 let source = r##"class BadRect: RectBlock { function measure(self: BadRect, mount: Mount, constraints: Constraints): MeasureResult { ui.window().resize(900,600) @@ -1715,6 +1877,7 @@ fn rendering_cannot_enqueue_native_window_side_effects() { } page = Page() page.render(BadRect(80,20,0,"#DDEEFF"))"##; + // 真实加载会运行 source measure,在候选发布前发现错误,不能等 OS 执行命令时才拒绝。 let error = ReplSession::load(source, "app.main", 114, 1).err().unwrap(); assert!(error.to_string().contains("read-only")); } @@ -1722,6 +1885,7 @@ fn rendering_cannot_enqueue_native_window_side_effects() { /// 直接调用 ui.stats 取得某个数字计数,读取后释放返回的 stats 托管对象。 /// 辅助函数避免经 REPL 查询统计带来额外输入/刷新,使缓存命中与测量次数的断言可比较。 fn source_measure_stat(session: &mut ReplSession, name: &str) -> i64 { + // 布局/缓存回归共用此直接 VM 助手,绕开 Console transcript 和一次输入引起的额外刷新。 let Value::Object(function) = session .candidate .vm @@ -1730,9 +1894,11 @@ fn source_measure_stat(session: &mut ReplSession, name: &str) -> i64 { else { panic!("stats function") }; + // 返回 stats 对象有新的拥有根,读完数字字段必须显式释放,不能让观察指标自身泄漏。 let Value::Object(stats) = session.candidate.vm.call(function, &[]).unwrap() else { panic!("stats") }; + // 要求确为 Number,不能将缺失字段/错误 API 值格式化成零而让缓存断言误通过。 let Value::Number(value) = session.candidate.vm.get_attr(stats, name).unwrap() else { panic!("stat number") }; @@ -1742,7 +1908,9 @@ fn source_measure_stat(session: &mut ReplSession, name: &str) -> i64 { /// 从 globals 中按名称找到业务 Block,再在给定完整文档中按 block_id 找对应 Mount。 /// 构造携带当前会话与该文档版本的 click,返回派发后发布的新文档,供后续动作沿新版本继续。 fn click_named(session: &mut ReplSession, document: &RenderDocument, name: &str) -> RenderDocument { + // 缓存示例测试通过此助手模拟按钮点击;globals 是当前 VM 的业务对象名字表。 let globals = session.candidate.globals.unwrap(); + // 按调用方给出的名字取得 Block 引用;缺失或非对象表示测试夹具已与按钮约定不符。 let Value::Object(block) = session .candidate .vm @@ -1752,12 +1920,15 @@ fn click_named(session: &mut ReplSession, document: &RenderDocument, name: &str) else { panic!("Block") }; + // 将业务 Block 对应到当前文档的出现位置;本助手适用于这些按钮只有一个 Mount 的夹具。 let mount = document .frame .mounts .iter() .find(|mount| mount.block_id == block.to_string()) .unwrap(); + // 使用当前 session/layout_version 派发,避免复用旧文档造成过期事件被丢弃。 + // 不提供坐标,直接验证指定按钮的 click 回调;要求返回新文档供下一次点击使用。 session .dispatch(&crate::events::Input { window: crate::window::MAIN_WINDOW, @@ -1780,6 +1951,7 @@ fn click_named(session: &mut ReplSession, document: &RenderDocument, name: &str) /// 同一个源 paint 对象出现在两个窗口,先执行与显示无关的表达式。 /// 无关输入应不产生文档;修改 paint 实际读取的 tint 后,两个窗口都必须发布新颜色。 fn shared_intrinsic_desktop_does_not_repaint_other_windows_on_repl_input() { + // 同一 Painted 实例挂到两个窗口,paint 读取共享 tint,建立跨窗口的字段依赖。 let (mut session, _) = ReplSession::load( r##" class Painted: RectBlock { @@ -1803,6 +1975,7 @@ page2.moveToWindow(window2) 1, ) .unwrap(); + // 执行不读写业务对象的表达式,检查 worker 不为无关 REPL 输入重新发布桌面。 assert!( session .execute("42", "app.main") @@ -1810,14 +1983,17 @@ page2.moveToWindow(window2) .document .is_none() ); + // 修改 paint 实际读取的字段;返回的桌面文档应同时包含两处更新。 let changed = session .execute("item.tint = \"#3868D9\"", "app.main") .unwrap() .document .unwrap(); + // 主窗口的矩形命令必须采用新颜色,不能只检查有文档发布。 assert!(changed.frame.commands.iter().any(|command| matches!( command, RenderCommand::RoundedRect { color, .. } if color == "#3868D9" ))); + // 再核对第二窗口,捕获只刷新当前窗口而遗漏共享对象另一出现位置的问题。 assert!( changed.windows[&2] .frame @@ -1833,6 +2009,7 @@ page2.moveToWindow(window2) /// 加载缓存示例并用真实 click 分别改变颜色与尺寸。 /// 纯颜色更新复用全部测量,尺寸依赖变化只让受影响的结果失效;按布局 pass 数核对命中而非写死单次计数。 fn source_measure_cache_reuses_independent_results_and_invalidates_model_changes() { + // 以固定视口加载真实缓存示例;CachedRect 和 ViewportBand 分别提供可缓存的源测量。 let (mut session, initial) = ReplSession::load_with_viewport( include_str!("../../../examples/layout-cache.endor"), "app.main", @@ -1844,18 +2021,24 @@ fn source_measure_cache_reuses_independent_results_and_invalidates_model_changes }), ) .unwrap(); + // 初始两项源测量均需执行;后面的统计由每次更新产生,检查更新本身的复用情况。 assert_eq!(source_measure_stat(&mut session, "sourceMeasureMisses"), 2); + // 调用上面的事件助手触发颜色按钮;事件路径与正常 UI 输入相同。 let painted = click_named(&mut session, &initial, "blue"); + // 核对颜色已变化,排除因按钮未生效而导致的“没有重新测量”。 assert!(painted.frame.commands.iter().any( |command| matches!(command,RenderCommand::RoundedRect {color,..} if color=="#526AC7") )); + // 同一次更新可能经历多个布局 pass;每个 pass 都应命中两项测量,实际重测数应为零。 let passes = source_measure_stat(&mut session, "layoutPasses"); assert_eq!( source_measure_stat(&mut session, "sourceMeasureHits"), 2 * passes ); assert_eq!(source_measure_stat(&mut session, "measured"), 0); + // 接着沿新文档点击尺寸按钮,改动 CachedRect.measure 读取的宽度模型。 let resized = click_named(&mut session, &painted, "expand"); + // 检查依赖更新已反映为 260×60 的矩形几何。 assert!( resized .frame @@ -1863,6 +2046,7 @@ fn source_measure_cache_reuses_independent_results_and_invalidates_model_changes .iter() .any(|mount| mount.width == 260.0 && mount.height == 60.0) ); + // 此次只有一项测量失效一次;其余 pass/对象仍命中,因此总命中数为 2×pass−1。 let passes = source_measure_stat(&mut session, "layoutPasses"); assert_eq!( source_measure_stat(&mut session, "sourceMeasureHits"), @@ -1875,6 +2059,7 @@ fn source_measure_cache_reuses_independent_results_and_invalidates_model_changes /// 新建尚未 render 的 Console VM,执行普通表达式和 resize。 /// 两者都不应产生发布文档,避免把 reset 后保留的画面替换成空白。 fn viewport_updates_in_a_fresh_console_do_not_replace_the_preserved_page() { + // 构造未执行 page.render 的新会话,用来复现 Console reset 后仍保留旧画面的情形。 let mut session = ReplSession::new_with_viewport( 104, Some(crate::layout::Size { @@ -1883,6 +2068,7 @@ fn viewport_updates_in_a_fresh_console_do_not_replace_the_preserved_page() { }), ) .unwrap(); + // 普通表达式没有新页面,返回值不能携带空白 RenderDocument。 assert!( session .execute("42", "app.main") @@ -1890,6 +2076,7 @@ fn viewport_updates_in_a_fresh_console_do_not_replace_the_preserved_page() { .document .is_none() ); + // 原生 resize 更新视口状态,但没有页面可发布时仍应返回 None。 assert!( session .resize(Some(crate::layout::Size { @@ -1899,6 +2086,7 @@ fn viewport_updates_in_a_fresh_console_do_not_replace_the_preserved_page() { .unwrap() .is_none() ); + // 读取 VM 暴露的视口宽度,证明 resize 已生效而非被直接忽略;查询也不产生文档。 let result = session.execute("ui.viewport().width", "app.main").unwrap(); assert_eq!(result.value, "360"); assert!(result.document.is_none()); @@ -1908,6 +2096,7 @@ fn viewport_updates_in_a_fresh_console_do_not_replace_the_preserved_page() { /// 源 measure 返回先前已创建的 MeasureResult,不在调用期间新建结果。 /// 直接改其 width 后刷新必须失效并更新相同 Mount,证明返回值解码读取也进入依赖;再次刷新保持稳定。 fn source_measure_cache_tracks_fields_of_an_existing_returned_result() { + // measure 直接返回全局已有结果;用此夹具验证解码结果字段时也记录依赖。 let source = r##"class HeldRect: RectBlock { result: MeasureResult function measure(self: HeldRect, mount: Mount, constraints: Constraints): MeasureResult { return self.result } @@ -1916,7 +2105,9 @@ fn source_measure_cache_tracks_fields_of_an_existing_returned_result() { rect = HeldRect(80,20,0,"#DDEEFF",result) page = Page() page.render(rect)"##; + // 首次发布建立 width=80 的测量缓存,随后绕过 REPL 直接写堆字段。 let (mut session, initial) = ReplSession::load(source, "app.main", 103, 1).unwrap(); + // 记住原出现位置 ID;宽度变更必须更新该 Mount,而不是新建另一个来掩盖缓存问题。 let id = initial .frame .mounts @@ -1924,7 +2115,9 @@ fn source_measure_cache_tracks_fields_of_an_existing_returned_result() { .find(|mount| mount.width == 80.0) .unwrap() .id; + // 从业务全局表提取 result 对象,与 measure 返回的引用保持一致。 let globals = session.candidate.globals.unwrap(); + // 要求夹具中的 result 确实是 VM 对象,便于通过 set_attr 触发写入观察。 let Value::Object(result) = session .candidate .vm @@ -1934,11 +2127,13 @@ fn source_measure_cache_tracks_fields_of_an_existing_returned_result() { else { panic!("result") }; + // 仅改已有返回对象的 width;源函数本体未读取该字段,依赖应来自返回值解码。 session .candidate .vm .set_attr(result, "width", Value::Number(140.into())) .unwrap(); + // 主动刷新消费字段变化,再检查同一 Mount 的尺寸及恰好一次缓存失效。 let next = session.refresh_document().unwrap().unwrap(); assert!( next.frame @@ -1947,6 +2142,7 @@ fn source_measure_cache_tracks_fields_of_an_existing_returned_result() { .any(|mount| mount.id == id && mount.width == 140.0) ); assert_eq!(source_measure_stat(&mut session, "sourceMeasureMisses"), 1); + // 再次刷新没有新写入,应保持缓存和已发布文档稳定。 assert!(session.refresh_document().unwrap().is_none()); } @@ -1954,6 +2150,7 @@ fn source_measure_cache_tracks_fields_of_an_existing_returned_result() { /// 在有限窗口约束下加载缓存示例,再缩窄真实可用视口。 /// 原 Mount ID 不变,内容宽度按根 padding 改变,且输入计数仍为 0;重复尺寸不发布,NaN 尺寸失败但不停止 VM。 fn viewport_resize_changes_constraints_and_preserves_mount_identity_without_source_input() { + // 固定初始视口,让示例的 ViewportBand 建立对 ui.viewport().width 的测量依赖。 let (mut session, initial) = ReplSession::load_with_viewport( include_str!("../../../examples/layout-cache.endor"), "app.main", @@ -1973,7 +2170,9 @@ fn viewport_resize_changes_constraints_and_preserves_mount_identity_without_sour .iter() .any(|mount| mount.width == 752.0 && mount.height == 24.0) ); + // 保存完整 Mount 顺序和身份,后续检查 resize 只更新几何而不重建出现位置。 let ids: Vec<_> = initial.frame.mounts.iter().map(|mount| mount.id).collect(); + // 模拟原生窗口缩小;该入口应更新布局约束,不执行一条新的 Endor 用户输入。 let document = session .resize(Some(crate::layout::Size { width: 360.0, @@ -1981,6 +2180,7 @@ fn viewport_resize_changes_constraints_and_preserves_mount_identity_without_sour })) .unwrap() .unwrap(); + // 逐项比较原 Mount ID,捕获 resize 导致生命周期重建或排序改变的问题。 assert_eq!( ids, document @@ -1990,6 +2190,7 @@ fn viewport_resize_changes_constraints_and_preserves_mount_identity_without_sour .map(|mount| mount.id) .collect::>() ); + // 新宽度 360 扣除左右各 24 的 padding,应发布 312 的内容宽度。 assert!( document .frame @@ -1997,6 +2198,7 @@ fn viewport_resize_changes_constraints_and_preserves_mount_identity_without_sour .iter() .any(|mount| mount.width == 312.0 && mount.height == 24.0) ); + // resize 不计作 REPL 输入;相同视口重复通知也不应再发布文档。 assert_eq!(session.inputs, 0); assert!( session @@ -2007,6 +2209,7 @@ fn viewport_resize_changes_constraints_and_preserves_mount_identity_without_sour .unwrap() .is_none() ); + // 非法 NaN 在视口边界被拒绝;这是参数错误,不应把仍可用的 VM 标成 faulted。 assert!( session .resize(Some(crate::layout::Size { @@ -2024,7 +2227,9 @@ const SOURCE_LAYOUT: &str = include_str!("../../../examples/source-layout.endor" /// 检查首次 source measure/arrange 已可读取结构关系与子测量结果,产出预期位置。 /// 直接改 Metrics.width 后通过依赖刷新同一 Mount,随后无变化刷新不再发布。 fn source_layout_uses_initial_mount_links_child_measurements_and_model_dependencies() { + // 复用 source-layout 示例,经加载入口执行首次测量、排列和发布。 let (mut session, initial) = ReplSession::load(SOURCE_LAYOUT, "app.main", 91, 1).unwrap(); + // 从已发布几何定位目标子矩形,检查父关系和子测量在首轮布局时已经可用。 let rect = initial .frame .mounts @@ -2032,9 +2237,13 @@ fn source_layout_uses_initial_mount_links_child_measurements_and_model_dependenc .find(|mount| mount.width == 200.0 && mount.height == 60.0) .unwrap(); assert_eq!((rect.x, rect.y), (44.0, 24.0)); + // 保留出现位置身份,后续模型写入应只改变同一位置的宽度。 let id = rect.id; + // 文字的 y 坐标同时验证排列对子测量高度与间距的使用。 assert!(initial.frame.commands.iter().any(|command| matches!(command,RenderCommand::Text { value,y,.. } if value.starts_with("尺寸来自") && *y == 100.0))); + // 取出示例的 Metrics 模型,直接写入源测量读过的字段。 let globals = session.candidate.globals.unwrap(); + // 夹具必须提供 Metrics 对象;类型不符应立即失败而非跳过依赖测试。 let Value::Object(metrics) = session .candidate .vm @@ -2044,12 +2253,15 @@ fn source_layout_uses_initial_mount_links_child_measurements_and_model_dependenc else { panic!("Metrics") }; + // 通过 VM 字段写入通知依赖系统;没有重新执行整段页面源码。 session .candidate .vm .set_attr(metrics, "width", Value::Number(260.into())) .unwrap(); + // 刷新应重算相关几何并发布新文档。 let next = session.refresh_document().unwrap().unwrap(); + // 按旧 ID 找回同一矩形,核对位置仍为 44、宽度更新为 260。 let rect = next .frame .mounts @@ -2057,6 +2269,7 @@ fn source_layout_uses_initial_mount_links_child_measurements_and_model_dependenc .find(|mount| mount.id == id) .unwrap(); assert_eq!((rect.x, rect.width), (44.0, 260.0)); + // 消费完变化后再次刷新应无输出,确认布局已收敛。 assert!(session.refresh_document().unwrap().is_none()); } @@ -2064,14 +2277,18 @@ fn source_layout_uses_initial_mount_links_child_measurements_and_model_dependenc /// 把同一 rect 放入具有不同 Metrics 的两个父容器。 /// 发布宽度必须分别为 200/140,不能把共享 Block 的一份测量结果误用于两个出现位置。 fn shared_block_source_measurements_belong_to_each_occurrence() { + // 保留原父容器,再创建另一份 Metrics;两个父容器共享同一 rect 业务对象。 let source = SOURCE_LAYOUT.replace( "page.render(root)", r#"otherMetrics = Metrics(140, 12) other = OffsetColumn(24, 16, rect, otherMetrics) page.render(Row(0, 0, root, other))"#, ); + // 在同一页面发布两个出现位置,使错误的按 Block 缓存策略可以被观察到。 let (mut session, initial) = ReplSession::load(&source, "app.main", 92, 1).unwrap(); + // 从全局表取得共享 rect 的业务身份,避免按几何误匹配父容器。 let globals = session.candidate.globals.unwrap(); + // 要求共享对象存在,后续用其 ID 同时筛选两个 Mount。 let Value::Object(rect) = session .candidate .vm @@ -2081,6 +2298,7 @@ fn shared_block_source_measurements_belong_to_each_occurrence() { else { panic!("Rect") }; + // 保留文档出现顺序,收集同一 Block 在不同父约束/模型上下文中的测量宽度。 let widths: Vec<_> = initial .frame .mounts @@ -2088,6 +2306,7 @@ fn shared_block_source_measurements_belong_to_each_occurrence() { .filter(|mount| mount.block_id == rect.to_string()) .map(|mount| mount.width) .collect(); + // 两处分别采用各自 Metrics 的 200/140,后续空刷新确认没有持续失效。 assert_eq!(widths, vec![200.0, 140.0]); assert!(session.refresh_document().unwrap().is_none()); } @@ -2096,6 +2315,7 @@ fn shared_block_source_measurements_belong_to_each_occurrence() { /// measure 读取宽度 80,onMount 随后把该依赖写成 140。 /// 首次发布必须已经重测为 140,不能把回调前的旧几何暴露出去,且后续刷新应稳定。 fn layout_dependencies_changed_by_mount_hook_are_measured_again_before_publication() { + // 首次 measure 读取 80,首次 onMount 再改为 140,构造发布前依赖失效的时序。 let source = r##"class Metrics { width: Number } class InitialRect: RectBlock { metrics: Metrics @@ -2108,7 +2328,9 @@ fn layout_dependencies_changed_by_mount_hook_are_measured_again_before_publicati rect = InitialRect(80,20,0,"#DDEEFF",metrics) page = Page() page.render(rect)"##; + // load 完成生命周期与布局收敛后才返回文档,调用方不应见到中间状态。 let (mut session, document) = ReplSession::load(source, "app.main", 93, 1).unwrap(); + // 检查第一份可见文档已经采用回调后的宽度;再刷新不得产生修正帧。 assert!( document .frame @@ -2123,6 +2345,7 @@ fn layout_dependencies_changed_by_mount_hook_are_measured_again_before_publicati /// 逐项修改示例,覆盖测量期提前读 bounds、只读范围业务写入、错误返回类型和伪造 child slot。 /// 每个非法程序都要在发布前给出对应诊断,不让不完整或不属于当前容器的排列通过。 fn source_layout_rejects_premature_geometry_writes_wrong_types_and_foreign_slots() { + // 每次仅替换一个合法源码片段,分别验证测量阶段、写入权限、返回契约与子槽归属边界。 for (before, after, message) in [ ( "return MeasureResult(parent.block.metrics.width, 60)", @@ -2145,7 +2368,9 @@ fn source_layout_rejects_premature_geometry_writes_wrong_types_and_foreign_slots "foreign child slot", ), ] { + // 从完整合法示例派生独立非法程序,避免前一错误留下的状态干扰下一用例。 let source = SOURCE_LAYOUT.replace(before, after); + // 在加载并首次布局时就应拒绝;诊断必须对应当前破坏的协议,不能因其他错误偶然失败。 let error = ReplSession::load(&source, "app.main", 94, 1).err().unwrap(); assert!(error.to_string().contains(message), "{error}"); } @@ -2155,12 +2380,14 @@ fn source_layout_rejects_premature_geometry_writes_wrong_types_and_foreign_slots /// 表驱动检查圆形内点击、圆外但底层可点、按下释放命中不同形状,以及页面外点击。 /// 实际提交仍指向圆 Mount,worker 必须重新按源 hitTest 与 press_point 复核并选择合法目标。 fn source_hit_filters_shape_falls_back_and_requires_matching_press_release() { + // 四组坐标分别覆盖圆内、圆外背景、跨目标释放和全页面外;两个计数表示最终回调归属。 for (press, release, expected_hits, expected_background) in [ ([64.0, 64.0], [64.0, 64.0], "1", "0"), ([144.0, 64.0], [144.0, 64.0], "0", "1"), ([64.0, 64.0], [144.0, 64.0], "0", "0"), ([9999.0, 9999.0], [9999.0, 9999.0], "0", "0"), ] { + // 每组重新加载圆形命中示例,保证计数从零开始、文档版本与事件相符。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/source-hit.endor"), "app.main", @@ -2168,12 +2395,14 @@ fn source_hit_filters_shape_falls_back_and_requires_matching_press_release() { 1, ) .unwrap(); + // 选中可交互的圆 Mount 作为客户端声明目标;宿主还必须用源 hitTest 复核真实坐标。 let circle = initial .frame .mounts .iter() .find(|mount| mount.interactive && mount.width == 160.0) .unwrap(); + // 在同一事件中携带按下与释放位置;即使释放落到背景,跨目标点击也不能误触发。 session .dispatch(&crate::events::Input { window: crate::window::MAIN_WINDOW, @@ -2188,6 +2417,7 @@ fn source_hit_filters_shape_falls_back_and_requires_matching_press_release() { screen_position: None, }) .unwrap(); + // 读取圆的业务计数验证前景回调,再检查背景计数验证穿透或拒绝行为。 assert_eq!( session.execute("hits.value", "app.main").unwrap().value, expected_hits @@ -2206,6 +2436,7 @@ fn source_hit_filters_shape_falls_back_and_requires_matching_press_release() { /// 把 hitTest 改为返回 Number 或试图递增业务计数。 /// 派发应报告 Bool 契约/只读错误并停止运行时,但业务写入与 click 回调均未发生,hits 保持 0。 fn source_hit_rejects_wrong_result_and_business_writes_before_callbacks() { + // 分别让 hitTest 返回错误类型或试图改业务状态,验证两种错误都先于 click 回调被拦截。 for (body, message) in [ ("return 1", "hitTest return expects Bool"), ( @@ -2213,15 +2444,19 @@ fn source_hit_rejects_wrong_result_and_business_writes_before_callbacks() { "read-only", ), ] { + // 只替换 hitTest 函数体,保留页面、监听器和命中区域这些有效前提。 let source = include_str!("../../../examples/source-hit.endor") .replace("return point.inCircle(40, 40, 40)", body); + // 加载时无需执行命中函数,预期错误应在随后输入派发期间出现。 let (mut session, initial) = ReplSession::load(&source, "app.main", 82, 1).unwrap(); + // 定位圆的出现位置,用有效版本和圆内坐标确保走到待验证的源命中协议。 let circle = initial .frame .mounts .iter() .find(|mount| mount.interactive && mount.width == 160.0) .unwrap(); + // 取派发错误而非发布结果;任何业务回调执行都发生得太晚,不能挽回只读约束破坏。 let error = session .dispatch(&crate::events::Input { window: crate::window::MAIN_WINDOW, @@ -2237,9 +2472,12 @@ fn source_hit_rejects_wrong_result_and_business_writes_before_callbacks() { }) .err() .unwrap(); + // 检查错误原因和运行时停止状态,防止将静默忽略错误算作通过。 assert!(error.to_string().contains(message), "{error}"); assert!(session.is_faulted()); + // 会话 faulted 后直接读取 VM,避免 execute 的停止检查遮蔽真实业务值。 let globals = session.candidate.globals.unwrap(); + // 取原 hits 状态对象,核对非法写入与 click 回调均未把零改为一。 let Value::Object(hits) = session .candidate .vm @@ -2249,6 +2487,7 @@ fn source_hit_rejects_wrong_result_and_business_writes_before_callbacks() { else { panic!("state") }; + // 业务状态必须仍为零,证明写入在发生前被拒绝。 assert_eq!( session.candidate.vm.get_attr(hits, "value").unwrap(), Value::Number(0.into()) @@ -2260,14 +2499,18 @@ fn source_hit_rejects_wrong_result_and_business_writes_before_callbacks() { /// 普通 RectBlock 通过 click 订阅变为可交互;断开令牌后新文档应移除所有交互标记。 /// 检验命中资格依赖实际监听器状态,不只由构造类型决定。 fn ordinary_block_subscription_updates_interactivity_after_disconnect() { + // 普通矩形通过连接令牌订阅 click,初始命中资格来自监听器而非专用 Button 类型。 let source = r##"hits = ui.state(0) rect = RectBlock(80, 40, 0, "#DDEEFF") token = rect.on("click", hits.increment) page = Page() page.render(rect)"##; + // 加载时建立连接并发布,先确认至少一个 Mount 被标记为可交互。 let (mut session, initial) = ReplSession::load(source, "app.main", 83, 1).unwrap(); assert!(initial.frame.mounts.iter().any(|mount| mount.interactive)); + // 从源语言断开唯一监听器;连接变化应触发新文档并清除交互标记。 let result = session.execute("token.disconnect()", "app.main").unwrap(); + // 遍历新文档的全部出现位置,不能只清除某一层或遗漏缓存中的交互状态。 assert!( result .document @@ -2282,10 +2525,13 @@ fn ordinary_block_subscription_updates_interactivity_after_disconnect() { /// 生成可调规模的源 paint 压力程序:copies 控制共享对象出现次数,locals 控制单次 paint 指令量。 /// onMount 计数检测取消/恢复是否重复生命周期,tint 让各出现位置绘制结果可统一断言。 fn resumable_paint_source(copies: usize, locals: usize) -> String { + // 下方布局/绘制切片测试调用本生成器;重复同一业务引用,扩大 Mount 数而不扩大业务对象数。 let children = std::iter::repeat_n("item", copies) .collect::>() .join(", "); + // 重复无副作用的局部赋值以消耗 VM 指令预算,让单个 paint 也能跨片暂停。 let locals = "probe = 2\n".repeat(locals); + // 生成完整可加载程序:挂载次数与可变颜色是后续取消、恢复和错误测试的观测点。 format!( "class Painted: RectBlock {{\n tint: String\n mounted: Object\n function onMount(self: Painted, mount: Mount): Unit {{ self.mounted.increment() }}\n function paint(self: Painted, mount: Mount, geometry: Bounds): DisplayList {{\n{locals}drawing = RectBlock.paint(self,mount,geometry)\ndrawing.commands.at(0).color = self.tint\nreturn drawing\n}}\n}}\nmounted = ui.state(0)\nitem = Painted(2,20,0,\"#DDEEFF\",\"#ED6A5A\",mounted)\npage = Page()\npage.render(Row(0,0,{children}))" ) @@ -2295,15 +2541,19 @@ fn resumable_paint_source(copies: usize, locals: usize) -> String { /// 分别加载含源布局/源绘制的示例并主动 reclaim 临时辅助对象。 /// 随后无业务变化刷新必须为 None,版本不变,证明缓存未把短命 helper 当作业务失效依赖。 fn collecting_lazy_helpers_does_not_invalidate_stable_layout_or_paint() { + // 分别覆盖源布局辅助对象和源绘制辅助对象,不把两套依赖机制混成一个用例。 for source in [ include_str!("../../../examples/flex-constraints.endor"), include_str!("../../../examples/source-paint.endor"), ] { + // 完成一次正常发布,让临时辅助对象及相应缓存都已产生。 let (mut session, initial) = ReplSession::load(source, "app.main", 281, 1).unwrap(); + // 显式执行桥接层回收,保留会话业务根;回收短命 helper 不应被解释为业务状态变化。 session .bridge .reclaim(&mut session.candidate.vm, &mut session.candidate.roots) .unwrap(); + // 检查没有发布动作,再比对保存的版本,防止仅返回 None 却内部替换文档。 assert!(session.refresh_document().unwrap().is_none()); assert_eq!( session.documents[&crate::window::MAIN_WINDOW] @@ -2318,10 +2568,14 @@ fn collecting_lazy_helpers_does_not_invalidate_stable_layout_or_paint() { /// 用 160/640 个出现位置强制布局和绘制让出一次执行。 /// 首次 Pending 时托管对象增长必须小于固定阈值,不能预建整树 Bounds/collector;显式取消后续体和只读范围都应关闭。 fn layout_and_paint_prepare_keep_only_current_occurrence_managed_helpers() { + // 以两种明显不同的树规模验证准备阶段的增量内存界限,阈值不随总出现次数增长。 for copies in [160, 640] { + // 先构造有效完整帧,随后直接调用桥接分片入口以观察首次 Pending 的中间状态。 let (mut session, initial) = ReplSession::load(&resumable_paint_source(copies, 0), "app.main", 280, 1).unwrap(); + // 记录开始绘制前的 VM 对象数;只计算本次准备与第一片新增的托管辅助对象。 let before = session.candidate.vm.object_count(); + // 对已布局的根和帧启动源绘制,避免把布局开销计入绘制阶段。 let progress = session .bridge .begin_paint_frame( @@ -2330,16 +2584,19 @@ fn layout_and_paint_prepare_keep_only_current_occurrence_managed_helpers() { initial.frame, ) .unwrap(); + // 必须真实让出执行;若一次完成,就没有覆盖待取消的绘制续体。 let crate::source_paint::Progress::Pending(work) = progress else { panic!("paint must yield"); }; // 每片只保留当前出现位置的辅助对象/结果;不能在首次让出前为所有位置预建 Bounds 和 collector。 assert!(session.candidate.vm.object_count() < before + 256); + // 取消未完成帧并检查 VM 续体释放,随后才能独立测试布局路径。 session .bridge .cancel_paint_frame(&mut session.candidate.vm, crate::window::MAIN_WINDOW, *work) .unwrap(); assert!(!session.candidate.vm.has_suspended_call()); + // 改变可用视口,使接下来的布局不能直接沿用原来的约束结果。 session .bridge .set_viewport( @@ -2350,20 +2607,25 @@ fn layout_and_paint_prepare_keep_only_current_occurrence_managed_helpers() { }), ) .unwrap(); + // 准备页面根但不一次性完成布局,后续观察 begin_layout_frame 的第一片。 let root = session .bridge .prepare_frame(&mut session.candidate.vm) .unwrap() .unwrap(); + // 重新取布局阶段基线,排除前一绘制测试已有对象对增长量的影响。 let before = session.candidate.vm.object_count(); + // 只启动布局第一片,不预先为整棵树创建 Bounds/collector。 let progress = session .bridge .begin_layout_frame(&mut session.candidate.vm, root) .unwrap(); + // 要求布局也实际暂停,随后用与绘制相同的固定阈值核对辅助对象增长。 let crate::ui_bridge::LayoutProgress::Pending(work) = progress else { panic!("layout must yield"); }; assert!(session.candidate.vm.object_count() < before + 256); + // 取消布局续体;最后同时核对暂停调用和只读范围均已关闭,避免影响后续业务执行。 session .bridge .cancel_layout_frame(&mut session.candidate.vm, *work) @@ -2377,16 +2639,21 @@ fn layout_and_paint_prepare_keep_only_current_occurrence_managed_helpers() { /// 修改共享 tint 后逐片推进到 paint 挂起,检查旧完整文档仍可见。 /// 换视口取消未发布绘制并重算,最终 80 条命令全为新色,onMount 仍恰好 80 次,取消与切片统计可观察。 fn pending_paint_retargets_without_replaying_completed_mount_hooks() { + // 80 个出现位置已完成首次 onMount;后续只改颜色,不应再调用这些生命周期钩子。 let (mut session, initial) = ReplSession::load(&resumable_paint_source(80, 0), "app.main", 278, 1).unwrap(); + // 空视口更新表表示沿用已有尺寸,让本轮先推进到可取消的源绘制阶段。 let viewports = std::collections::BTreeMap::new(); + // 提交业务颜色变化但采用增量执行,保留观察未完成更新的机会。 session .execute_incremental("item.tint = \"#526AC7\"", "app.main", &viewports) .unwrap(); + // 有界推进刷新各阶段,等待绘制工作出现;超出上限后由下面断言报告未覆盖暂停路径。 for _ in 0..100 { session .resize_windows_incremental(&viewports, false) .unwrap(); + // 只在刷新状态已有 paint 续体时停止,不能把仍在布局中的暂停误算为绘制暂停。 if session .refresh .as_ref() @@ -2395,6 +2662,7 @@ fn pending_paint_retargets_without_replaying_completed_mount_hooks() { break; } } + // 确认刷新状态与 VM 实际暂停调用一致,随后验证尚未发布半成品。 assert!( session .refresh @@ -2402,6 +2670,7 @@ fn pending_paint_retargets_without_replaying_completed_mount_hooks() { .is_some_and(|work| work.paint.is_some()) ); assert!(session.candidate.vm.has_suspended_call()); + // 绘制未完成时应继续展示初始版本,所有旧命令仍保持初始颜色。 assert_eq!( session.documents[&crate::window::MAIN_WINDOW] .frame @@ -2409,6 +2678,7 @@ fn pending_paint_retargets_without_replaying_completed_mount_hooks() { initial.frame.layout_version ); assert!(session.documents[&crate::window::MAIN_WINDOW].frame.commands.iter().all(|command| matches!(command, RenderCommand::RoundedRect { color, .. } if color == "#ED6A5A"))); + // 在旧 paint 暂停时提供新尺寸,迫使刷新取消旧目标并基于最新约束重新准备。 let latest = std::collections::BTreeMap::from([( crate::window::MAIN_WINDOW, crate::layout::Size { @@ -2416,17 +2686,21 @@ fn pending_paint_retargets_without_replaying_completed_mount_hooks() { height: 650.0, }, )]); + // 先只执行一次重定向,确认旧的 VM 暂停调用已被清除。 session.resize_windows_incremental(&latest, false).unwrap(); assert!(!session.candidate.vm.has_suspended_call()); + // 用同步入口推进到收敛,检查最终整帧全部为新色且没有丢失出现位置。 let settled = session.resize_windows(&latest).unwrap().unwrap(); assert_eq!(settled.frame.commands.len(), 80); assert!(settled.frame.commands.iter().all( |command| matches!(command, RenderCommand::RoundedRect { color, .. } if color == "#526AC7") )); + // 业务挂载计数仍为首次的 80;重算绘制不能重放已完成的 onMount。 assert_eq!( session.execute("mounted.value", "app.main").unwrap().value, "80" ); + // 取消应恰好发生一次,多片绘制统计则证明此用例确实跨越过执行切片。 assert_eq!(source_measure_stat(&mut session, "paintCancels"), 1); assert!(source_measure_stat(&mut session, "paintSlices") > 1); } @@ -2435,32 +2709,43 @@ fn pending_paint_retargets_without_replaying_completed_mount_hooks() { /// 利用长 paint 先产生暂停,再在解码时遇到非法颜色。 /// 必须同时验证曾挂起及最终失败;故障关闭 VM 续体/只读范围,保留旧文档版本和原始绘制颜色。 fn paint_error_after_pause_closes_read_only_scope_and_preserves_last_picture() { + // 单个 paint 内放入 300 次局部赋值,让命令解码报错之前有机会真实暂停。 let (mut session, initial) = ReplSession::load(&resumable_paint_source(1, 300), "app.main", 279, 1).unwrap(); + // 保持当前视口,将变量收敛到“暂停后绘制出错”这一条路径。 let viewports = std::collections::BTreeMap::new(); + // 业务字段本身可接受字符串;非法颜色会在后续 paint 命令解码时被拒绝。 session .execute_incremental("item.tint = \"invalid-color\"", "app.main", &viewports) .unwrap(); + // 累计是否曾观察到 paint 续体,防止只测到同步失败。 let mut paused = false; + // 另记最终是否失败,两项必须同时成立才覆盖暂停后的错误清理。 let mut failed = false; + // 有界推进至错误;每个成功切片检查刷新状态,错误分支立即结束推进。 for _ in 0..100 { + // 成功仍可能表示尚未完成,不能以 Ok 直接判定新帧已经发布。 match session.resize_windows_incremental(&viewports, false) { + // 累计 paint 曾挂起的事实;后续阶段清除 refresh 时也保留该证据。 Ok(_) => { paused |= session .refresh .as_ref() .is_some_and(|work| work.paint.is_some()) } + // 记录错误并停止使用这次已故障的刷新,后面的断言检查清理结果。 Err(_) => { failed = true; break; } } } + // 要求两个阶段均被覆盖;故障后 VM 不能残留暂停调用或只读范围。 assert!(paused && failed); assert!(session.is_faulted()); assert!(!session.candidate.vm.has_suspended_call()); assert!(!session.candidate.vm.object_store().is_read_only()); + // 对外仍保留最后成功发布的版本和颜色,不暴露无效颜色生成的半帧。 assert_eq!( session.documents[&crate::window::MAIN_WINDOW] .frame @@ -2474,6 +2759,7 @@ fn paint_error_after_pause_closes_read_only_scope_and_preserves_last_picture() { /// paint 局部变量先引用旧 ObjectList,再重新绑定到新 DisplayList。 /// 允许局部引用重绑不等于允许修改旧业务对象;绘制成功后 previous 仍应为空。 fn source_paint_can_rebind_old_plain_reference_to_new_result_without_mutating_it() { + // 局部 drawing 先引用旧列表、后改指向新 DisplayList;用于区分引用重绑与旧对象字段写入。 let source = r##"class ReboundRect: RectBlock { previous: ObjectList function paint(self: ReboundRect, mount: Mount, geometry: Bounds): DisplayList { @@ -2486,8 +2772,10 @@ fn source_paint_can_rebind_old_plain_reference_to_new_result_without_mutating_it rect = ReboundRect(80, 40, 0, "#DDEEFF", previous) page = Page() page.render(rect)"##; + // 加载过程执行 paint;成功生成一条命令,证明局部变量赋值未被只读策略误拒绝。 let (mut session, document) = ReplSession::load(source, "app.main", 75, 1).unwrap(); assert_eq!(document.frame.commands.len(), 1); + // 重新读取旧列表长度,确认没有因为重绑而意外往旧业务集合写入命令。 assert_eq!( session.execute("previous.count", "app.main").unwrap().value, "0" @@ -2498,6 +2786,7 @@ fn source_paint_can_rebind_old_plain_reference_to_new_result_without_mutating_it /// 源 paint 修改原生基类返回的命令颜色,检查共享对象各出现位置均使用覆盖结果。 /// 直接写堆上的 tint 而不执行 REPL,只靠 paint 的字段依赖就应触发重绘并在下一轮稳定。 fn source_paint_overrides_native_commands_and_reacts_to_heap_field_writes() { + // 加载共享矩形的源绘制示例,让 paint 对 tint 的读取建立真实依赖。 let (mut session, initial) = ReplSession::load( include_str!("../../../examples/source-paint.endor"), "app.main", @@ -2505,6 +2794,7 @@ fn source_paint_overrides_native_commands_and_reacts_to_heap_field_writes() { 1, ) .unwrap(); + // 先验证文档结构,再核对两处矩形及文字的源绘制颜色,确保覆盖生效。 initial.validate().unwrap(); assert_eq!(initial.frame.commands.iter().filter(|command| matches!(command, RenderCommand::RoundedRect { color, .. } if color == "#ED6A5A")).count(), 2); assert!( @@ -2512,7 +2802,9 @@ fn source_paint_overrides_native_commands_and_reacts_to_heap_field_writes() { |command| matches!(command, RenderCommand::Text { color, .. } if color == "#FFFFFF") ) ); + // 直接取得被 paint 读取的业务矩形对象,不通过重新执行页面源码来刷新。 let globals = session.candidate.globals.unwrap(); + // 对象身份必须来自原会话,使 set_attr 只改变已有字段并触发其依赖。 let Value::Object(rect) = session .candidate .vm @@ -2528,6 +2820,7 @@ fn source_paint_overrides_native_commands_and_reacts_to_heap_field_writes() { .vm .set_attr(rect, "tint", Value::Text("#526AC7".into())) .unwrap(); + // 仅靠写观察驱动刷新,两处共享出现位置都必须更新;再次刷新应稳定。 let updated = session.refresh_document().unwrap().unwrap(); assert_eq!(updated.frame.commands.iter().filter(|command| matches!(command, RenderCommand::RoundedRect { color, .. } if color == "#526AC7")).count(), 2); assert!(session.refresh_document().unwrap().is_none());