@mpcore/simulator 0.6.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -15,7 +15,7 @@
15
15
  - 提供原生形状的 `wx.onAppShow/offAppShow/onAppHide/offAppHide`;Node/browser session 与测试句柄通过 `triggerAppShow(options?)`、`triggerAppHide({ reason })` 显式驱动应用前后台事件,普通页面导航不会伪造应用切换
16
16
  - 测试入口 `launch({ configureSession })` 会在执行 `app.js` 前等待配置完成,可安装测试宿主能力;配置失败会关闭会话,默认 request 仍受既有 mock / strict mock 策略约束,不自动开放真实网络
17
17
  - 通过共享 `RuntimeKernel` 管理 artifact、独立执行 realm、timer、diagnostics 与平台适配边界
18
- - `close()` 会清理页面栈、组件 scope、observer、timer、事件和模块缓存,并使旧页面/节点 handle 失效
18
+ - `close()` 会清理页面栈、组件 scope、observer、timer、事件和模块缓存,并使旧页面/节点 handle 失效;Node/browser 中页面 `onUnload` 或组件 `detached` 抛错后仍继续清理其余组件、关系和调度器,最后保留并抛出首个异常,重复关闭不会重复卸载。普通导航沿用遇错即停止的卸载边界,不启用关闭专用的尽力清理策略。
19
19
 
20
20
  编写页面和组件单测时优先使用上层 `@mpcore/test`;直接使用本包适合实现 provider、调试桥或更低层运行时断言。
21
21
 
@@ -25,6 +25,20 @@
25
25
 
26
26
  此入口只负责页面样式依赖和 CSS 兼容声明,不实现嵌套组件的完整样式隔离、类名前缀转换或 `rpx` 布局换算。Component 页面的 `page-isolated`、`page-strong-isolated`、`page-apply-shared`、`page-shared` 禁用隐式 `app.wxss`,页面仍可显式导入样式;最终页面 JSON 的 `styleIsolation` 优先于 JS 定义,JSON 未提供该值时才保留 JS 选项。普通 `Page` 注册不应用组件隔离选项,普通 `isolated` 也不等同于 `page-isolated`。缺失依赖、循环导入、非法 CSS 和不支持的导入会抛出明确错误。支持带媒体条件的本地导入;远程导入及 `layer` / `supports` 导入条件不受支持,也不会触发外部请求。
27
27
 
28
+ ## 路由完成与滚动状态
29
+
30
+ Node/browser 宿主提供 `BeforeAppRoute`、`BeforePageUnload`、`AppRoute`、`AppRouteDone` 四组 `wx.on/off` 事件;同一次导航共享字符串 `routeEventId`。前置事件发生在隐藏/卸载之前,完成事件等待目标页 ready 和该次宿主提交。模拟器通过显式事件能力标记接入,`SDKVersion` 仍为 `0.0.0`,不代表真实微信基础库或 Skyline 渲染器。
31
+
32
+ 业务代码中的 `wx.navigateTo/redirectTo/reLaunch/navigateBack/switchTab` 在调用时捕获选项与回调,在当前调用栈退出后的宿主任务中提交,不会重入当前 HMR 事务或页面挂载。提交后修改或复用原选项对象,不会改变已提交的导航。
33
+
34
+ 底层 `session` 同名方法仍用于同步驱动;测试会话句柄的导航方法必须 `await`,以真实成功或失败回调完成,而不是立即返回旧页面。Node session 在实际清理完成后通过既有事件接口发送一次 `close` 通知,拒绝所有关联测试句柄中尚未完成的导航等待;直接关闭 `configureSession` 保留的底层 session 同样有效。`tap()` 触发导航后应使用 `waitForCurrentPage()` 等可观察条件等待目标页;同路由重启还须等待新页面身份或业务完成信号,不能仅匹配路径。工作台的选中 scope 跟随实际当前页切换,不把导航请求返回当作切换完成。
35
+
36
+ 浏览器自定义 renderer 的 `onRender` 可以返回 Promise;必须在实际 DOM 提交后 resolve,路由完成和 `setData` 回调才会继续。同步 renderer 可保持原来的返回值,非 Promise 返回值被忽略。Web demo 在更新响应式 revision 后返回 Vue `nextTick()`,等待预览 Shadow DOM 的 watcher 完成。关闭会话或被更新导航取代后,不发布旧的路由完成事件。工作台先初始化候选项目,成功后关闭旧会话再替换预览,防止旧提交确认新项目的 DOM;初始化或目录导入失败时保留当前可用会话。
37
+
38
+ `scroll-view` 的请求属性与实际位置分开保存。模型按启用的轴裁剪实际位置,内容缩短/移除时重新裁剪;未改变的绑定不会覆盖用户滚动,也不会在内容增长后自动重试。当前可求值的范围限定为 **inline `px` 视口尺寸及一个 `view` 内容盒的显式尺寸**,各轴独立;逻辑分组 `block`、注释和空白不生成内容盒。仅通过 WXSS 指定的尺寸、`rpx/%`、自动布局及多个内容盒等未知几何保守使用零范围,不能作为真实布局位置的证明。浏览器预览能显示 CSS,不等于这个原生状态模型实现了完整浏览器布局;复杂布局仍须在实际浏览器或微信 IDE 中验证。
39
+
40
+ 测试节点与真实预览点击共用原生 tap 分发:保留原始 `target`,逐层更新 `currentTarget`,遵守 `catchtap/catch:tap`,仅在事件到达 `navigator` 时执行其默认导航。一次交互先确定原始页面/组件归属,业务回调中的销毁、重新渲染或同路由重建不将剩余冒泡发送给新实例。测试节点 `tap()` 仍等待异步业务处理并传递结果或错误;导航的原生默认动作不等待异步业务 Promise。
41
+
28
42
  ## 分块请求 mock
