feat(test): discover native ESM config

Author: quanru

apps/site/docs/en/midscene-test/configuration.mdx

@@ -10,10 +10,10 @@ Midscene Test supports the following configuration files:
 
 | How the configuration is selected | Supported file | Loading behavior |
 | --- | --- | --- |
-| Automatic discovery, when no configuration path is provided | `midscene.config.ts` only | Transformed from TypeScript and loaded |
+| Automatic discovery, when no configuration path is provided | `midscene.config.ts` or `midscene.config.mjs` | `.ts` is transformed from TypeScript; `.mjs` is loaded by Node.js as native ESM |
 | An explicit path passed through the CLI's `--config <path>` option or `loadTestProject(path)` | `.ts` or `.mjs` | `.ts` is transformed from TypeScript; `.mjs` is loaded by Node.js as native ESM without TypeScript transformation |
 
-For a typical project, create `midscene.config.ts` in the project root and run Midscene Test without `--config`. Use `.mjs` when another build step already emits the configuration as JavaScript, and pass that file explicitly. A file named `midscene.config.mjs` is not discovered automatically.
+For a typical project, create `midscene.config.ts` in the project root and run Midscene Test without `--config`. If another build step emits the configuration as JavaScript, name it `midscene.config.mjs` and it is discovered in the same way. If both files exist, Midscene Test reports a conflict instead of choosing one silently; use `--config <path>` to select the intended file explicitly.
 
 Create browser or device resources in `setup` and register the corresponding Agent Nodes through `nodes`. These determine the capabilities available to each execution project.
 
@@ -452,7 +452,7 @@ import {
 } from '@midscene/test';
 ```
 
-- **`loadTestProject(path)`**: asynchronously loads an explicitly provided TypeScript (`.ts`) or JavaScript ESM (`.mjs`) project configuration. Without an explicit path, the CLI discovers only `midscene.config.ts`. Midscene Test does not support synchronous loading.
+- **`loadTestProject(path)`**: asynchronously loads an explicitly provided TypeScript (`.ts`) or JavaScript ESM (`.mjs`) project configuration. Without `--config`, the CLI discovers `midscene.config.ts` or `midscene.config.mjs`; if both exist, it asks you to select one explicitly. Midscene Test does not support synchronous loading.
 - **`runTestProject()`**: asynchronously discovers, runs, and summarizes the entire project.
 - **`CaseRunner` / `createCaseRunner()`**: directly runs one test case represented as a plain object, without file parsing or lifecycle management.
 - **`runWorkflowDocument()`**: runs the complete lifecycle and every Case in one document.

apps/site/docs/zh/midscene-test/configuration.mdx

@@ -10,10 +10,10 @@ Midscene Test 支持以下配置文件：
 
 | 配置文件的选择方式 | 支持的文件 | 加载方式 |
 | --- | --- | --- |
-| 未指定配置路径，由 Midscene Test 自动查找 | 仅支持 `midscene.config.ts` | 先转换 TypeScript，再加载配置 |
+| 未指定配置路径，由 Midscene Test 自动查找 | `midscene.config.ts` 或 `midscene.config.mjs` | `.ts` 会先经过 TypeScript 转换；`.mjs` 由 Node.js 作为原生 ESM 直接加载 |
 | 通过 CLI 的 `--config <路径>` 或 `loadTestProject(路径)` 显式指定 | `.ts` 或 `.mjs` | `.ts` 会先经过 TypeScript 转换；`.mjs` 由 Node.js 作为原生 ESM 直接加载，不经过 TypeScript 转换 |
 
-一般情况下，在项目根目录创建 `midscene.config.ts`，运行 Midscene Test 时无需传入 `--config`。如果配置已经由其他构建流程输出为 JavaScript，可以使用 `.mjs`，但必须显式传入文件路径。Midscene Test 不会自动查找名为 `midscene.config.mjs` 的文件。
+一般情况下，在项目根目录创建 `midscene.config.ts`，运行 Midscene Test 时无需传入 `--config`。如果配置已经由其他构建流程输出为 JavaScript，将它命名为 `midscene.config.mjs`，Midscene Test 也会自动查找。如果两个文件同时存在，Midscene Test 会报告冲突，不会静默选择其中一个；此时请通过 `--config <路径>` 明确指定要使用的文件。
 
 在 `setup` 中创建浏览器或设备资源，并通过 `nodes` 注册对应 Agent 的 Node。这些资源和 Node 决定各执行项目可用的能力。
 
@@ -446,7 +446,7 @@ import {
 } from '@midscene/test';
 ```
 
