MID-5: support Web YAML downloadPath (#2688)

* feat(web-integration): support yaml download path

* fix(web-integration): keep download behavior session active

* test(web-integration): cover yaml download path

* fix(web-integration): use puppeteer download behavior option

---------

Co-authored-by: Multica Helper <midscene@users.noreply.github.com>
Co-authored-by: quanru <quanruzhuoxiu@gmail.com>
Co-authored-by: ottomao <ottomao@gmail.com>

Author: 3 people

apps/site/docs/en/automate-with-scripts-in-yaml.mdx

@@ -166,6 +166,11 @@ web:
   # Path to a JSON format browser cookie file, optional.
   cookie: <path-to-cookie-file>
 
+  # Chrome download directory (Puppeteer only), optional.
+  # Relative paths are resolved from the current working directory.
+  # Not supported in bridge mode.
+  downloadPath: <path-to-download-directory>
+
   # Extra HTTP headers sent with every request (Puppeteer only), optional.
   # Useful when the server validates custom request headers.
   # Values must be strings; quote values YAML would treat as a boolean or number, e.g. "true".

apps/site/docs/en/bridge-mode.mdx

@@ -110,6 +110,9 @@ In bridge mode, these options will be ignored (they will follow your desktop bro
 - deviceScaleFactor
 - waitForNetworkIdle
 - cookie
+- extraHTTPHeaders
+- downloadPath
+- chromeArgs
 
 ## Remote Access Configuration
 

apps/site/docs/zh/automate-with-scripts-in-yaml.mdx

@@ -165,6 +165,11 @@ web:
   # JSON 格式的浏览器 Cookie 文件路径，可选
   cookie: <path-to-cookie-file>
 
+  # Chrome 下载目录（仅 Puppeteer 模式），可选
+  # 相对路径会基于当前工作目录解析
+  # bridgeMode 不支持该选项
+  downloadPath: <path-to-download-directory>
+
   # 随每个请求发送的额外 HTTP 请求头（仅 Puppeteer 模式），可选
   # 适用于服务器会校验自定义请求头的场景
   # 值必须是字符串；像 true、false、纯数字这类会被 YAML 解析为非字符串的值需加引号，如 "true"

apps/site/docs/zh/bridge-mode.mdx

@@ -102,6 +102,9 @@ midscene ./bing.yaml
 - `deviceScaleFactor`
 - `waitForNetworkIdle`
 - `cookie`
+- `extraHTTPHeaders`
+- `downloadPath`
+- `chromeArgs`
 
 ## 远程访问配置
 

packages/cli/src/create-yaml-player.ts

@@ -17,7 +17,10 @@ import type { AbstractInterface } from '@midscene/core/device';
 import { processCacheConfig } from '@midscene/core/utils';
 import { getDebug } from '@midscene/shared/logger';
 import { AgentOverChromeBridge } from '@midscene/web/bridge-mode';
-import { puppeteerAgentForTarget } from '@midscene/web/puppeteer-agent-launcher';
+import {
+  buildDownloadBehavior,
+  puppeteerAgentForTarget,
+} from '@midscene/web/puppeteer-agent-launcher';
 import type { Browser, Page } from 'puppeteer';
 import puppeteer from 'puppeteer';
 
@@ -187,6 +190,7 @@ export async function createYamlPlayer(
             (await puppeteer.connect({
               browserWSEndpoint: webTarget.cdpEndpoint,
               defaultViewport: null,
+              downloadBehavior: buildDownloadBehavior(webTarget.downloadPath),
             }));
 
           // Warn about options that don't apply to an already-running browser
@@ -261,6 +265,7 @@ export async function createYamlPlayer(
           'waitForNetworkIdle',
           'cookie',
           'extraHTTPHeaders',
+          'downloadPath',
           'chromeArgs',
         ];
         const ignoredKeys = bridgeUnsupportedKeys.filter(

packages/cli/src/yaml-batch-executor.ts

@@ -10,6 +10,7 @@ import type {
 import { type ScriptPlayer, parseYamlScript } from '@midscene/core/yaml';
 import {
   buildChromeArgs,
+  buildDownloadBehavior,
   defaultViewportHeight,
   defaultViewportWidth,
 } from '@midscene/web/puppeteer-agent-launcher';
@@ -127,6 +128,9 @@ class YamlBatchExecutor {
           browser = await puppeteer.connect({
             browserWSEndpoint: globalWebConfig.cdpEndpoint,
             defaultViewport: null,
+            downloadBehavior: buildDownloadBehavior(
+              globalWebConfig.downloadPath,
+            ),
           });
         } else {
           // Extract viewport dimensions from global config or use defaults
@@ -145,6 +149,9 @@ class YamlBatchExecutor {
           browser = await puppeteer.launch({
             headless: !headed,
             defaultViewport: headed ? null : { width, height },
+            downloadBehavior: buildDownloadBehavior(
+              globalWebConfig?.downloadPath,
+            ),
             args,
             acceptInsecureCerts: globalWebConfig?.acceptInsecureCerts,
           });

packages/cli/tests/unit-test/batch-runner.test.ts

@@ -6,6 +6,7 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs';
+import path from 'node:path';
 import { BatchRunner } from '@/batch-runner';
 import { createYamlPlayer } from '@/create-yaml-player';
 import type {
@@ -61,7 +62,18 @@ vi.mock('@midscene/web/puppeteer-agent-launcher', async (importOriginal) => {
     await importOriginal<
       typeof import('@midscene/web/puppeteer-agent-launcher')
     >();
-  return { ...original };
+  return {
+    ...original,
+    buildDownloadBehavior: (downloadPath: string | undefined) =>
+      downloadPath
+        ? {
+            policy: 'allow',
+            downloadPath: downloadPath.startsWith('/')
+              ? downloadPath
+              : `${process.cwd()}/${downloadPath.replace(/^\.\//, '')}`,
+          }
+        : undefined,
+  };
 });
 vi.mock('@midscene/web/bridge-mode');
 vi.mock('@midscene/android');
@@ -213,6 +225,30 @@ describe('BatchRunner', () => {
       expect(launchCall).toHaveProperty('acceptInsecureCerts', true);
     });
 
+    test('should pass downloadPath to Puppeteer launch options when shareBrowserContext is true', async () => {
+      const config = {
+        ...mockBatchConfig,
+        shareBrowserContext: true,
+        files: ['web1.yml'],
+        globalConfig: {
+          web: {
+            url: 'http://example.com',
+            downloadPath: './downloads',
+          },
+        },
+      };
+      const runner = new BatchRunner(config);
+      await runner.run();
+
+      expect(puppeteer.launch).toHaveBeenCalledTimes(1);
+
+      const launchCall = vi.mocked(puppeteer.launch).mock.calls[0][0];
+      expect(launchCall).toHaveProperty('downloadBehavior', {
+        policy: 'allow',
+        downloadPath: path.resolve('./downloads'),
+      });
+    });
+
     test('should not create a shared browser instance when shareBrowserContext is false', async () => {
       const config = {
         ...mockBatchConfig,
@@ -273,11 +309,38 @@ describe('BatchRunner', () => {
       expect(puppeteer.connect).toHaveBeenCalledWith({
         browserWSEndpoint: 'ws://localhost:9222/devtools/browser/xxx',
         defaultViewport: null,
+        downloadBehavior: undefined,
       });
       // Should NOT call launch
       expect(puppeteer.launch).not.toHaveBeenCalled();
     });
 
+    test('should pass downloadPath to Puppeteer connect options when shareBrowserContext uses CDP', async () => {
+      const config = {
+        ...mockBatchConfig,
+        shareBrowserContext: true,
+        files: ['web1.yml'],
+        globalConfig: {
+          web: {
+            url: 'http://example.com',
+            cdpEndpoint: 'ws://localhost:9222/devtools/browser/xxx',
+            downloadPath: './downloads',
+          },
+        },
+      };
+      const runner = new BatchRunner(config);
+      await runner.run();
+
+      expect(puppeteer.connect).toHaveBeenCalledWith({
+        browserWSEndpoint: 'ws://localhost:9222/devtools/browser/xxx',
+        defaultViewport: null,
+        downloadBehavior: {
+          policy: 'allow',
+          downloadPath: path.resolve('./downloads'),
+        },
+      });
+    });
+
     test('should disconnect (not close) browser in CDP mode', async () => {
       const mockDisconnect = vi.fn();
       const mockClose = vi.fn().mockResolvedValue(undefined);

packages/cli/tests/unit-test/create-yaml-player.test.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { createYamlPlayer, launchServer } from '@/create-yaml-player';
 import type { MidsceneYamlScript, MidsceneYamlScriptEnv } from '@midscene/core';
 import { processCacheConfig } from '@midscene/core/utils';
@@ -47,9 +48,25 @@ vi.mock('@midscene/web/bridge-mode', () => ({
   AgentOverChromeBridge: vi.fn(),
 }));
 
-vi.mock('@midscene/web/puppeteer-agent-launcher', () => ({
-  puppeteerAgentForTarget: vi.fn(),
-}));
+vi.mock('@midscene/web/puppeteer-agent-launcher', async (importOriginal) => {
+  const original =
+    await importOriginal<
+      typeof import('@midscene/web/puppeteer-agent-launcher')
+    >();
+  return {
+    ...original,
+    buildDownloadBehavior: (downloadPath: string | undefined) =>
+      downloadPath
+        ? {
+            policy: 'allow',
+            downloadPath: downloadPath.startsWith('/')
+              ? downloadPath
+              : `${process.cwd()}/${downloadPath.replace(/^\.\//, '')}`,
+          }
+        : undefined,
+    puppeteerAgentForTarget: vi.fn(),
+  };
+});
 
 vi.mock('@midscene/web/puppeteer', () => ({
   PuppeteerAgent: vi.fn(),
@@ -275,6 +292,42 @@ describe('create-yaml-player', () => {
 
       expect(result).toBe(mockPlayer);
     });
+
+    test('should pass web downloadPath to puppeteer agent launcher', async () => {
+      const mockScript: MidsceneYamlScript = {
+        web: {
+          url: 'http://example.com',
+          downloadPath: './downloads',
+        },
+        tasks: [],
+      };
+      const mockAgent = { destroy: vi.fn() };
+      let setupFnCallback: (() => Promise<any>) | undefined;
+
+      vi.mocked(puppeteerAgentForTarget).mockResolvedValue({
+        agent: mockAgent as any,
+        freeFn: [],
+      });
+      vi.mocked(ScriptPlayer).mockImplementation((script, setupFn) => {
+        setupFnCallback = setupFn as () => Promise<any>;
+        return {
+          addCleanup: vi.fn(),
+        } as unknown as ScriptPlayer<MidsceneYamlScriptEnv>;
+      });
+
+      await createYamlPlayer(mockFilePath, mockScript);
+      await setupFnCallback?.();
+
+      expect(puppeteerAgentForTarget).toHaveBeenCalledWith(
+        expect.objectContaining({
+          url: 'http://example.com',
+          downloadPath: './downloads',
+        }),
+        expect.any(Object),
+        undefined,
+        undefined,
+      );
+    });
   });
 
   describe('Cache configuration - Legacy compatibility mode', () => {
@@ -821,6 +874,44 @@ describe('create-yaml-player', () => {
       );
     });
 
+    test('should warn that downloadPath is ignored in bridge mode', async () => {
+      const mockScript: MidsceneYamlScript = {
+        web: {
+          url: 'http://example.com',
+          bridgeMode: 'newTabWithUrl',
+          downloadPath: './downloads',
+        },
+        tasks: [],
+      };
+
+      const mockAgent = {
+        destroy: vi.fn(),
+        connectNewTabWithUrl: vi.fn().mockResolvedValue(undefined),
+      };
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      let setupFnCallback: (() => Promise<any>) | undefined;
+
+      vi.mocked(readFileSync).mockReturnValue('mock yaml content');
+      vi.mocked(parseYamlScript).mockReturnValue(mockScript);
+      vi.mocked(AgentOverChromeBridge).mockImplementation(
+        () => mockAgent as any,
+      );
+      vi.mocked(ScriptPlayer).mockImplementation((script, setupFn) => {
+        setupFnCallback = setupFn as () => Promise<any>;
+        return {
+          addCleanup: vi.fn(),
+        } as unknown as ScriptPlayer<MidsceneYamlScriptEnv>;
+      });
+
+      await createYamlPlayer(mockFilePath, mockScript);
+      await setupFnCallback?.();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('downloadPath'),
+      );
+      warnSpy.mockRestore();
+    });
+
     test('should handle undefined aiActionContext gracefully for Android', async () => {
       const mockScript: MidsceneYamlScript = {
         android: {
@@ -1300,6 +1391,7 @@ describe('create-yaml-player', () => {
       expect(puppeteer.connect).toHaveBeenCalledWith({
         browserWSEndpoint: 'ws://localhost:9222/devtools/browser/xxx',
         defaultViewport: null,
+        downloadBehavior: undefined,
       });
 
       // Should reuse puppeteerAgentForTarget (page setup: viewport, userAgent, etc.)
@@ -1311,6 +1403,53 @@ describe('create-yaml-player', () => {
       );
     });
 
+    test('should configure download behavior via Puppeteer connect options in CDP mode', async () => {
+      const mockScript: MidsceneYamlScript = {
+        web: {
+          url: 'http://example.com',
+          cdpEndpoint: 'ws://localhost:9222/devtools/browser/xxx',
+          downloadPath: './downloads',
+        },
+        tasks: [],
+      };
+
+      const mockBrowser = {
+        disconnect: vi.fn(),
+      };
+      const mockAgent = { destroy: vi.fn() };
+      let setupFnCallback: (() => Promise<any>) | undefined;
+
+      vi.mocked(readFileSync).mockReturnValue('mock yaml content');
+      vi.mocked(parseYamlScript).mockReturnValue(mockScript);
+
+      const puppeteer = (await import('puppeteer')).default;
+      vi.mocked(puppeteer.connect).mockResolvedValue(mockBrowser as any);
+
+      vi.mocked(puppeteerAgentForTarget).mockResolvedValue({
+        agent: mockAgent as any,
+        freeFn: [],
+      });
+
+      vi.mocked(ScriptPlayer).mockImplementation((script, setupFn) => {
+        setupFnCallback = setupFn as () => Promise<any>;
+        return {
+          addCleanup: vi.fn(),
+        } as unknown as ScriptPlayer<MidsceneYamlScriptEnv>;
+      });
+
+      await createYamlPlayer(mockFilePath, mockScript);
+      await setupFnCallback?.();
+
+      expect(puppeteer.connect).toHaveBeenCalledWith({
+        browserWSEndpoint: 'ws://localhost:9222/devtools/browser/xxx',
+        defaultViewport: null,
+        downloadBehavior: {
+          policy: 'allow',
+          downloadPath: path.resolve('./downloads'),
+        },
+      });
+    });
+
     test('should pass agent options in CDP mode via puppeteerAgentForTarget', async () => {
       const mockScript: MidsceneYamlScript = {
         web: {