29
43
 
30
44
  `session.mockRequest()` 支持为 `enableChunked: true` 的请求声明分块,默认仍不访问网络:
package/dist/index.d.mts CHANGED
@@ -1,3 +1,4 @@
1
+ import { WEVU_PAGE_SCROLL_EVENT_CONTRACT_KEY, WEVU_ROUTE_EVENT_CONTRACT_KEY } from "@weapp-core/constants";
1
2
  //#region src/host/globals.d.ts
2
3
  export interface HeadlessAppDefinition extends Record<string, any> {}
3
4
  export interface HeadlessPageDefinition extends Record<string, any> {}
@@ -23,6 +24,94 @@ export declare function registerPageDefinition(registries: HeadlessHostRegistrie
23
24
  export declare function registerComponentDefinition(registries: HeadlessHostRegistries, definition: HeadlessComponentDefinition): HeadlessPageDefinition;
24
25
  export declare function registerExportedComponentDefinition(registries: HeadlessHostRegistries, id: string, moduleExports: Record<string, any>, registeredDefinition?: HeadlessComponentDefinition): HeadlessComponentDefinition | null;
25
26
  //#endregion
27
+ //#region src/project/pageConfig.d.ts
28
+ interface HeadlessNavigationBarSnapshot {
29
+ animation: {
30
+ duration?: number;
31
+ timingFunction?: string;
32
+ } | null;
33
+ backgroundColor: string;
34
+ frontColor: string;
35
+ loading: boolean;
36
+ title: string;
37
+ }
38
+ type HeadlessBackgroundTextStyle = 'dark' | 'light';
39
+ interface HeadlessBackgroundSnapshot {
40
+ backgroundColor: string;
41
+ backgroundColorBottom: string;
42
+ backgroundColorTop: string;
43
+ textStyle: HeadlessBackgroundTextStyle;
44
+ }
45
+ //#endregion
46
+ //#region src/runtime/componentInstance/types.d.ts
47
+ interface HeadlessComponentInstance extends Record<string, any> {
48
+ __definition__?: HeadlessComponentDefinition;
49
+ __lastInteractionEvent__?: Record<string, any>;
50
+ __propertySnapshots__?: Record<string, any>;
51
+ __ready__?: boolean;
52
+ createIntersectionObserver?: (options?: Record<string, any>) => any;
53
+ createMediaQueryObserver?: () => HeadlessWxMediaQueryObserver;
54
+ createSelectorQuery?: () => HeadlessWxSelectorQuery;
55
+ getRelationNodes: (relationKey: string) => HeadlessComponentInstance[];
56
+ data: Record<string, any>;
57
+ properties: Record<string, any>;
58
+ selectAllComponents?: (selector: string) => any[];
59
+ selectComponent?: (selector: string) => any;
60
+ selectOwnerComponent?: () => any;
61
+ setData: (patch: Record<string, any>, callback?: () => void) => void;
62
+ triggerEvent: (eventName: string, detail?: unknown, options?: Record<string, any>) => void;
63
+ }
64
+ interface CreateComponentInstanceOptions {
65
+ definition: HeadlessComponentDefinition;
66
+ properties?: Record<string, any>;
67
+ requestRender?: (callback?: () => void) => void;
68
+ triggerEvent?: (instance: HeadlessComponentInstance, eventName: string, detail?: unknown, options?: Record<string, any>) => void;
69
+ }
70
+ //#endregion
71
+ //#region src/runtime/componentInstance/observers.d.ts
72
+ export declare function runComponentObservers(definition: HeadlessComponentDefinition, instance: HeadlessComponentInstance, changedKeys: string[], previousProperties?: Record<string, any>): void;
73
+ //#endregion
74
+ //#region src/runtime/componentInstance/properties.d.ts
75
+ export declare function coerceComponentPropertyValue(rawValue: unknown, option: unknown): unknown;
76
+ export declare function normalizeComponentPropertyValue(definition: HeadlessComponentDefinition, key: string, rawValue: unknown): any;
77
+ //#endregion
78
+ //#region src/runtime/componentInstance/shared.d.ts
79
+ export declare function cloneValue<T>(value: T): T;
80
+ export declare function hasComponentPropertyValueChanged(currentValue: unknown, previousSnapshot: unknown, nextValue: unknown, bindingAffected: boolean): boolean;
81
+ //#endregion
82
+ //#region src/runtime/componentInstance/index.d.ts
83
+ export declare function createComponentInstance(options: CreateComponentInstanceOptions): HeadlessComponentInstance;
84
+ export declare function runComponentLifecycle(instance: HeadlessComponentInstance, lifecycleName: 'attached' | 'created' | 'detached' | 'ready'): void;
85
+ export declare function runComponentPageLifetime(instance: HeadlessComponentInstance, lifetimeName: 'hide' | 'resize' | 'show', payload?: unknown): void;
86
+ //#endregion
87
+ //#region src/runtime/pageInstance.d.ts
88
+ export interface HeadlessPageInstance extends Record<string, any> {
89
+ __background__?: HeadlessBackgroundSnapshot;
90
+ __backgroundTextStyle__?: HeadlessBackgroundTextStyle;
91
+ __lastChangedKeys__?: string[];
92
+ __navigationBar__?: HeadlessNavigationBarSnapshot;
93
+ __navigationBarTitle__?: string;
94
+ __route__: string;
95
+ __scrollTop__?: number;
96
+ data: Record<string, any>;
97
+ properties: Record<string, any>;
98
+ options: Record<string, string>;
99
+ route: string;
100
+ createIntersectionObserver?: (options?: Record<string, any>) => any;
101
+ createMediaQueryObserver?: () => HeadlessWxMediaQueryObserver;
102
+ getTabBar?: () => HeadlessComponentInstance | null;
103
+ selectAllComponents?: (selector: string) => any[];
104
+ selectComponent?: (selector: string) => any;
105
+ setData: (patch: Record<string, any>, callback?: () => void) => void;
106
+ }
107
+ export declare function getPageInstanceId(page: HeadlessPageInstance): number;
108
+ export declare function createPageInstance(route: string, definition: HeadlessPageDefinition, options?: Record<string, string>, pageState?: {
109
+ background?: HeadlessBackgroundSnapshot;
110
+ backgroundTextStyle?: HeadlessBackgroundTextStyle;
111
+ navigationBar?: HeadlessNavigationBarSnapshot;
112
+ requestRender?: (callback?: () => void) => void;
113
+ }): HeadlessPageInstance;
114
+ //#endregion
26
115
  //#region src/host/wx/core.d.ts
27
116
  export interface HeadlessWxCallbackOption<TResult = void> {
28
117
  complete?: (result?: TResult) => void;
@@ -933,7 +1022,31 @@ export interface HeadlessWxDriverCapabilities {
933
1022
  }
934
1023
  //#endregion
935
1024
  //#region src/host/wx/api.d.ts
936
- export interface HeadlessWxDriver extends HeadlessWxDriverCapabilities {
1025
+ /** 宿主已接受的一次路由操作;同一次操作的所有阶段共用事件标识。 */
1026
+ export interface HeadlessWxRouteEvent {
1027
+ path: string;
1028
+ query: Record<string, string>;
1029
+ openType: 'appLaunch' | 'navigateTo' | 'redirectTo' | 'navigateBack' | 'switchTab' | 'reLaunch';
1030
+ renderer: 'webview' | 'skyline' | 'xr-frame';
1031
+ webviewId: number;
1032
+ routeEventId: string;
1033
+ timeStamp: number;
1034
+ }
1035
+ /** 页面销毁前的原生实例,仍可同步读取页面数据。 */
1036
+ export interface HeadlessWxBeforePageUnloadEvent extends HeadlessWxRouteEvent {
1037
+ page: HeadlessPageInstance;
1038
+ }
1039
+ export interface HeadlessWxRouteListeners {
1040
+ onBeforeAppRoute: (listener: (event: HeadlessWxRouteEvent) => void) => void;
1041
+ offBeforeAppRoute: (listener?: (event: HeadlessWxRouteEvent) => void) => void;
1042
+ onBeforePageUnload: (listener: (event: HeadlessWxBeforePageUnloadEvent) => void) => void;
1043
+ offBeforePageUnload: (listener?: (event: HeadlessWxBeforePageUnloadEvent) => void) => void;
1044
+ onAppRoute: (listener: (event: HeadlessWxRouteEvent) => void) => void;
1045
+ offAppRoute: (listener?: (event: HeadlessWxRouteEvent) => void) => void;
1046
+ onAppRouteDone: (listener: (event: HeadlessWxRouteEvent) => void) => void;
1047
+ offAppRouteDone: (listener?: (event: HeadlessWxRouteEvent) => void) => void;
1048
+ }
1049
+ export interface HeadlessWxDriver extends HeadlessWxDriverCapabilities, HeadlessWxRouteListeners {
937
1050
  chooseImage: (option: HeadlessWxChooseImageOption) => HeadlessWxChooseImageResult;
938
1051
  chooseMessageFile: (option: HeadlessWxChooseMessageFileOption) => HeadlessWxChooseMessageFileResult;
939
1052
  chooseMedia: (option: HeadlessWxChooseMediaOption) => HeadlessWxChooseMediaResult;
@@ -959,7 +1072,9 @@ export interface HeadlessWxDriver extends HeadlessWxDriverCapabilities {
959
1072
  canvasToTempFilePath: (option: HeadlessWxCanvasToTempFilePathOption) => HeadlessWxCanvasToTempFilePathSuccessResult;
960
1073
  uploadFile: (option: HeadlessWxUploadFileOption) => HeadlessWxRequestTask;
961
1074
  }
962
- export interface HeadlessWx extends HeadlessUniEventBus {
1075
+ export interface HeadlessWx extends HeadlessUniEventBus, HeadlessWxRouteListeners {
1076
+ [WEVU_ROUTE_EVENT_CONTRACT_KEY]: 1;
1077
+ [WEVU_PAGE_SCROLL_EVENT_CONTRACT_KEY]: 1;
963
1078
  canIUse: (schema: string) => boolean;
964
1079
  chooseImage: (option?: HeadlessWxChooseImageOption) => HeadlessWxChooseImageResult | undefined;
965
1080
  chooseMessageFile: (option?: HeadlessWxChooseMessageFileOption) => HeadlessWxChooseMessageFileResult | undefined;
@@ -1146,6 +1261,7 @@ export declare class RuntimeScheduler {
1146
1261
  private readonly intervals;
1147
1262
  private readonly timeouts;
1148
1263
  private closed;
1264
+ private canceledHandle?;
1149
1265
  private readonly onError;
1150
1266
  constructor(onError: (error: unknown) => void);
1151
1267
  clearInterval(handle: IntervalHandle): void;
@@ -1154,6 +1270,8 @@ export declare class RuntimeScheduler {
1154
1270
  queueMicrotask(handler: () => void): void;
1155
1271
  setInterval(handler: (...args: any[]) => void, timeout?: number, ...args: any[]): NodeJS.Timeout;
1156
1272
  setTimeout(handler: (...args: any[]) => void, timeout?: number, ...args: any[]): NodeJS.Timeout;
1273
+ /** 已销毁 realm 的 Promise 回调不能复活任务,也不能向外泄漏异步拒绝。 */
1274
+ private getCanceledHandle;
1157
1275
  }
1158
1276
  //#endregion
1159
1277
  //#region src/kernel/runtimeKernel.d.ts
@@ -1278,94 +1396,6 @@ export interface CreateBrowserProjectOptions {
1278
1396
  }
1279
1397
  export declare function createBrowserProject(files: BrowserVirtualFiles, options?: CreateBrowserProjectOptions): HeadlessProjectDescriptor;
1280
1398
  //#endregion
1281
- //#region src/project/pageConfig.d.ts
1282
- interface HeadlessNavigationBarSnapshot {
1283
- animation: {
1284
- duration?: number;
1285
- timingFunction?: string;
1286
- } | null;
1287
- backgroundColor: string;
1288
- frontColor: string;
1289
- loading: boolean;
1290
- title: string;
1291
- }
1292
- type HeadlessBackgroundTextStyle = 'dark' | 'light';
1293
- interface HeadlessBackgroundSnapshot {
1294
- backgroundColor: string;
1295
- backgroundColorBottom: string;
1296
- backgroundColorTop: string;
1297
- textStyle: HeadlessBackgroundTextStyle;
1298
- }
1299
- //#endregion
1300
- //#region src/runtime/componentInstance/types.d.ts
1301
- interface HeadlessComponentInstance extends Record<string, any> {
1302
- __definition__?: HeadlessComponentDefinition;
1303
- __lastInteractionEvent__?: Record<string, any>;
1304
- __propertySnapshots__?: Record<string, any>;
1305
- __ready__?: boolean;
1306
- createIntersectionObserver?: (options?: Record<string, any>) => any;
1307
- createMediaQueryObserver?: () => HeadlessWxMediaQueryObserver;
1308
- createSelectorQuery?: () => HeadlessWxSelectorQuery;
1309
- getRelationNodes: (relationKey: string) => HeadlessComponentInstance[];
1310
- data: Record<string, any>;
1311
- properties: Record<string, any>;
1312
- selectAllComponents?: (selector: string) => any[];
1313
- selectComponent?: (selector: string) => any;
1314
- selectOwnerComponent?: () => any;
1315
- setData: (patch: Record<string, any>, callback?: () => void) => void;
1316
- triggerEvent: (eventName: string, detail?: unknown, options?: Record<string, any>) => void;
1317
- }
1318
- interface CreateComponentInstanceOptions {
1319
- definition: HeadlessComponentDefinition;
1320
- properties?: Record<string, any>;
1321
- requestRender?: (callback?: () => void) => void;
1322
- triggerEvent?: (instance: HeadlessComponentInstance, eventName: string, detail?: unknown, options?: Record<string, any>) => void;
1323
- }
1324
- //#endregion
1325
- //#region src/runtime/componentInstance/observers.d.ts
1326
- export declare function runComponentObservers(definition: HeadlessComponentDefinition, instance: HeadlessComponentInstance, changedKeys: string[], previousProperties?: Record<string, any>): void;
1327
- //#endregion
1328
- //#region src/runtime/componentInstance/properties.d.ts
1329
- export declare function coerceComponentPropertyValue(rawValue: unknown, option: unknown): unknown;
1330
- export declare function normalizeComponentPropertyValue(definition: HeadlessComponentDefinition, key: string, rawValue: unknown): any;
1331
- //#endregion
1332
- //#region src/runtime/componentInstance/shared.d.ts
1333
- export declare function cloneValue<T>(value: T): T;
1334
- export declare function hasComponentPropertyValueChanged(currentValue: unknown, previousSnapshot: unknown, nextValue: unknown, bindingAffected: boolean): boolean;
1335
- //#endregion
1336
- //#region src/runtime/componentInstance/index.d.ts
1337
- export declare function createComponentInstance(options: CreateComponentInstanceOptions): HeadlessComponentInstance;
1338
- export declare function runComponentLifecycle(instance: HeadlessComponentInstance, lifecycleName: 'attached' | 'created' | 'detached' | 'ready'): void;
1339
- export declare function runComponentPageLifetime(instance: HeadlessComponentInstance, lifetimeName: 'hide' | 'resize' | 'show', payload?: unknown): void;
1340
- //#endregion
1341
- //#region src/runtime/pageInstance.d.ts
1342
- export interface HeadlessPageInstance extends Record<string, any> {
1343
- __background__?: HeadlessBackgroundSnapshot;
1344
- __backgroundTextStyle__?: HeadlessBackgroundTextStyle;
1345
- __lastChangedKeys__?: string[];
1346
- __navigationBar__?: HeadlessNavigationBarSnapshot;
1347
- __navigationBarTitle__?: string;
1348
- __route__: string;
1349
- __scrollTop__?: number;
1350
- data: Record<string, any>;
1351
- properties: Record<string, any>;
1352
- options: Record<string, string>;
1353
- route: string;
1354
- createIntersectionObserver?: (options?: Record<string, any>) => any;
1355
- createMediaQueryObserver?: () => HeadlessWxMediaQueryObserver;
1356
- getTabBar?: () => HeadlessComponentInstance | null;
1357
- selectAllComponents?: (selector: string) => any[];
1358
- selectComponent?: (selector: string) => any;
1359
- setData: (patch: Record<string, any>, callback?: () => void) => void;
1360
- }
1361
- export declare function getPageInstanceId(page: HeadlessPageInstance): number;
1362
- export declare function createPageInstance(route: string, definition: HeadlessPageDefinition, options?: Record<string, string>, pageState?: {
1363
- background?: HeadlessBackgroundSnapshot;
1364
- backgroundTextStyle?: HeadlessBackgroundTextStyle;
1365
- navigationBar?: HeadlessNavigationBarSnapshot;
1366
- requestRender?: (callback?: () => void) => void;
1367
- }): HeadlessPageInstance;
1368
- //#endregion
1369
1399
  //#region src/view/wxs.d.ts
1370
1400
  type WxsModuleBindings = Record<string, unknown>;
1371
1401
  //#endregion
@@ -1539,6 +1569,100 @@ interface RuntimeRendererContext {
1539
1569
  //#region src/runtime/render/index.d.ts
1540
1570
  export declare function renderRuntimePageTree(context: RuntimeRendererContext, page: HeadlessPageInstance): RuntimeRenderedPageTree;
1541
1571
  //#endregion
1572
+ //#region src/view/nodeHandle.d.ts
1573
+ interface DomNodeLike$3 {
1574
+ attribs?: Record<string, string>;
1575
+ children?: DomNodeLike$3[];
1576
+ data?: string;
1577
+ dataset?: Record<string, unknown>;
1578
+ name?: string;
1579
+ parent?: DomNodeLike$3 | null;
1580
+ type?: string;
1581
+ }
1582
+ export interface HeadlessTestingNodeEventInit {
1583
+ currentTarget?: {
1584
+ dataset?: Record<string, unknown>;
1585
+ id?: string;
1586
+ };
1587
+ dataset?: Record<string, unknown>;
1588
+ detail?: unknown;
1589
+ id?: string;
1590
+ mark?: Record<string, unknown>;
1591
+ target?: {
1592
+ dataset?: Record<string, unknown>;
1593
+ id?: string;
1594
+ };
1595
+ }
1596
+ export interface HeadlessTestingNodeValueEventInit extends HeadlessTestingNodeEventInit {
1597
+ detail?: {
1598
+ value?: string;
1599
+ [key: string]: unknown;
1600
+ };
1601
+ }
1602
+ interface HeadlessTestingNodeInteractionHandlers {
1603
+ assertActive?: () => void;
1604
+ callMethod: (scopeId: string | null, methodName: string, event: Record<string, any>) => unknown;
1605
+ dispatchNativeEvent?: (node: DomNodeLike$3, eventName: string, event: HeadlessTestingNodeEventInit, onHandlerResult?: (result: unknown) => void) => boolean;
1606
+ createScopeHandle: (scopeId: string | null) => {
1607
+ scopeId: string;
1608
+ snapshot: () => Promise<unknown>;
1609
+ } | null;
1610
+ createPageHandle: () => {
1611
+ data: (path?: string) => Promise<unknown>;
1612
+ };
1613
+ ownerScopeId: (scopeId: string | null) => string | null;
1614
+ }
1615
+ export declare class HeadlessTestingNodeHandle {
1616
+ private readonly node;
1617
+ private readonly interactions?;
1618
+ constructor(node: DomNodeLike$3, interactions?: HeadlessTestingNodeInteractionHandlers | undefined);
1619
+ private assertActive;
1620
+ private query;
1621
+ $(selector: string): Promise<HeadlessTestingNodeHandle | null>;
1622
+ $$(selector: string): Promise<HeadlessTestingNodeHandle[]>;
1623
+ getElementsByXpath(expression: string): Promise<HeadlessTestingNodeHandle[]>;
1624
+ attr(name: string): Promise<string | undefined>;
1625
+ dataset(): Promise<Record<string, unknown>>;
1626
+ scope(): Promise<{
1627
+ scopeId: string;
1628
+ snapshot: () => Promise<unknown>;
1629
+ } | null>;
1630
+ componentScope(): Promise<{
1631
+ scopeId: string;
1632
+ snapshot: () => Promise<unknown>;
1633
+ } | null>;
1634
+ pageScope(): Promise<{
1635
+ scopeId: string;
1636
+ snapshot: () => Promise<unknown>;
1637
+ } | null>;
1638
+ page(): Promise<{
1639
+ data: (path?: string) => Promise<unknown>;
1640
+ }>;
1641
+ ownerComponentScope(): Promise<{
1642
+ scopeId: string;
1643
+ snapshot: () => Promise<unknown>;
1644
+ } | null>;
1645
+ text(): Promise<string>;
1646
+ tagName(): Promise<string | undefined>;
1647
+ trigger(eventName: string, event?: HeadlessTestingNodeEventInit): Promise<unknown>;
1648
+ tap(event?: HeadlessTestingNodeEventInit): Promise<unknown>;
1649
+ input(value: string, event?: HeadlessTestingNodeValueEventInit): Promise<unknown>;
1650
+ change(value: string, event?: HeadlessTestingNodeValueEventInit): Promise<unknown>;
1651
+ blur(value?: string, event?: HeadlessTestingNodeValueEventInit): Promise<unknown>;
1652
+ wxml(): Promise<string>;
1653
+ }
1654
+ //#endregion
1655
+ //#region src/view/nativeNode.d.ts
1656
+ interface HeadlessNativeNode {
1657
+ attribs?: Record<string, string>;
1658
+ children?: HeadlessNativeNode[];
1659
+ name?: string;
1660
+ dataset?: Record<string, unknown>;
1661
+ data?: string;
1662
+ type?: string;
1663
+ parent?: HeadlessNativeNode | null;
1664
+ }
1665
+ //#endregion
1542
1666
  //#region src/runtime/wxState.d.ts
1543
1667
  export interface HeadlessWxLoadingSnapshot {
1544
1668
  mask: boolean;
@@ -1653,6 +1777,7 @@ export interface HeadlessWxUploadFileLogEntry {
1653
1777
  }
1654
1778
  export interface HeadlessWxStateOptions {
1655
1779
  strictMocks?: boolean;
1780
+ readPackageFile?: (filePath: string) => string | undefined;
1656
1781
  }
1657
1782
  export declare function createHeadlessWxState(scheduler?: Pick<RuntimeScheduler, 'clearTimeout' | 'setTimeout'>, options?: HeadlessWxStateOptions): {
1658
1783
  close(): void;
@@ -1941,6 +2066,7 @@ export declare class HeadlessSession {
1941
2066
  private appInstance;
1942
2067
  private readonly appLifecycle;
1943
2068
  private readonly moduleLoader;
2069
+ private readonly routeEvents;
1944
2070
  private readonly eventListeners;
1945
2071
  private readonly registries;
1946
2072
  private currentPageInstance;
@@ -2055,6 +2181,9 @@ export declare class HeadlessSession {
2055
2181
  getFileText(filePath: string): string | null;
2056
2182
  getSavedFileListSnapshot(): HeadlessWxSavedFileInfo[];
2057
2183
  renderCurrentPage(): RuntimeRenderedPageTree;
2184
+ dispatchNativeNodeEvent(node: HeadlessNativeNode, eventName: string, event: {
2185
+ detail?: unknown;
2186
+ }, onHandlerResult?: (result: unknown) => void): boolean;
2058
2187
  requestRender(callback?: () => void): void;
2059
2188
  getScopeSnapshot(scopeId: string): {
2060
2189
  data: Record<string, any>;
@@ -2077,6 +2206,8 @@ export declare class HeadlessSession {
2077
2206
  } | null;
2078
2207
  getScopeIdForComponent(component: HeadlessComponentInstance | null | undefined): string | null;
2079
2208
  callScopeMethod(scopeId: string | null, methodName: string, event: Record<string, any>): any;
2209
+ /** 解析本次交互的实例,后续回调不随重渲染或导航切换所有者。 */
2210
+ private resolveScopeMethod;
2080
2211
  callScopeMethodDirect(scopeId: string, methodName: string, ...args: any[]): any;
2081
2212
  getStorageSnapshot(): {
2082
2213
  [k: string]: unknown;
@@ -2256,6 +2387,7 @@ export declare class HeadlessSession {
2256
2387
  triggerRouteDone(options?: Record<string, any>): HeadlessPageInstance;
2257
2388
  stopPullDownRefresh(): void;
2258
2389
  private executeSelectorQuery;
2390
+ private beginRoute;
2259
2391
  private createFreshPage;
2260
2392
  private runInitialPageLifecycles;
2261
2393
  private isTabBarRoute;
@@ -2285,7 +2417,8 @@ export declare function createHeadlessSession(options: HeadlessSessionOptions):
2285
2417
  export interface BrowserHeadlessSessionOptions {
2286
2418
  files: BrowserVirtualFiles;
2287
2419
  globals?: Record<string, unknown>;
2288
- onRender?: () => void;
2420
+ /** 返回的 Promise 表示宿主 DOM 已提交;普通返回值按同步渲染处理。 */
2421
+ onRender?: () => unknown;
2289
2422
  project?: HeadlessProjectDescriptor;
2290
2423
  strictHostMocks?: boolean;
2291
2424
  }
@@ -2304,6 +2437,7 @@ export declare class BrowserHeadlessSession {
2304
2437
  private readonly componentScopes;
2305
2438
  private readonly selectorQueryScopeSnapshots;
2306
2439
  private renderRequestPending;
2440
+ private renderInProgress;
2307
2441
  private readonly renderRequestCallbacks;
2308
2442
  private readonly tabBarRoutes;
2309
2443
  private readonly tabPages;
@@ -2317,6 +2451,7 @@ export declare class BrowserHeadlessSession {
2317
2451
  private launchOptions;
2318
2452
  private readonly kernel;
2319
2453
  private readonly startupNavigation;
2454
+ private readonly routeEvents;
2320
2455
  private readonly wxState;
2321
2456
  private pullDownRefreshState;
2322
2457
  constructor(options: BrowserHeadlessSessionOptions);
@@ -2575,8 +2710,13 @@ export declare class BrowserHeadlessSession {
2575
2710
  selectOwnerComponent(scopeId: string): any;
2576
2711
  private selectComponentsWithin;
2577
2712
  renderCurrentPage(): BrowserRenderedPageTree;
2713
+ dispatchNativeNodeEvent(node: HeadlessNativeNode, eventName: string, event: {
2714
+ detail?: unknown;
2715
+ }, onHandlerResult?: (result: unknown) => void): boolean;
2578
2716
  requestRender(callback?: () => void): void;
2579
2717
  callScopeMethod(scopeId: string | null, methodName: string, event: Record<string, any>): any;
2718
+ /** 解析本次交互的实例,后续回调不随重渲染或导航切换所有者。 */
2719
+ private resolveScopeMethod;
2580
2720
  callScopeMethodDirect(scopeId: string, methodName: string, ...args: any[]): any;
2581
2721
  callTapBinding(scopeId: string, methodName: string): any;
2582
2722
  callTapBindingWithEvent(scopeId: string, methodName: string, event?: {
@@ -2617,6 +2757,7 @@ export declare class BrowserHeadlessSession {
2617
2757
  triggerRouteDone(options?: Record<string, any>): HeadlessPageInstance;
2618
2758
  stopPullDownRefresh(): void;
2619
2759
  private executeSelectorQuery;
2760
+ private beginRoute;
2620
2761
  private createFreshPage;
2621
2762
  private runInitialPageLifecycles;
2622
2763
  private isTabBarRoute;
@@ -2672,88 +2813,30 @@ export interface MiniProgramEventBinding {
2672
2813
  }
2673
2814
  export declare function collectMiniProgramEventBindings(attributes?: Record<string, string>): Map<string, MiniProgramEventBinding>;
2674
2815
  export declare function resolveMiniProgramEventBinding(attributes: Record<string, string> | undefined, eventName: string): MiniProgramEventBinding | null;
2675
- //#endregion
2676
- //#region src/view/nodeHandle.d.ts
2677
- interface DomNodeLike$3 {
2816
+ /** 冒泡时保留原始 target,currentTarget 则属于当前执行绑定的节点。 */
2817
+ export declare function createMiniProgramEventPayload(node: {
2678
2818
  attribs?: Record<string, string>;
2679
- children?: DomNodeLike$3[];
2680
- data?: string;
2681
2819
  dataset?: Record<string, unknown>;
2682
- name?: string;
2683
- parent?: DomNodeLike$3 | null;
2684
- type?: string;
2685
- }
2686
- export interface HeadlessTestingNodeEventInit {
2687
- currentTarget?: {
2688
- dataset?: Record<string, unknown>;
2689
- id?: string;
2690
- };
2820
+ }, eventName: string, event: HeadlessTestingNodeEventInit, origin?: {
2821
+ attribs?: Record<string, string>;
2691
2822
  dataset?: Record<string, unknown>;
2692
- detail?: unknown;
2693
- id?: string;
2694
- mark?: Record<string, unknown>;
2695
- target?: {
2696
- dataset?: Record<string, unknown>;
2697
- id?: string;
2698
- };
2699
- }
2700
- export interface HeadlessTestingNodeValueEventInit extends HeadlessTestingNodeEventInit {
2701
- detail?: {
2702
- value?: string;
2703
- [key: string]: unknown;
2704
- };
2705
- }
2706
- interface HeadlessTestingNodeInteractionHandlers {
2707
- assertActive?: () => void;
2708
- callMethod: (scopeId: string | null, methodName: string, event: Record<string, any>) => unknown;
2709
- createScopeHandle: (scopeId: string | null) => {
2710
- scopeId: string;
2711
- snapshot: () => Promise<unknown>;
2712
- } | null;
2713
- createPageHandle: () => {
2714
- data: (path?: string) => Promise<unknown>;
2715
- };
2716
- ownerScopeId: (scopeId: string | null) => string | null;
2717
- }
2718
- export declare class HeadlessTestingNodeHandle {
2719
- private readonly node;
2720
- private readonly interactions?;
2721
- constructor(node: DomNodeLike$3, interactions?: HeadlessTestingNodeInteractionHandlers | undefined);
2722
- private assertActive;
2723
- private query;
2724
- $(selector: string): Promise<HeadlessTestingNodeHandle | null>;
2725
- $$(selector: string): Promise<HeadlessTestingNodeHandle[]>;
2726
- getElementsByXpath(expression: string): Promise<HeadlessTestingNodeHandle[]>;
2727
- attr(name: string): Promise<string | undefined>;
2728
- dataset(): Promise<Record<string, unknown>>;
2729
- scope(): Promise<{
2730
- scopeId: string;
2731
- snapshot: () => Promise<unknown>;
2732
- } | null>;
2733
- componentScope(): Promise<{
2734
- scopeId: string;
2735
- snapshot: () => Promise<unknown>;
2736
- } | null>;
2737
- pageScope(): Promise<{
2738
- scopeId: string;
2739
- snapshot: () => Promise<unknown>;
2740
- } | null>;
2741
- page(): Promise<{
2742
- data: (path?: string) => Promise<unknown>;
2743
- }>;
2744
- ownerComponentScope(): Promise<{
2745
- scopeId: string;
2746
- snapshot: () => Promise<unknown>;
2747
- } | null>;
2748
- text(): Promise<string>;
2749
- tagName(): Promise<string | undefined>;
2750
- trigger(eventName: string, event?: HeadlessTestingNodeEventInit): Promise<unknown>;
2751
- tap(event?: HeadlessTestingNodeEventInit): Promise<unknown>;
2752
- input(value: string, event?: HeadlessTestingNodeValueEventInit): Promise<unknown>;
2753
- change(value: string, event?: HeadlessTestingNodeValueEventInit): Promise<unknown>;
2754
- blur(value?: string, event?: HeadlessTestingNodeValueEventInit): Promise<unknown>;
2755
- wxml(): Promise<string>;
2756
- }
2823
+ }): {
2824
+ bubbles: boolean;
2825
+ capturePhase: boolean;
2826
+ composed: boolean;
2827
+ currentTarget: {
2828
+ dataset: Record<string, unknown>;
2829
+ id: string;
2830
+ };
2831
+ detail: unknown;
2832
+ mark: Record<string, unknown> | undefined;
2833
+ target: {
2834
+ dataset: Record<string, unknown>;
2835
+ id: string;
2836
+ };
2837
+ timeStamp: number;
2838
+ type: string;
2839
+ };
2757
2840
  //#endregion
2758
2841
  //#region src/view/render.d.ts
2759
2842
  interface DomNodeLike$2 {
@@ -2956,6 +3039,7 @@ interface HeadlessTestingToolInfo {
2956
3039
  export declare class HeadlessTestingSessionHandle {
2957
3040
  private readonly project;
2958
3041
  private readonly session;
3042
+ private readonly pendingNavigations;
2959
3043
  constructor(project: HeadlessProjectDescriptor, session: HeadlessSession);
2960
3044
  close(): Promise<void>;
2961
3045
  toolInfo(): Promise<HeadlessTestingToolInfo>;