-* **`loadTestProject(path)`**：异步加载显式指定的 TypeScript（`.ts`）或 JavaScript ESM（`.mjs`）项目配置。CLI 未收到显式路径时，只会自动查找 `midscene.config.ts`。Midscene Test 不支持同步加载。
+* **`loadTestProject(path)`**：异步加载显式指定的 TypeScript（`.ts`）或 JavaScript ESM（`.mjs`）项目配置。CLI 未收到 `--config` 时，会自动查找 `midscene.config.ts` 或 `midscene.config.mjs`；如果两者同时存在，则要求明确指定一个。Midscene Test 不支持同步加载。
 * **`runTestProject()`**：异步发现、运行并汇总整个项目。
 * **`CaseRunner` / `createCaseRunner()`**：直接执行纯对象形式的单个用例（不含文件解析和生命周期控制）。
 * **`runWorkflowDocument()`**：执行单个文档的完整生命周期及内部全部 Case。

packages/test/src/cli/test-project-runner.ts

@@ -48,7 +48,7 @@ import type {
   TestProjectRunSummary,
 } from './types';
 
-const CONFIG_NAME = 'midscene.config.ts';
+const CONFIG_NAMES = ['midscene.config.ts', 'midscene.config.mjs'] as const;
 const CONFIG_PREFIX = 'midscene.config.';
 const ALWAYS_IGNORED_PATTERNS = [
   '.git/**',
@@ -117,17 +117,31 @@ export const discoverTestConfig = (projectRoot: string): string | undefined => {
   const candidates = readdirSync(root)
     .filter((name) => name.startsWith(CONFIG_PREFIX))
     .sort();
-  const unsupported = candidates.filter((name) => name !== CONFIG_NAME);
+  const supported = candidates.filter((name) =>
+    CONFIG_NAMES.includes(name as (typeof CONFIG_NAMES)[number]),
+  );
+  const unsupported = candidates.filter(
+    (name) => !CONFIG_NAMES.includes(name as (typeof CONFIG_NAMES)[number]),
+  );
   if (unsupported.length > 0) {
     throw new Error(
       [
         `Unsupported or conflicting Midscene configs found in ${root}:`,
         ...candidates.map((name) => `- ${name}`),
-        `Only ${CONFIG_NAME} is supported.`,
+        `Only ${CONFIG_NAMES.join(' and ')} are supported.`,
+      ].join('\n'),
+    );
+  }
+  if (supported.length > 1) {
+    throw new Error(
+      [
+        `Multiple Midscene configs found in ${root}:`,
+        ...supported.map((name) => `- ${name}`),
+        'Pass --config <path> to select one explicitly.',
       ].join('\n'),
     );
   }
-  return candidates.includes(CONFIG_NAME) ? join(root, CONFIG_NAME) : undefined;
+  return supported[0] ? join(root, supported[0]) : undefined;
 };
 
 const defaultResultDir = (projectRoot: string): string =>

packages/test/tests/test-project-runner.test.ts

@@ -81,14 +81,38 @@ describe('test project main-process runner', () => {
     ).toBe('20260807090504-12345678');
   });
 
-  it('discovers only midscene.config.ts', () => {
+  it('discovers midscene.config.ts', () => {
     const root = createProject();
     const configPath = join(root, 'midscene.config.ts');
     writeFileSync(configPath, 'export default { nodes: [] };');
 
     expect(discoverTestConfig(root)).toBe(configPath);
   });
 
+  it('discovers midscene.config.mjs', () => {
+    const root = createProject();
+    const configPath = join(root, 'midscene.config.mjs');
+    writeFileSync(configPath, 'export default { nodes: [] };');
+
+    expect(discoverTestConfig(root)).toBe(configPath);
+  });
+
+  it('requires an explicit config when both supported names exist', () => {
+    const root = createProject();
+    writeFileSync(
+      join(root, 'midscene.config.ts'),
+      'export default { nodes: [] };',
+    );
+    writeFileSync(
+      join(root, 'midscene.config.mjs'),
+      'export default { nodes: [] };',
+    );
+
+    expect(() => discoverTestConfig(root)).toThrow(
+      'Pass --config <path> to select one explicitly.',
+    );
+  });
+
   it.each(['js', 'cjs', 'mts', 'cts', 'tsx'])(
     'rejects a midscene.config.%s discovery candidate',
     (extension) => {
@@ -100,7 +124,7 @@ describe('test project main-process runner', () => {
       writeFileSync(join(root, `midscene.config.${extension}`), 'unsupported');
 
       expect(() => discoverTestConfig(root)).toThrow(
-        'Only midscene.config.ts is supported.',
+        'Only midscene.config.ts and midscene.config.mjs are supported.',
       );
     },
   );