@midscene/test 1.16.0 → 1.16.2

package/dist/templates/test/android/.env.example

@@ -1,7 +1,7 @@
 # Copy this file to .env before running tests.
 # Do not commit .env to your repository. In CI, inject these values as environment variables instead.
 # Choose a supported model and copy its four configuration values from:
-# https://midscenejs.com/model-common-config.html
+# https://midscenejs.com/model-api-setup.html
 # For the complete environment variable reference, see:
 # https://midscenejs.com/model-config.html
 # After configuring .env, verify model connectivity and Midscene compatibility from the project directory:

package/dist/templates/test/android/README.md

@@ -4,7 +4,7 @@ A Midscene Test project for Android, based on the TodoMVC case in `midscene-exam
 
 If you skipped installation during creation, run `{{INSTALL_COMMAND}}`. The `postinstall` script automatically generates `midscene-node-spec.android.md` after each dependency installation. If lifecycle scripts are disabled, run `{{RUN_NODES_COMMAND}}` manually.
 
-Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-common-config.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
+Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-api-setup.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
 
 After configuring `.env`, run `{{VERIFY_MODEL_COMMAND}}` from the project directory to check model connectivity and Midscene compatibility. This check does not require a browser or device. If it fails, see [Model debugging and observability](https://midscenejs.com/model-debugging-observability.html) before running tests.
 
@@ -17,3 +17,5 @@ Run tests with `{{TEST_COMMAND}}`. Read `midscene-node-spec.android.md` for the
 After changing Node registrations in `midscene.config.ts`, run `{{RUN_NODES_COMMAND}}` to refresh the spec. This loads the configuration without connecting to a device or running tests. Extension factories must only acquire runtime resources inside Node execution.
 
 Tests run serially and stop after the first failed case (`test.bail: 1`). Reports are saved and connections are released on failure. Reports are written to `midscene_run/report/`.
+
+Each test file creates its own Agent through `fileSetup` and releases it afterward. The Project is limited to one file at a time because this starter connects to a single device or desktop. Before increasing the Project limit, provide independent devices/displays through your resource allocator.

package/dist/templates/test/android/README.zh.md

@@ -2,10 +2,12 @@
 
 这是参考 `midscene-example/android/vitest-demo` TodoMVC 用例的 Android 版 Midscene Test 项目。
 
-如果创建时跳过安装，执行 `{{INSTALL_COMMAND}}`。安装后会自动生成 `midscene-node-spec.android.md`；若禁用了安装脚本，手动执行 `{{RUN_NODES_COMMAND}}`。复制 `.env.example` 为 `.env`，按[模型配置指南](https://midscenejs.com/model-common-config.html)配置模型。
+如果创建时跳过安装，执行 `{{INSTALL_COMMAND}}`。安装后会自动生成 `midscene-node-spec.android.md`；若禁用了安装脚本，手动执行 `{{RUN_NODES_COMMAND}}`。复制 `.env.example` 为 `.env`，按[模型配置指南](https://midscenejs.com/model-api-setup.html)配置模型。
 
 配置后，在项目目录执行 `{{VERIFY_MODEL_COMMAND}}`，检查模型连接和 Midscene 兼容性。这一步不需要浏览器或设备；若检查失败，请先参考[模型调试与可观测性](https://midscenejs.com/model-debugging-observability.html)排查，再运行测试。
 
 连接设备并用 `adb devices` 确认；可设置 `ANDROID_DEVICE_ID` 指定设备。`cases/todo.yaml` 打开在线 React TodoMVC，添加三个任务、删除一个、完成另一个、筛选已完成任务，并校验可见任务和未完成数量。设备需要能访问该网站；`beforeEach` 先执行 `midscene.config.ts` 中的 `todo.setup`，打开 All 视图并等待输入框加载，再由 `aiAssert` 确认列表为空（包含已完成任务）且没有遮挡弹窗。已有任务会保留；检查失败时，用例会在修改任务前停止。请切换到 All，删除全部任务（包括已完成任务），或仅清除 TodoMVC 网站的数据；关闭遮挡弹窗后重新运行。模型或连接异常应先按报告中的原因排查。AI 检查可能误判，失败时请结合报告确认页面状态。
 
 执行 `{{TEST_COMMAND}}` 运行测试。Node 列表见 `midscene-node-spec.android.md`；修改配置中的 Node 后执行 `{{RUN_NODES_COMMAND}}` 刷新。用例串行运行，首次失败即停止后续用例（`test.bail: 1`）；失败时仍会保存报告并释放连接。报告位于 `midscene_run/report/`。
+
+每份测试文件通过 `fileSetup` 创建独立 Agent，结束后释放。此模板连接一台设备或一个桌面，因此 Project 的 `maxConcurrentFiles` 固定为 1；提高此上限前，需要通过资源分配脚本为并发文件提供独立设备或桌面。

package/dist/templates/test/android/midscene.config.ts

@@ -1,23 +1,21 @@
 import { fileURLToPath } from 'node:url';
 import { AndroidAgent, agentFromAdbDevice } from '@midscene/android';
 import { type NodeExecutionContext, defineNode, z } from '@midscene/test';
-import { defineProjectSetup, defineTestProject } from '@midscene/test/config';
+import { defineFileSetup, defineTestProject } from '@midscene/test/config';
 import { createMidsceneNodes } from '@midscene/test/midscene';
 import { config as loadEnv } from 'dotenv';
 
 loadEnv({ path: fileURLToPath(new URL('.env', import.meta.url)) });
 
-interface ProjectContext {
+interface FileContext {
   agent: AndroidAgent;
 }
 
-const getAgent = ({
-  context,
-}: NodeExecutionContext<unknown, ProjectContext>) => {
+const getAgent = ({ context }: NodeExecutionContext<unknown, FileContext>) => {
   return context.agent;
 };
 
-const setup = defineProjectSetup<ProjectContext>({
+const fileSetup = defineFileSetup<FileContext, undefined>({
   name: 'android',
   async setup({ env, onTeardown }) {
     const agent = await agentFromAdbDevice(env.ANDROID_DEVICE_ID || undefined);
@@ -27,43 +25,42 @@ const setup = defineProjectSetup<ProjectContext>({
 });
 
 const todoSetupInputSchema = z.strictObject({});
-const todoSetup = defineNode<typeof todoSetupInputSchema, void, ProjectContext>(
-  {
-    name: 'todo.setup',
-    title: 'Prepare TodoMVC for the initial-state check',
-    description:
-      'Open React TodoMVC in All view and wait for its input without changing existing tasks.',
-    inputSchema: todoSetupInputSchema,
-    async execute({ context, signal }) {
-      signal.throwIfAborted();
-      await context.agent.launch('https://todomvc.com/examples/react/dist/#/');
-      await context.agent.aiWaitFor(
-        'The React TodoMVC page has loaded and the "What needs to be done?" input is visible.',
-        { timeoutMs: 30_000, abortSignal: signal },
-      );
-      signal.throwIfAborted();
-      return {
-        summary:
-          'Opened TodoMVC in All view; existing tasks were left unchanged.',
-      };
-    },
+const todoSetup = defineNode<typeof todoSetupInputSchema, void, FileContext>({
+  name: 'todo.setup',
+  title: 'Prepare TodoMVC for the initial-state check',
+  description:
+    'Open React TodoMVC in All view and wait for its input without changing existing tasks.',
+  inputSchema: todoSetupInputSchema,
+  async execute({ context, signal }) {
+    signal.throwIfAborted();
+    await context.agent.launch('https://todomvc.com/examples/react/dist/#/');
+    await context.agent.aiWaitFor(
+      'The React TodoMVC page has loaded and the "What needs to be done?" input is visible.',
+      { timeoutMs: 30_000, abortSignal: signal },
+    );
+    signal.throwIfAborted();
+    return {
+      summary:
+        'Opened TodoMVC in All view; existing tasks were left unchanged.',
+    };
   },
-);
+});
 
-export default defineTestProject<ProjectContext>({
+export default defineTestProject<FileContext, undefined>({
   projects: [
     {
       name: 'android',
-      setup,
+      fileSetup,
+      maxConcurrentFiles: 1,
       files: { include: ['cases/**/*.{yaml,yml}'] },
     },
   ],
   nodes: [
     todoSetup,
-    ...createMidsceneNodes<ProjectContext>({
+    ...createMidsceneNodes<FileContext>({
       agentClass: AndroidAgent,
       getAgent,
     }),
   ],
-  test: { maxConcurrency: 1, bail: 1, testTimeout: 720_000 },
+  test: { maxConcurrentFiles: 1, bail: 1, testTimeout: 720_000 },
 });

package/dist/templates/test/computer/.env.example

@@ -1,7 +1,7 @@
 # Copy this file to .env before running tests.
 # Do not commit .env to your repository. In CI, inject these values as environment variables instead.
 # Choose a supported model and copy its four configuration values from:
-# https://midscenejs.com/model-common-config.html
+# https://midscenejs.com/model-api-setup.html
 # For the complete environment variable reference, see:
 # https://midscenejs.com/model-config.html
 # After configuring .env, verify model connectivity and Midscene compatibility from the project directory:

package/dist/templates/test/computer/README.md

@@ -4,7 +4,7 @@ A Midscene Test project for Computer, based on the TodoMVC case in `midscene-exa
 
 If you skipped installation during creation, run `{{INSTALL_COMMAND}}`. The `postinstall` script automatically generates `midscene-node-spec.computer.md` after each dependency installation. If lifecycle scripts are disabled, run `{{RUN_NODES_COMMAND}}` manually.
 
-Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-common-config.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
+Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-api-setup.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
 
 After configuring `.env`, run `{{VERIFY_MODEL_COMMAND}}` from the project directory to check model connectivity and Midscene compatibility. This check does not require a browser or device. If it fails, see [Model debugging and observability](https://midscenejs.com/model-debugging-observability.html) before running tests.
 
@@ -17,3 +17,5 @@ Run tests with `{{TEST_COMMAND}}`. Read `midscene-node-spec.computer.md` for the
 After changing Node registrations in `midscene.config.ts`, run `{{RUN_NODES_COMMAND}}` to refresh the spec. This loads the configuration without connecting to a device or running tests. Extension factories must only acquire runtime resources inside Node execution.
 
 Tests run serially and stop after the first failed case (`test.bail: 1`). Reports are saved and connections are released on failure. Reports are written to `midscene_run/report/`.
+
+Each test file creates its own Agent through `fileSetup` and releases it afterward. The Project is limited to one file at a time because this starter connects to a single device or desktop. Before increasing the Project limit, provide independent devices/displays through your resource allocator.

package/dist/templates/test/computer/README.zh.md

@@ -2,10 +2,12 @@
 
 这是参考 `midscene-example/computer/vitest-demo` TodoMVC 用例的 Computer 版 Midscene Test 项目。
 
-如果创建时跳过安装，执行 `{{INSTALL_COMMAND}}`。安装后会自动生成 `midscene-node-spec.computer.md`；若禁用了安装脚本，手动执行 `{{RUN_NODES_COMMAND}}`。复制 `.env.example` 为 `.env`，按[模型配置指南](https://midscenejs.com/model-common-config.html)配置模型。
+如果创建时跳过安装，执行 `{{INSTALL_COMMAND}}`。安装后会自动生成 `midscene-node-spec.computer.md`；若禁用了安装脚本，手动执行 `{{RUN_NODES_COMMAND}}`。复制 `.env.example` 为 `.env`，按[模型配置指南](https://midscenejs.com/model-api-setup.html)配置模型。
 
 配置后，在项目目录执行 `{{VERIFY_MODEL_COMMAND}}`，检查模型连接和 Midscene 兼容性。这一步不需要浏览器或设备；若检查失败，请先参考[模型调试与可观测性](https://midscenejs.com/model-debugging-observability.html)排查，再运行测试。
 
 按照[桌面环境指南](https://midscenejs.com/platforms/desktop.html)准备权限和依赖。可设置 `COMPUTER_DISPLAY_ID` 选择显示器；无头 Linux 需要 Xvfb 和 `MIDSCENE_COMPUTER_HEADLESS_LINUX`。`cases/todo.yaml` 在 macOS 使用 Safari、在 Windows/Linux 使用 Chrome 打开在线 React TodoMVC，添加三个任务、删除一个、完成另一个、筛选已完成任务，并校验任务名称及输入框占位文字。桌面需要能访问该网站；`beforeEach` 先执行 `midscene.config.ts` 中的 `todo.setup`，打开 All 视图并等待输入框加载，再由 `aiAssert` 确认列表为空（包含已完成任务）且没有遮挡弹窗。已有任务会保留；检查失败时，用例会在修改任务前停止。请切换到 All，删除全部任务（包括已完成任务），或仅清除 TodoMVC 网站的数据；关闭遮挡弹窗后重新运行。模型或连接异常应先按报告中的原因排查。AI 检查可能误判，失败时请结合报告确认页面状态。
 
 执行 `{{TEST_COMMAND}}` 运行测试。Node 列表见 `midscene-node-spec.computer.md`；修改配置中的 Node 后执行 `{{RUN_NODES_COMMAND}}` 刷新。用例串行运行，首次失败即停止后续用例（`test.bail: 1`）；失败时仍会保存报告并释放连接。报告位于 `midscene_run/report/`。
+
+每份测试文件通过 `fileSetup` 创建独立 Agent，结束后释放。此模板连接一台设备或一个桌面，因此 Project 的 `maxConcurrentFiles` 固定为 1；提高此上限前，需要通过资源分配脚本为并发文件提供独立设备或桌面。

package/dist/templates/test/computer/midscene.config.ts

@@ -1,23 +1,21 @@
 import { fileURLToPath } from 'node:url';
 import { ComputerAgent, agentForComputer } from '@midscene/computer';
 import { type NodeExecutionContext, defineNode, z } from '@midscene/test';
-import { defineProjectSetup, defineTestProject } from '@midscene/test/config';
+import { defineFileSetup, defineTestProject } from '@midscene/test/config';
 import { createMidsceneNodes } from '@midscene/test/midscene';
 import { config as loadEnv } from 'dotenv';
 
 loadEnv({ path: fileURLToPath(new URL('.env', import.meta.url)) });
 
-interface ProjectContext {
+interface FileContext {
   agent: ComputerAgent;
 }
 
-const getAgent = ({
-  context,
-}: NodeExecutionContext<unknown, ProjectContext>) => {
+const getAgent = ({ context }: NodeExecutionContext<unknown, FileContext>) => {
   return context.agent;
 };
 
-const setup = defineProjectSetup<ProjectContext>({
+const fileSetup = defineFileSetup<FileContext, undefined>({
   name: 'computer',
   async setup({ env, onTeardown }) {
     const agent = await agentForComputer({
@@ -29,46 +27,45 @@ const setup = defineProjectSetup<ProjectContext>({
 });
 
 const todoSetupInputSchema = z.strictObject({});
-const todoSetup = defineNode<typeof todoSetupInputSchema, void, ProjectContext>(
-  {
-    name: 'todo.setup',
-    title: 'Prepare TodoMVC for the initial-state check',
-    description:
-      'Open React TodoMVC in All view and wait for its input without changing existing tasks.',
-    inputSchema: todoSetupInputSchema,
-    async execute({ context, signal }) {
-      signal.throwIfAborted();
-      await context.agent.aiAct(
-        'Open a browser and navigate to https://todomvc.com/examples/react/dist/#/. On macOS use Safari with Cmd+Space and Cmd+L; on Windows or Linux use Chrome with the Windows key and Ctrl+L. Ensure the All filter is selected if filters are visible. Only navigate and select All; leave every Todo unchanged.',
-        { abortSignal: signal },
-      );
-      await context.agent.aiWaitFor(
-        'The React TodoMVC page has loaded and the "What needs to be done?" input is visible.',
-        { timeoutMs: 30_000, abortSignal: signal },
-      );
-      signal.throwIfAborted();
-      return {
-        summary:
-          'Opened TodoMVC in All view; existing tasks were left unchanged.',
-      };
-    },
+const todoSetup = defineNode<typeof todoSetupInputSchema, void, FileContext>({
+  name: 'todo.setup',
+  title: 'Prepare TodoMVC for the initial-state check',
+  description:
+    'Open React TodoMVC in All view and wait for its input without changing existing tasks.',
+  inputSchema: todoSetupInputSchema,
+  async execute({ context, signal }) {
+    signal.throwIfAborted();
+    await context.agent.aiAct(
+      'Open a browser and navigate to https://todomvc.com/examples/react/dist/#/. On macOS use Safari with Cmd+Space and Cmd+L; on Windows or Linux use Chrome with the Windows key and Ctrl+L. Ensure the All filter is selected if filters are visible. Only navigate and select All; leave every Todo unchanged.',
+      { abortSignal: signal },
+    );
+    await context.agent.aiWaitFor(
+      'The React TodoMVC page has loaded and the "What needs to be done?" input is visible.',
+      { timeoutMs: 30_000, abortSignal: signal },
+    );
+    signal.throwIfAborted();
+    return {
+      summary:
+        'Opened TodoMVC in All view; existing tasks were left unchanged.',
+    };
   },
-);
+});
 
-export default defineTestProject<ProjectContext>({
+export default defineTestProject<FileContext, undefined>({
   projects: [
     {
       name: 'computer',
-      setup,
+      fileSetup,
+      maxConcurrentFiles: 1,
       files: { include: ['cases/**/*.{yaml,yml}'] },
     },
   ],
   nodes: [
     todoSetup,
-    ...createMidsceneNodes<ProjectContext>({
+    ...createMidsceneNodes<FileContext>({
       agentClass: ComputerAgent,
       getAgent,
     }),
   ],
-  test: { maxConcurrency: 1, bail: 1, testTimeout: 360_000 },
+  test: { maxConcurrentFiles: 1, bail: 1, testTimeout: 360_000 },
 });

package/dist/templates/test/harmony/.env.example

@@ -1,7 +1,7 @@
 # Copy this file to .env before running tests.
 # Do not commit .env to your repository. In CI, inject these values as environment variables instead.
 # Choose a supported model and copy its four configuration values from:
-# https://midscenejs.com/model-common-config.html
+# https://midscenejs.com/model-api-setup.html
 # For the complete environment variable reference, see:
 # https://midscenejs.com/model-config.html
 # After configuring .env, verify model connectivity and Midscene compatibility from the project directory:

package/dist/templates/test/harmony/README.md

@@ -4,7 +4,7 @@ A Midscene Test project for HarmonyOS, based on the TodoMVC case in `midscene-ex
 
 If you skipped installation during creation, run `{{INSTALL_COMMAND}}`. The `postinstall` script automatically generates `midscene-node-spec.harmony.md` after each dependency installation. If lifecycle scripts are disabled, run `{{RUN_NODES_COMMAND}}` manually.
 
-Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-common-config.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
+Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-api-setup.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
 
 After configuring `.env`, run `{{VERIFY_MODEL_COMMAND}}` from the project directory to check model connectivity and Midscene compatibility. This check does not require a browser or device. If it fails, see [Model debugging and observability](https://midscenejs.com/model-debugging-observability.html) before running tests.
 
@@ -17,3 +17,5 @@ Run tests with `{{TEST_COMMAND}}`. Read `midscene-node-spec.harmony.md` for the
 After changing Node registrations in `midscene.config.ts`, run `{{RUN_NODES_COMMAND}}` to refresh the spec. This loads the configuration without connecting to a device or running tests. Extension factories must only acquire runtime resources inside Node execution.
 
 Tests run serially and stop after the first failed case (`test.bail: 1`). Reports are saved and connections are released on failure. Reports are written to `midscene_run/report/`.
+
+Each test file creates its own Agent through `fileSetup` and releases it afterward. The Project is limited to one file at a time because this starter connects to a single device or desktop. Before increasing the Project limit, provide independent devices/displays through your resource allocator.

package/dist/templates/test/harmony/README.zh.md

@@ -2,10 +2,12 @@
 
 这是参考 `midscene-example/harmony/vitest-demo` TodoMVC 用例的 HarmonyOS 版 Midscene Test 项目。
 
-如果创建时跳过安装，执行 `{{INSTALL_COMMAND}}`。安装后会自动生成 `midscene-node-spec.harmony.md`；若禁用了安装脚本，手动执行 `{{RUN_NODES_COMMAND}}`。复制 `.env.example` 为 `.env`，按[模型配置指南](https://midscenejs.com/model-common-config.html)配置模型。
+如果创建时跳过安装，执行 `{{INSTALL_COMMAND}}`。安装后会自动生成 `midscene-node-spec.harmony.md`；若禁用了安装脚本，手动执行 `{{RUN_NODES_COMMAND}}`。复制 `.env.example` 为 `.env`，按[模型配置指南](https://midscenejs.com/model-api-setup.html)配置模型。
 
 配置后，在项目目录执行 `{{VERIFY_MODEL_COMMAND}}`，检查模型连接和 Midscene 兼容性。这一步不需要浏览器或设备；若检查失败，请先参考[模型调试与可观测性](https://midscenejs.com/model-debugging-observability.html)排查，再运行测试。
 
 连接设备并用 `hdc list targets` 确认；可设置 `HARMONY_DEVICE_ID` 指定设备，必要时设置 `HDC_HOME`。`cases/todo.yaml` 在浏览器打开在线 React TodoMVC，添加三个任务、删除一个、完成另一个、筛选已完成任务，并校验可见任务和未完成数量。设备需要能访问该网站；`beforeEach` 先执行 `midscene.config.ts` 中的 `todo.setup`，打开 All 视图并等待输入框加载，再由 `aiAssert` 确认列表为空（包含已完成任务）且没有遮挡弹窗。已有任务会保留；检查失败时，用例会在修改任务前停止。请切换到 All，删除全部任务（包括已完成任务），或仅清除 TodoMVC 网站的数据；关闭遮挡弹窗后重新运行。模型或连接异常应先按报告中的原因排查。AI 检查可能误判，失败时请结合报告确认页面状态。
 
 执行 `{{TEST_COMMAND}}` 运行测试。Node 列表见 `midscene-node-spec.harmony.md`；修改配置中的 Node 后执行 `{{RUN_NODES_COMMAND}}` 刷新。用例串行运行，首次失败即停止后续用例（`test.bail: 1`）；失败时仍会保存报告并释放连接。报告位于 `midscene_run/report/`。
+
+每份测试文件通过 `fileSetup` 创建独立 Agent，结束后释放。此模板连接一台设备或一个桌面，因此 Project 的 `maxConcurrentFiles` 固定为 1；提高此上限前，需要通过资源分配脚本为并发文件提供独立设备或桌面。

package/dist/templates/test/harmony/midscene.config.ts

@@ -1,23 +1,21 @@
 import { fileURLToPath } from 'node:url';
 import { HarmonyAgent, agentFromHdcDevice } from '@midscene/harmony';
 import { type NodeExecutionContext, defineNode, z } from '@midscene/test';
-import { defineProjectSetup, defineTestProject } from '@midscene/test/config';
+import { defineFileSetup, defineTestProject } from '@midscene/test/config';
 import { createMidsceneNodes } from '@midscene/test/midscene';
 import { config as loadEnv } from 'dotenv';
 
 loadEnv({ path: fileURLToPath(new URL('.env', import.meta.url)) });
 
-interface ProjectContext {
+interface FileContext {
   agent: HarmonyAgent;
 }
 
-const getAgent = ({
-  context,
-}: NodeExecutionContext<unknown, ProjectContext>) => {
+const getAgent = ({ context }: NodeExecutionContext<unknown, FileContext>) => {
   return context.agent;
 };
 
-const setup = defineProjectSetup<ProjectContext>({
+const fileSetup = defineFileSetup<FileContext, undefined>({
   name: 'harmony',
   async setup({ env, onTeardown }) {
     const agent = await agentFromHdcDevice(env.HARMONY_DEVICE_ID || undefined);
@@ -27,43 +25,42 @@ const setup = defineProjectSetup<ProjectContext>({
 });
 
 const todoSetupInputSchema = z.strictObject({});
-const todoSetup = defineNode<typeof todoSetupInputSchema, void, ProjectContext>(
-  {
-    name: 'todo.setup',
-    title: 'Prepare TodoMVC for the initial-state check',
-    description:
-      'Open React TodoMVC in All view and wait for its input without changing existing tasks.',
-    inputSchema: todoSetupInputSchema,
-    async execute({ context, signal }) {
-      signal.throwIfAborted();
-      await context.agent.launch('https://todomvc.com/examples/react/dist/#/');
-      await context.agent.aiWaitFor(
-        'The React TodoMVC page has loaded and the "What needs to be done?" input is visible.',
-        { timeoutMs: 30_000, abortSignal: signal },
-      );
-      signal.throwIfAborted();
-      return {
-        summary:
-          'Opened TodoMVC in All view; existing tasks were left unchanged.',
-      };
-    },
+const todoSetup = defineNode<typeof todoSetupInputSchema, void, FileContext>({
+  name: 'todo.setup',
+  title: 'Prepare TodoMVC for the initial-state check',
+  description:
+    'Open React TodoMVC in All view and wait for its input without changing existing tasks.',
+  inputSchema: todoSetupInputSchema,
+  async execute({ context, signal }) {
+    signal.throwIfAborted();
+    await context.agent.launch('https://todomvc.com/examples/react/dist/#/');
+    await context.agent.aiWaitFor(
+      'The React TodoMVC page has loaded and the "What needs to be done?" input is visible.',
+      { timeoutMs: 30_000, abortSignal: signal },
+    );
+    signal.throwIfAborted();
+    return {
+      summary:
+        'Opened TodoMVC in All view; existing tasks were left unchanged.',
+    };
   },
-);
+});
 
-export default defineTestProject<ProjectContext>({
+export default defineTestProject<FileContext, undefined>({
   projects: [
     {
       name: 'harmony',
-      setup,
+      fileSetup,
+      maxConcurrentFiles: 1,
       files: { include: ['cases/**/*.{yaml,yml}'] },
     },
   ],
   nodes: [
     todoSetup,
-    ...createMidsceneNodes<ProjectContext>({
+    ...createMidsceneNodes<FileContext>({
       agentClass: HarmonyAgent,
       getAgent,
     }),
   ],
-  test: { maxConcurrency: 1, bail: 1, testTimeout: 720_000 },
+  test: { maxConcurrentFiles: 1, bail: 1, testTimeout: 720_000 },
 });

package/dist/templates/test/ios/.env.example

@@ -1,7 +1,7 @@
 # Copy this file to .env before running tests.
 # Do not commit .env to your repository. In CI, inject these values as environment variables instead.
 # Choose a supported model and copy its four configuration values from:
-# https://midscenejs.com/model-common-config.html
+# https://midscenejs.com/model-api-setup.html
 # For the complete environment variable reference, see:
 # https://midscenejs.com/model-config.html
 # After configuring .env, verify model connectivity and Midscene compatibility from the project directory:

package/dist/templates/test/ios/README.md

@@ -4,7 +4,7 @@ A Midscene Test project for iOS, based on the TodoMVC case in `midscene-example/
 
 If you skipped installation during creation, run `{{INSTALL_COMMAND}}`. The `postinstall` script automatically generates `midscene-node-spec.ios.md` after each dependency installation. If lifecycle scripts are disabled, run `{{RUN_NODES_COMMAND}}` manually.
 
-Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-common-config.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
+Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-api-setup.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
 
 After configuring `.env`, run `{{VERIFY_MODEL_COMMAND}}` from the project directory to check model connectivity and Midscene compatibility. This check does not require a browser or device. If it fails, see [Model debugging and observability](https://midscenejs.com/model-debugging-observability.html) before running tests.
 
@@ -17,3 +17,5 @@ Run tests with `{{TEST_COMMAND}}`. Read `midscene-node-spec.ios.md` for the avai
 After changing Node registrations in `midscene.config.ts`, run `{{RUN_NODES_COMMAND}}` to refresh the spec. This loads the configuration without connecting to a device or running tests. Extension factories must only acquire runtime resources inside Node execution.
 
 Tests run serially and stop after the first failed case (`test.bail: 1`). Reports are saved and connections are released on failure. Reports are written to `midscene_run/report/`.
+
+Each test file creates its own Agent through `fileSetup` and releases it afterward. The Project is limited to one file at a time because this starter connects to a single device or desktop. Before increasing the Project limit, provide independent devices/displays through your resource allocator.

package/dist/templates/test/ios/README.zh.md

@@ -2,10 +2,12 @@
 
 这是参考 `midscene-example/ios/vitest-demo` TodoMVC 用例的 iOS 版 Midscene Test 项目。
 
-如果创建时跳过安装，执行 `{{INSTALL_COMMAND}}`。安装后会自动生成 `midscene-node-spec.ios.md`；若禁用了安装脚本，手动执行 `{{RUN_NODES_COMMAND}}`。复制 `.env.example` 为 `.env`，按[模型配置指南](https://midscenejs.com/model-common-config.html)配置模型。
+如果创建时跳过安装，执行 `{{INSTALL_COMMAND}}`。安装后会自动生成 `midscene-node-spec.ios.md`；若禁用了安装脚本，手动执行 `{{RUN_NODES_COMMAND}}`。复制 `.env.example` 为 `.env`，按[模型配置指南](https://midscenejs.com/model-api-setup.html)配置模型。
 
 配置后，在项目目录执行 `{{VERIFY_MODEL_COMMAND}}`，检查模型连接和 Midscene 兼容性。这一步不需要浏览器或设备；若检查失败，请先参考[模型调试与可观测性](https://midscenejs.com/model-debugging-observability.html)排查，再运行测试。
 
 启动 WebDriverAgent。可设置 `WDA_HOST` 和 `WDA_PORT`，或用 `WDA_BASE_URL` 指定带路径前缀的网关地址。远程 MJPEG 流可设置 `WDA_MJPEG_URL`，直连则可设置 `WDA_MJPEG_PORT`。`cases/todo.yaml` 打开在线 React TodoMVC，添加三个任务、删除一个、完成另一个、筛选已完成任务，并校验可见任务和未完成数量。设备需要能访问该网站；`beforeEach` 先执行 `midscene.config.ts` 中的 `todo.setup`，打开 All 视图并等待输入框加载，再由 `aiAssert` 确认列表为空（包含已完成任务）且没有遮挡弹窗。已有任务会保留；检查失败时，用例会在修改任务前停止。请切换到 All，删除全部任务（包括已完成任务），或仅清除 TodoMVC 网站的数据；关闭遮挡弹窗后重新运行。模型或连接异常应先按报告中的原因排查。AI 检查可能误判，失败时请结合报告确认页面状态。
 
 执行 `{{TEST_COMMAND}}` 运行测试。Node 列表见 `midscene-node-spec.ios.md`；修改配置中的 Node 后执行 `{{RUN_NODES_COMMAND}}` 刷新。用例串行运行，首次失败即停止后续用例（`test.bail: 1`）；失败时仍会保存报告并释放连接。报告位于 `midscene_run/report/`。
+
+每份测试文件通过 `fileSetup` 创建独立 Agent，结束后释放。此模板连接一台设备或一个桌面，因此 Project 的 `maxConcurrentFiles` 固定为 1；提高此上限前，需要通过资源分配脚本为并发文件提供独立设备或桌面。

package/dist/templates/test/ios/midscene.config.ts

@@ -1,23 +1,21 @@
 import { fileURLToPath } from 'node:url';
 import { IOSAgent, agentFromWebDriverAgent } from '@midscene/ios';
 import { type NodeExecutionContext, defineNode, z } from '@midscene/test';
-import { defineProjectSetup, defineTestProject } from '@midscene/test/config';
+import { defineFileSetup, defineTestProject } from '@midscene/test/config';
 import { createMidsceneNodes } from '@midscene/test/midscene';
 import { config as loadEnv } from 'dotenv';
 
 loadEnv({ path: fileURLToPath(new URL('.env', import.meta.url)) });
 
-interface ProjectContext {
+interface FileContext {
   agent: IOSAgent;
 }
 
-const getAgent = ({
-  context,
-}: NodeExecutionContext<unknown, ProjectContext>) => {
+const getAgent = ({ context }: NodeExecutionContext<unknown, FileContext>) => {
   return context.agent;
 };
 
-const setup = defineProjectSetup<ProjectContext>({
+const fileSetup = defineFileSetup<FileContext, undefined>({
   name: 'ios',
   async setup({ env, onTeardown }) {
     const wdaBaseUrl = env.WDA_BASE_URL || undefined;
@@ -56,40 +54,39 @@ const setup = defineProjectSetup<ProjectContext>({
 });
 
 const todoSetupInputSchema = z.strictObject({});
-const todoSetup = defineNode<typeof todoSetupInputSchema, void, ProjectContext>(
-  {
-    name: 'todo.setup',
-    title: 'Prepare TodoMVC for the initial-state check',
-    description:
-      'Open React TodoMVC in All view and wait for its input without changing existing tasks.',
-    inputSchema: todoSetupInputSchema,
-    async execute({ context, signal }) {
-      signal.throwIfAborted();
-      await context.agent.launch('https://todomvc.com/examples/react/dist/#/');
-      await context.agent.aiWaitFor(
-        'The React TodoMVC page has loaded and the "What needs to be done?" input is visible.',
-        { timeoutMs: 30_000, abortSignal: signal },
-      );
-      signal.throwIfAborted();
-      return {
-        summary:
-          'Opened TodoMVC in All view; existing tasks were left unchanged.',
-      };
-    },
+const todoSetup = defineNode<typeof todoSetupInputSchema, void, FileContext>({
+  name: 'todo.setup',
+  title: 'Prepare TodoMVC for the initial-state check',
+  description:
+    'Open React TodoMVC in All view and wait for its input without changing existing tasks.',
+  inputSchema: todoSetupInputSchema,
+  async execute({ context, signal }) {
+    signal.throwIfAborted();
+    await context.agent.launch('https://todomvc.com/examples/react/dist/#/');
+    await context.agent.aiWaitFor(
+      'The React TodoMVC page has loaded and the "What needs to be done?" input is visible.',
+      { timeoutMs: 30_000, abortSignal: signal },
+    );
+    signal.throwIfAborted();
+    return {
+      summary:
+        'Opened TodoMVC in All view; existing tasks were left unchanged.',
+    };
   },
-);
+});
 
-export default defineTestProject<ProjectContext>({
+export default defineTestProject<FileContext, undefined>({
   projects: [
     {
       name: 'ios',
-      setup,
+      fileSetup,
+      maxConcurrentFiles: 1,
       files: { include: ['cases/**/*.{yaml,yml}'] },
     },
   ],
   nodes: [
     todoSetup,
-    ...createMidsceneNodes<ProjectContext>({ agentClass: IOSAgent, getAgent }),
+    ...createMidsceneNodes<FileContext>({ agentClass: IOSAgent, getAgent }),
   ],
-  test: { maxConcurrency: 1, bail: 1, testTimeout: 720_000 },
+  test: { maxConcurrentFiles: 1, bail: 1, testTimeout: 720_000 },
 });

package/dist/templates/test/web/.env.example

@@ -1,7 +1,7 @@
 # Copy this file to .env before running tests.
 # Do not commit .env to your repository. In CI, inject these values as environment variables instead.
 # Choose a supported model and copy its four configuration values from:
-# https://midscenejs.com/model-common-config.html
+# https://midscenejs.com/model-api-setup.html
 # For the complete environment variable reference, see:
 # https://midscenejs.com/model-config.html
 # After configuring .env, verify model connectivity and Midscene compatibility from the project directory:

package/dist/templates/test/web/README.md

@@ -4,7 +4,7 @@ A Midscene Test project for Web, based on the TodoMVC Test Runner example. For d
 
 If you skipped installation during creation, run `{{INSTALL_COMMAND}}`. The `postinstall` script automatically generates `midscene-node-spec.web.md` after each dependency installation. If lifecycle scripts are disabled, run `{{RUN_NODES_COMMAND}}` manually.
 
-Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-common-config.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
+Copy `.env.example` to `.env`, then choose and configure a model using the [supported models and setup guide](https://midscenejs.com/model-api-setup.html). Do not commit `.env` to your repository; inject the model configuration as environment variables in CI.
 
 After configuring `.env`, run `{{VERIFY_MODEL_COMMAND}}` from the project directory to check model connectivity and Midscene compatibility. This check does not require a browser or device. If it fails, see [Model debugging and observability](https://midscenejs.com/model-debugging-observability.html) before running tests.
 
@@ -17,3 +17,19 @@ Run tests with `{{TEST_COMMAND}}`. Read `midscene-node-spec.web.md` for the avai
 After changing Node registrations in `midscene.config.ts`, run `{{RUN_NODES_COMMAND}}` to refresh the spec. This loads the configuration without connecting to a device or running tests. Extension factories must only acquire runtime resources inside Node execution.
 
 Tests run serially and stop after the first failed case (`test.bail: 1`). Reports are saved and the browser is closed on failure. Reports are written to `midscene_run/report/`.
+
+## How preparation works
+
+| Stage | Frequency | What this example does |
+| --- | --- | --- |
+| `setup` (project configuration) | Once per project | Starts a shared Browser |
+| `fileSetup` (project configuration) | Once per file | Creates a separate BrowserContext and Page; returns the Node `context` |
+| `beforeAll` (YAML) | Once before the file's cases | Sets the viewport; the first `getAgent` call creates the Agent for later Nodes to reuse |
+
+`fileSetup` applies to every file; each file declares its own `beforeAll`. The business Node `todo.setup` is unrelated to the `setup` configuration field.
+
+## Usage notes
+
+- Raise `test.maxConcurrentFiles` to run files concurrently. Cases within a file stay sequential.
+- Retries do not repeat these three stages; `beforeEach` resets business state.
+- File cleanup destroys the Agent and closes the BrowserContext. The Browser closes after all file cleanup. Isolate backend accounts and data separately.