@midscene/test 1.16.0 → 1.16.1

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

@@ -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

@@ -9,3 +9,5 @@
 连接设备并用 `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/README.md

@@ -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

@@ -9,3 +9,5 @@
 按照[桌面环境指南](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/README.md

@@ -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

@@ -9,3 +9,5 @@
 连接设备并用 `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/README.md

@@ -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

@@ -9,3 +9,5 @@
 启动 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/README.md

@@ -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.

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

@@ -11,3 +11,19 @@
 `cases/todo.yaml` 使用在线 React TodoMVC。每条用例先由 `todo.setup` 打开 All 视图、清空页面存储并重新加载，通过 DOM 确认列表为空，再由 `todo.seed` 添加三个任务；第一条用例校验初始化状态，第二条用 AI 删除和完成任务，再校验最终状态。`todo.captureState` 在每条用例后记录页面状态。运行时需要能访问 TodoMVC 网站。
 
 执行 `{{TEST_COMMAND}}` 运行测试。Node 列表见 `midscene-node-spec.web.md`；修改配置中的 Node 后执行 `{{RUN_NODES_COMMAND}}` 刷新。用例串行运行，首次失败即停止后续用例（`test.bail: 1`）；失败时仍会保存报告并关闭浏览器。报告位于 `midscene_run/report/`。
+
+## 准备工作如何执行
+
+| 阶段 | 次数 | 本例中的工作 |
+| --- | --- | --- |
+| `setup`（项目配置） | 项目一次 | 启动共享 Browser |
+| `fileSetup`（项目配置） | 每份文件一次 | 创建独立 BrowserContext、Page，返回 Node 使用的 `context` |
+| `beforeAll`（YAML） | 文件用例开始前一次 | 设置视口；首次调用 `getAgent` 创建 Agent，后续 Node 复用 |
+
+`fileSetup` 自动应用到每份文件；`beforeAll` 由各文件声明。业务 Node `todo.setup` 与配置项 `setup` 无关。
+
+## 注意事项
+
+- 提高 `test.maxConcurrentFiles` 可并发运行文件，文件内用例仍顺序执行。
+- 重试不重跑上述三个阶段；`beforeEach` 负责重置业务状态。
+- 文件结束后先销毁 Agent、关闭 BrowserContext；所有文件清理完再关闭 Browser。后端账号和数据需自行隔离。

package/dist/templates/test/web/cases/todo.yaml

@@ -1,8 +1,10 @@
+# fileSetup has prepared this file's page; getAgent creates its Agent on first use.
 beforeAll:
   - setViewportSize:
       width: 1280
       height: 720
 
+# Reset business state for every case attempt, including retries.
 beforeEach:
   - todo.setup: {}
   - todo.seed:

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

@@ -1,26 +1,34 @@
 import { fileURLToPath } from 'node:url';
 import type { NodeExecutionContext } from '@midscene/test';
-import { defineProjectSetup, defineTestProject } from '@midscene/test/config';
+import {
+  defineFileSetup,
+  defineProjectSetup,
+  defineTestProject,
+} from '@midscene/test/config';
 import { createMidsceneNodes } from '@midscene/test/midscene';
 import { PlaywrightAgent } from '@midscene/web/playwright/agent';
 import { config as loadEnv } from 'dotenv';
-import { type Page, chromium } from 'playwright';
+import { type Browser, type Page, chromium } from 'playwright';
 import { createTodoNodes } from './nodes/todo';
 
 loadEnv({ path: fileURLToPath(new URL('.env', import.meta.url)) });
 
-interface ProjectContext {
+interface FileContext {
   page: Page;
   agent?: PlaywrightAgent;
 }
 
-const getAgent = ({
-  context,
-}: NodeExecutionContext<unknown, ProjectContext>) => {
+interface ProjectContext {
+  browser: Browser;
+}
+
+// Create the Agent on first use; reuse it within this file.
+const getAgent = ({ context }: NodeExecutionContext<unknown, FileContext>) => {
   context.agent ??= new PlaywrightAgent(context.page);
   return context.agent;
 };
 
+// Once per project: keep the shared Browser until every file has cleaned up.
 const setup = defineProjectSetup<ProjectContext>({
   name: 'web',
   async setup({ env, onTeardown }) {
@@ -28,8 +36,21 @@ const setup = defineProjectSetup<ProjectContext>({
       headless: env.HEADLESS !== 'false',
     });
     onTeardown(() => browser.close());
-    const page = await browser.newPage();
-    const context: ProjectContext = { page };
+    return { browser };
+  },
+});
+
+// Before each file's beforeAll: create its session, page, and Node context.
+const fileSetup = defineFileSetup<FileContext, ProjectContext>({
+  name: 'web-file',
+  async setup({ projectContext, signal, onTeardown }) {
+    if (!projectContext)
+      throw new Error('Web Project setup did not create a browser.');
+    const browserContext = await projectContext.browser.newContext();
+    onTeardown(() => browserContext.close());
+    signal.throwIfAborted();
+    const page = await browserContext.newPage();
+    const context: FileContext = { page };
     onTeardown(async () => {
       await context.agent?.destroy();
     });
@@ -37,20 +58,21 @@ const setup = defineProjectSetup<ProjectContext>({
   },
 });
 
-export default defineTestProject<ProjectContext>({
+export default defineTestProject<FileContext, ProjectContext>({
   projects: [
     {
       name: 'web',
       setup,
+      fileSetup,
       files: { include: ['cases/**/*.{yaml,yml}'] },
     },
   ],
   nodes: [
-    ...createTodoNodes<ProjectContext>({ getPage: (context) => context.page }),
-    ...createMidsceneNodes<ProjectContext>({
+    ...createTodoNodes<FileContext>({ getPage: (context) => context.page }),
+    ...createMidsceneNodes<FileContext>({
       agentClass: PlaywrightAgent,
       getAgent,
     }),
   ],
-  test: { maxConcurrency: 1, bail: 1, testTimeout: 600_000 },
+  test: { maxConcurrentFiles: 1, bail: 1, testTimeout: 600_000 },
 });