refactor(testing-framework): type uiAgent options via core connection types

`UIAgentConfig.options` was a hand-rolled `Record<string, unknown>`,
disconnected from the real agent launcher inputs and forcing
`as unknown as Parameters<...>` casts in the factory.

Make `UIAgentConfig` a discriminated union keyed by `type`, with each
variant's `options` typed against the canonical connection types from
`@midscene/core` (`WebConnectionOpt` / `AndroidConnectionOpt` / ...).
`UIAgentType` is derived from the union; web's `url` is required.

Also drop the now-unnecessary `agent as unknown as Agent` cast in the web
factory: `PuppeteerAgent` is `@midscene/core`'s `Agent<PuppeteerWebPage>`,
so once options are typed it is directly assignable to `Agent` — the cast
was only needed because the prior `Record` casts poisoned the return type.

Updates config test and RFC §2/§2.1.

Validation: nx build core, testing-framework build + tsc + 33 unit tests,
pnpm lint.

Author: ottomao

packages/testing-framework/src/config/types.ts

@@ -2,23 +2,37 @@
  * `midscene.config.ts` schema (RFC §2). Environment / target lives here, never
  * in the case YAML.
  */
+import type {
+  AndroidConnectionOpt,
+  ComputerConnectionOpt,
+  IOSConnectionOpt,
+  WebConnectionOpt,
+} from '@midscene/core';
 import type { Agent } from '@midscene/core/agent';
 import type { AgentOpt } from '@midscene/core/agent';
 import type { GeneralAgentAdapter } from '../general-agent/types';
 import type { RuntimeNode } from '../runtime';
 
-/** Platforms the framework can build a UI Agent for out of the box. */
-export type UIAgentType = 'web' | 'android' | 'ios' | 'computer';
-
 /** Shared UI Agent behavior parameters (aiActContext, generateReport, ...). */
 export type UIAgentOptions = AgentOpt;
 
