Spacedrive 跨语言集成测试：基于 Rust 桥接的 useNormalizedQuery 端到端测试实战

Spacedrive 跨语言集成测试基于 Rust 桥接的 useNormalizedQuery 端到端测试实战【免费下载链接】spacedriveSpacedrive is an open source cross-platform file explorer, powered by a virtual distributed filesystem written in Rust.项目地址: https://gitcode.com/gh_mirrors/sp/spacedrive导读本文围绕 Spacedrive 仓库中的 TypeScript 集成测试体系展开讲解如何通过 Rust 测试夹具启动真实 daemon、索引测试目录再以bun test驱动 TypeScript 侧 React HookuseNormalizedQuery完成文件系统变更 → 事件推送 → 缓存更新 → UI 重渲染的全链路验证。读完本文你将掌握这套跨 Rust/TypeScript 双语言的桥接测试架构、桥接配置协议、四类现成测试场景的源码实现以及如何新增、调试这类端到端测试。一、为什么需要 Rust ↔ TypeScript 桥接集成测试Spacedrive 的核心文件系统引擎由 Rust 编写而 React 前端通过sd/ts-client与 daemon 通信。传统做法是分别对 Rust 端和 TypeScript 端做单元测试但这无法回答一个关键问题当磁盘上的文件被移动或重命名时前端缓存的目录列表会不会实时正确更新这个问题的答案横跨 Rust 的文件系统 watcher、索引数据库、事件系统WebSocket以及 TypeScript 侧的订阅管理与 TanStack Query 缓存。packages/ts-client/tests/integration/README.md描述的桥接方案正是为此设计由 Rust 测试进程启动一个真实的 Spacedrive daemon 并索引测试文件再派生子进程运行 TypeScript 测试让 React Hook 直接连接到这个真实后端进行断言。二、架构总览三层桥接链路整套测试桥接由三个环节协作完成整体脉络如下Rust 测试夹具core/tests/typescript_bridge_test.rs使用IndexingHarnessBuilder搭建带 RPC server 的真实 daemon创建测试 location 并写入测试文件完成索引Shallow 或 Content 模式将连接信息写入 JSON 文件通过tokio::process::Command派发bun test运行指定 TypeScript 测试校验 TypeScript 测试的退出码并清理环境。桥接配置通过环境变量BRIDGE_CONFIG_PATH传递的 JSON 文件包含五个字段详见第三节。TypeScript 测试如 useNormalizedQuery.test.ts读取桥接配置通过SpacedriveClient.fromTcpSocket()连接 daemon使用 React Testing Library 的renderHook挂载 Hook直接执行文件系统操作move / rename / delete等待 watcher 检测并推送事件断言缓存是否按预期更新。三、桥接配置协议BRIDGE_CONFIG_PATH 的五个字段Rust 侧把连接信息序列化为 JSON 写入临时文件TypeScript 侧通过BRIDGE_CONFIG_PATH环境变量读取。该配置由 core/tests/typescript_bridge_test.rs 中的TestBridgeConfig结构体定义字段类型含义socket_addrStringdaemon RPC 服务器的 TCP 地址如127.0.0.1:41234每次测试随机分配可用端口library_idString测试库的 UUID来自harness.library.id()location_db_idi32已索引 location 在数据库中的 IDlocation_pathPathBuf测试 location 在物理文件系统上的根路径test_data_pathPathBuf测试数据临时目录TypeScript 侧的读取代码见 useNormalizedQuery.test.tsconst configPath process.env.BRIDGE_CONFIG_PATH; if (!configPath) { throw new Error(BRIDGE_CONFIG_PATH environment variable not set); } const configJson await readFile(configPath, utf-8); bridgeConfig JSON.parse(configJson); // 通过 TCP socket 连接 daemon client SpacedriveClient.fromTcpSocket(bridgeConfig.socket_addr); // 设置当前库上下文 client.setCurrentLibrary(bridgeConfig.library_id);需要说明的是仓库中 client.ts 提供的是setCurrentLibrary()方法并会触发library-changed事件供 Hook 同步库 ID。四、Rust 侧测试夹具源码解析4.1 启用 daemonIndexingHarnessBuilder提供了.enable_daemon()方法其实现位于 core/tests/helpers/indexing_harness.rspub fn enable_daemon(mut self) - Self { self.daemon_enabled true; self }在build()阶段如果启用了 daemon夹具会先绑定端口 0 获取系统分配的随机空闲端口再启动 RPC server 后台任务并复用测试 Harness 同一个Core实例见 indexing_harness.rslet temp_listener tokio::net::TcpListener::bind(127.0.0.1:0).await?; let actual_port temp_listener.local_addr()?.port(); let socket_addr format!(127.0.0.1:{}, actual_port); drop(temp_listener); // Release the port let core_for_daemon core.clone(); tokio::spawn(async move { let mut server sd_core::infra::daemon::rpc::RpcServer::new(socket_addr_clone, core_for_daemon); if let Err(e) server.start().await { tracing::error!(Daemon RPC server error: {}, e); } });测试中获取地址let harness IndexingHarnessBuilder::new(test_name) .enable_daemon() // 在随机端口启动 RPC server .build() .await?; let socket_addr harness.daemon_socket_addr().unwrap(); // socket_addr 127.0.0.1:41234随机可用端口4.2 测试夹具的其他关键行为IndexingHarnessBuilder默认开启文件系统 watcher可通过.disable_watcher()关闭这保证了测试中文件操作能被真实检测到build()会创建独立测试库{test_name} Library并用get_current_device_id()注册真实设备使 watcher 能定位 locationindexing_harness.rs测试数据目录通过TestDataDir::new_for_watcher()创建避免 watcher 在特定平台如 macOS上的兼容问题。五、运行测试5.1 首次环境准备从仓库根目录安装依赖bun install该命令会安装集成测试所需的全部依赖包括happy-domhappy-dom/global-registrator—— 轻量 DOM 环境文档标注比 jsdom 快 5–10 倍testing-library/react—— React Hook 测试工具tanstack/react-query—— 查询缓存管理以及其他必需依赖。5.2 全链路端到端测试Rust → TypeScript在core目录执行cd core cargo test --package sd-core --test typescript_bridge_test -- --nocapture该命令将编译 Rust 代码启动带测试数据的 daemon通过 Bun 运行 TypeScript 测试同时输出 Rust 与 TypeScript 两侧日志任一侧失败都会导致测试失败Rust 侧会检查output.status.success()。仓库中 core/tests/typescript_bridge_test.rs 实际注册了 4 个#[tokio::test]测试分别对应移动、重命名、批量移动、删除四个场景Rust 测试函数对应的 TypeScript 测试文件test_typescript_use_normalized_query_with_file_movesuseNormalizedQuery.test.tstest_typescript_use_normalized_query_with_folder_renamesuseNormalizedQuery.folder-rename.test.tstest_typescript_use_normalized_query_with_bulk_movesuseNormalizedQuery.bulk-moves.test.tstest_typescript_use_normalized_query_with_file_deletesuseNormalizedQuery.file-delete.test.ts5.3 仅运行 TypeScript 侧手动调试当需要独立调试 TypeScript 侧时# 终端 1手动启动 daemon cd core cargo run --bin sd-daemon # 终端 2使用手动准备的配置运行 TypeScript 测试 export BRIDGE_CONFIG_PATH/path/to/bridge/config.json bun test packages/ts-client/tests/integration/useNormalizedQuery.test.tsRust 测试实际执行 Bun 时还会额外指定--config指向 bunfig.toml并设置RUST_LOGdebug环境变量便于排障见 typescript_bridge_test.rs。六、测试场景逐一拆解6.1 文件移动测试Rust 侧先创建folder_a/folder_b及file1.txt、file2.rs、file3.md以IndexMode::Shallow索引typescript_bridge_test.rs。TypeScript 侧流程如下useNormalizedQuery.test.ts用useNormalizedQuery查询folder_a与folder_b的files.directory_listing等待初始数据加载waitFor超时 5 秒断言初始状态folder_a至少 2 个文件、folder_b至少 1 个文件并记录file1的 UUID用 Node 的fs/promises.rename把file1.txt从folder_a移到folder_b等待 8 秒watcher 有 500ms 缓冲 tick 时间重命名类操作需要更久断言folder_a缓存中不再有file1folder_b缓存中新增file1关键断言file1InFolderB.uuid file1Before.uuid验证移动被识别为同一实体UUID 保持不变。单测超时 30 秒以覆盖 watcher 延迟。6.2 文件夹重命名测试Rust 侧创建original_folder内含文件与嵌套目录并索引typescript_bridge_test.rs。TypeScript 侧useNormalizedQuery.folder-rename.test.ts查询根目录列表与original_folder内容断言根目录中存在kind Directory的original_folder记录其 UUID执行rename(originalPath, renamedPath)等待 8 秒断言original_folder从根目录缓存移除、renamed_folder出现关键断言renamedFolder.uuid originalFolderUuid验证目录身份identity在重命名后保持。6.3 批量移动与删除测试除 README 中提到的两个场景外仓库还新增了两个桥接测试批量移动test_typescript_use_normalized_query_with_bulk_moves在bulk_test目录创建 20 个文件前 10 个简单文本、后 10 个较大文件并使用IndexMode::Content索引——该模式会计算哈希、生成内容身份content identity专门用于回归按内容寻址的文件导致缓存更新错误的 bug见 typescript_bridge_test.rs。索引后额外等待 5 秒让内容识别与事件处理完成。文件删除test_typescript_use_normalized_query_with_file_deletes在delete_test目录创建 5 个文件后索引验证ResourceDeleted事件能否将文件从缓存中移除typescript_bridge_test.rs。此外集成测试目录 packages/ts-client/tests/integration 中还包含search.test.ts与ephemeral-streaming.test.ts覆盖搜索与流式传输场景。七、测试环境Happy DOM 而非 jsdom这些集成测试需要浏览器 DOM 全局对象document、window、HTMLElement等来支撑 React Testing Library。仓库选用Happy DOM其特点来自 README 与 setup.ts 注释对 React Hook 测试比 jsdom 快 5–10 倍更轻量专为测试优化配置简单一行代码完成全局注册。工作原理setup.ts 导入happy-dom/global-registrator并注册 DOM 全局import { GlobalRegistrator } from happy-dom/global-registrator; GlobalRegistrator.register();每个测试文件第一行导入./setup确保在 React 相关 import 之前完成 DOM 初始化// 在任何其他 import 之前设置 DOM 环境 import ./setup;每个测试在afterEach中调用testing-library/react的cleanup()清理组件。setup.ts 还抑制了act()警告集成测试中 daemon 事件是异步触发 React 状态更新的属于预期行为无需act()包裹setup.ts。八、useNormalizedQuery 源码级剖析桥接测试的核心被测对象是useNormalizedQuery。其实现位于 packages/ts-client/src/hooks/useNormalizedQuery.ts是与 Rust 核心Identifiabletrait 对应的 TypeScript 端组件订阅过滤后的 WebSocket 事件流将ResourceEvent转换为 TanStack Query 缓存更新。8.1 订阅与过滤useNormalizedQuery内部通过client.subscribeFiltered()建立订阅过滤器包含resource_type、path_scope、library_id、include_descendants四项useNormalizedQuery.ts。注意一个重要的工程决策// file 类资源数量庞大无 pathScope 的全局订阅会引发事件风暴 // 单文件查询如 FileInspector改用 stale-while-revalidate 策略 if (options.resourceType file !options.pathScope) { return; }即文件类资源必须提供pathScope才会建立事件订阅这是防止大规模事件刷屏的关键设计。8.2 事件类型与 Valibot 运行时校验事件处理器对三类事件做 Valibot 运行时校验后分发useNormalizedQuery.tsResourceChanged—— 单个资源变更走updateSingleResource类型安全深合并ResourceChangedBatch—— 批量资源变更走updateBatchResourcesResourceDeleted—— 资源删除走deleteResource按 ID 从缓存过滤Refresh—— 全量刷新调用queryClient.invalidateQueries()。8.3 客户端二次过滤filterBatchResourcesREADME 中强调SubscriptionManager 过滤与缓存更新。源码中还有个关键细节服务端过滤虽能减少 90% 事件量但无法拆分原子批量事件——若批量事件包含 100 个文件而只有 1 个属于当前查询作用域整个批次仍会送达。因此filterBatchResources在客户端按pathScope二次过滤路径统一归一化Windows 反斜杠转正斜杠、去尾部斜杠Windows 路径小写比较从alternate_paths或sd_path中提取 Physical 路径提取文件父目录与 scope 做精确匹配只有父目录等于 scope 的文件才进入缓存useNormalizedQuery.ts。同时被过滤掉的资源可能意味着文件移出了当前视图此时会执行deleteResource将其从缓存移除。8.4 缓存合并策略safeMergesafeMerge遵循以下规则useNormalizedQuery.tsnoMergeFields来自事件 metadataincoming 直接覆盖数组字段整体替换而非拼接服务端下发的是完整列表如 sidecars、alternate_paths、tags拼接会损坏数据嵌套对象递归深合并如content_identity原始类型incoming 覆盖。另外updateBatchResources在缓存为空时用事件数据直接播种缓存{ files, total_count, has_more: false }解决订阅缓冲区重放先于首次查询响应到达导致事件被丢弃、UI 空置的竞态问题useNormalizedQuery.ts。九、完整事件流从文件系统变更到 React 重渲染的链路README 中的流程图文件系统变更rename/move/delete ↓ Watcher 检测Rust ↓ 索引更新数据库 ↓ ResourceChanged 事件WebSocket ↓ SubscriptionManager 过滤TypeScript ↓ useNormalizedQuery 事件处理器 ↓ 缓存更新TanStack Query ↓ React 重渲染Hooks桥接测试的价值在于这条链路中没有任何一环使用 mockwatcher 是真实的、数据库是真实的、WebSocket 事件是真实的、TanStack Query 缓存也是真实的。十、新增测试的完整指南10.1 Rust 侧模板在 core/tests/typescript_bridge_test.rs 中新增#[tokio::test]#[tokio::test] async fn test_typescript_my_new_feature() - anyhow::Result() { let harness IndexingHarnessBuilder::new(my_test) .enable_daemon() .build() .await?; // 设置测试数据 let test_location harness.create_test_location(test).await?; test_location.write_file(test.txt, content).await?; let location test_location.index(Test, IndexMode::Shallow).await?; // 写桥接配置参考现有测试 let bridge_config TestBridgeConfig { /* ... */ }; // 序列化为 JSON 并写入临时文件 ... // 派生 TypeScript 测试进程 let output tokio::process::Command::new(bun) .arg(test) .arg(packages/ts-client/tests/integration/my-feature.test.ts) .env(BRIDGE_CONFIG_PATH, config_path.to_str().unwrap()) .output() .await?; assert!(output.status.success()); Ok(()) }10.2 TypeScript 侧模板在 packages/ts-client/tests/integration 目录新增测试文件import ./setup; import { SpacedriveClient } from ../../src/client; import { renderHook } from testing-library/react; test(my feature works, async () { const bridgeConfig JSON.parse(/* 从环境变量读取 */); const client SpacedriveClient.fromTcpSocket(bridgeConfig.socket_addr); client.setCurrentLibrary(bridgeConfig.library_id); const { result } renderHook(() useMyFeature(...)); // 断言你的功能 });十一、调试指南11.1 启用调试日志# Rust 侧 RUST_LOGdebug cargo test typescript_bridge -- --nocapture # TypeScript 侧在测试文件中 const query useNormalizedQuery({ // ... debug: true, // 为事件处理启用 console.log });测试还默认把 TypeScript 的 stdout/stderr 转发到 Rust 的 stderrRust 侧会打印桥接配置路径、socket 地址、库 ID 等上下文信息typescript_bridge_test.rs。11.2 常见问题排查Connection refused连接被拒绝daemon 未启动或启动太慢。Rust 夹具在绑定端口后会 sleep 1 秒等待 server 就绪indexing_harness.rs若仍失败可适当延长等待时间。No events received未收到事件watcher 可能被禁用或处于缓冲中。检查Harness 中 watcher 处于启用状态默认启用等待时间是否足够文件夹重命名因缓冲需要 8 秒以上路径是否正确、索引是否已完成。Cache not updating缓存未更新检查事件订阅过滤器与查询作用域是否匹配resourceType是否正确file、location等文件查询是否正确设置pathScope未设置将跳过订阅见 8.1 节事件是否被filterBatchResources客户端二次过滤掉。十二、这套测试体系的收益真正的端到端测试覆盖从文件系统到 React Hook 的完整技术栈真实 watcher 集成验证的是真实文件系统 watcher 行为而非 mock跨语言一致性保证 Rust 与 TypeScript 两侧的事件协议、字段命名不漂移回归检测能捕获事件发送、缓存合并、过滤逻辑中的破坏性变更示例即文档测试代码本身就是如何正确使用 useNormalizedQuery 事件系统的可运行范例。十三、未来增强方向README 中列出的规划包括批量操作的测试补充错误处理与重试逻辑测试网络中断场景测试性能基准测试并发操作测试内容识别content identification事件测试标签tag更新测试。延伸阅读core/tests/typescript_bridge_test.rs —— Rust 桥接测试全部用例core/tests/helpers/indexing_harness.rs ——IndexingHarnessBuilder与 daemon 启动实现packages/ts-client/src/hooks/useNormalizedQuery.ts —— 被测核心 Hook 实现packages/ts-client/src/client.ts ——SpacedriveClient与 TCP 传输packages/ts-client/tests/integration/setup.ts —— Happy DOM 环境初始化packages/ts-client/tests/integration/bunfig.toml —— Bun 测试配置【免费下载链接】spacedriveSpacedrive is an open source cross-platform file explorer, powered by a virtual distributed filesystem written in Rust.项目地址: https://gitcode.com/gh_mirrors/sp/spacedrive创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考