-/** Configuration-style UI Agent: framework builds it from `type` + `options`. */
-export interface UIAgentConfig {
-  type: UIAgentType;
-  /** Platform connection parameters (url, deviceId, ...). */
-  options?: Record<string, unknown>;
-}
+/**
+ * Configuration-style UI Agent: the framework builds the agent from `type` +
+ * `options`. `options` is the platform connection target, typed against the
+ * canonical per-platform connection types from `@midscene/core`
+ * (`WebConnectionOpt` / `AndroidConnectionOpt` / ...). Those are the pure
+ * "how to reach the target" shapes the agent launchers consume — agent
+ * behavior is expressed separately via `uiAgentOptions`. Keeping `options`
+ * bound to core means it can never drift from the launcher inputs.
+ */
+export type UIAgentConfig =
+  | { type: 'web'; options: WebConnectionOpt }
+  | { type: 'android'; options?: AndroidConnectionOpt }
+  | { type: 'ios'; options?: IOSConnectionOpt }
+  | { type: 'computer'; options?: ComputerConnectionOpt };
+
+/** Platforms the framework can build a UI Agent for out of the box. */
+export type UIAgentType = UIAgentConfig['type'];
 
 /** Context passed to a programmatic UI Agent factory. */
 export interface UIAgentFactoryCtx {

packages/testing-framework/src/ui-agent/factory.ts

@@ -5,6 +5,7 @@
  * (programmatic). This module resolves both into a live Midscene UI Agent plus
  * an optional cleanup hook.
  */
+import type { AndroidConnectionOpt, WebConnectionOpt } from '@midscene/core';
 import type { Agent } from '@midscene/core/agent';
 import type { UIAgent, UIAgentConfig, UIAgentOptions } from '../config/types';
 
@@ -46,9 +47,9 @@ async function createFromConfig(
 ): Promise<ResolvedUIAgent> {
   switch (config.type) {
     case 'web':
-      return createWebAgent(config, uiAgentOptions);
+      return createWebAgent(config.options, uiAgentOptions);
     case 'android':
-      return createAndroidAgent(config, uiAgentOptions);
+      return createAndroidAgent(config.options, uiAgentOptions);
     case 'ios':
     case 'computer':
       throw new Error(
@@ -62,11 +63,10 @@ async function createFromConfig(
 }
 
 async function createWebAgent(
-  config: UIAgentConfig,
+  options: WebConnectionOpt,
   uiAgentOptions: UIAgentOptions | undefined,
 ): Promise<ResolvedUIAgent> {
-  const options = (config.options ?? {}) as Record<string, unknown>;
-  if (!options.url) {
+  if (!options?.url) {
     throw new Error('[midscene] uiAgent.type "web" requires `options.url`.');
   }
 
@@ -80,14 +80,12 @@ async function createWebAgent(
   }
 
   const { agent, freeFn } = await mod.puppeteerAgentForTarget(
-    options as unknown as Parameters<typeof mod.puppeteerAgentForTarget>[0],
-    uiAgentOptions as unknown as Parameters<
-      typeof mod.puppeteerAgentForTarget
-    >[1],
+    options,
+    uiAgentOptions,
   );
 
   return {
-    agent: agent as unknown as Agent,
+    agent,
     cleanup: async () => {
       for (const free of freeFn) {
         try {
@@ -101,10 +99,10 @@ async function createWebAgent(
 }
 
 async function createAndroidAgent(
-  config: UIAgentConfig,
+  options: AndroidConnectionOpt | undefined,
   uiAgentOptions: UIAgentOptions | undefined,
 ): Promise<ResolvedUIAgent> {
-  const options = (config.options ?? {}) as Record<string, unknown>;
+  const env = options ?? {};
   // `@midscene/android` is an optional peer; load it loosely so the framework
   // does not hard-depend on it.
   const spec = '@midscene/android';
@@ -122,10 +120,9 @@ async function createAndroidAgent(
     );
   }
 
-  const deviceId = options.deviceId as string | undefined;
-  const agent = await mod.agentFromAdbDevice(deviceId, {
-    ...(uiAgentOptions as object),
-    ...options,
+  const agent = await mod.agentFromAdbDevice(env.deviceId, {
+    ...uiAgentOptions,
+    ...env,
   });
 
   return {

packages/testing-framework/tests/unit-test/config.test.ts

@@ -37,8 +37,10 @@ describe('defineMidsceneConfig', () => {
 
   it('throws without testDir', () => {
     expect(() =>
-      // @ts-expect-error intentionally missing
-      defineMidsceneConfig({ uiAgent: { type: 'web' } }),
+      // @ts-expect-error intentionally missing testDir
+      defineMidsceneConfig({
+        uiAgent: { type: 'web', options: { url: 'https://x.test' } },
+      }),
     ).toThrow(/testDir/);
   });
 });

rfcs/0001-v2-testing-framework-phase0.md

@@ -79,8 +79,15 @@ import { defineMidsceneConfig } from '@midscene/testing-framework';
 
 export default defineMidsceneConfig({
   // —— 运行目标：单字段 uiAgent，容纳配置式与编程式（见 §2.1）——
+  // 配置式按 type 判别，options 直接复用 @midscene/core 的逐平台「连接类型」
+  // （WebConnectionOpt / AndroidConnectionOpt / IOSConnectionOpt /
+  // ComputerConnectionOpt），即从 env 类型里剥掉 agent 行为与 yaml 配置后的
+  // 纯连接契约，与 agent launcher 入参同源，不再是手写的 Record。
   uiAgent:
-    | { type: 'web' | 'android' | 'ios' | 'computer'; options: Record<string, unknown> }
+    | { type: 'web'; options: WebConnectionOpt }
+    | { type: 'android'; options?: AndroidConnectionOpt }
+    | { type: 'ios'; options?: IOSConnectionOpt }
+    | { type: 'computer'; options?: ComputerConnectionOpt }
     | ((ctx: UIAgentFactoryCtx) => Promise<{ agent: Agent }>);
 
   // —— 用例发现 ——
@@ -120,7 +127,7 @@ export default defineMidsceneConfig({
 - 值是**对象** → 配置式：框架据 `type + options` 创建 UI Agent。
 - 值是**函数** → 编程式：项目完全掌控构造。
 
-两者唯一的 key，类型层就是 union，从根上消除"两套运行目标定义"的气味。`options`（平台连接参数，如 url / deviceId）与 `uiAgentOptions`（Agent 行为，如 aiActContext / generateReport）是两类不同的东西，都保留。
+两者唯一的 key，类型层就是 union，从根上消除"两套运行目标定义"的气味。`options`（平台连接参数，如 url / deviceId）与 `uiAgentOptions`（Agent 行为，如 aiActContext / generateReport）是两类不同的东西，都保留。`options` 不是手写的 `Record`，而是按 `type` 判别后落到 `@midscene/core` 暴露的逐平台「连接类型」`WebConnectionOpt` / `AndroidConnectionOpt` / … 上——这些是从对应 env 类型派生、剥掉 agent 行为与 yaml 配置后的纯连接契约（web 的 `url` 因此是必填）。改 core 类型这里会立即感知，且不再把 agent-opt / output 等无关字段混进连接参数。
 
 **配置式样例：**