@midscene/testing-framework 0.0.0

package/dist/lib/runtime/setup.js

@@ -0,0 +1,96 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    createDefaultSetup: ()=>createDefaultSetup,
+    setupFrameworkAgent: ()=>setupFrameworkAgent
+});
+async function createAndroidSetup(config, context) {
+    const { agentFromAdbDevice } = await import("@midscene/android");
+    const options = config.target?.options || {};
+    const { deviceId, launch, ...deviceOptions } = options;
+    const agent = await agentFromAdbDevice('string' == typeof deviceId ? deviceId : void 0, {
+        ...context.agentOptions,
+        ...deviceOptions
+    });
+    if ('string' == typeof launch && launch) await agent.launch(launch);
+    return {
+        agent,
+        async teardown () {
+            if ('string' == typeof launch && launch && !launch.startsWith('http')) await agent.terminate(launch);
+        }
+    };
+}
+async function createWebSetup(config, context) {
+    const [{ PlaywrightAgent }, { chromium }] = await Promise.all([
+        import("@midscene/web/playwright"),
+        import("playwright")
+    ]);
+    const options = config.target?.options || {};
+    if (!options.url) throw new Error('target.options.url is required for the web target');
+    const browser = await chromium.launch({
+        headless: options.headless ?? true,
+        args: [
+            '--no-sandbox',
+            '--disable-setuid-sandbox'
+        ]
+    });
+    const browserContext = await browser.newContext({
+        viewport: options.viewport
+    });
+    const page = await browserContext.newPage();
+    await page.goto(options.url);
+    return {
+        agent: new PlaywrightAgent(page, context.agentOptions),
+        browser,
+        context: browserContext,
+        page,
+        async teardown () {
+            await browserContext.close();
+            await browser.close();
+        }
+    };
+}
+async function createDefaultSetup(config, context) {
+    if (!config.target) throw new Error('midscene config must provide "target" or "setup"');
+    if ('android' === config.target.type) return createAndroidSetup(config, context);
+    if ('web' === config.target.type) return createWebSetup(config, context);
+    throw new Error(`Unsupported target.type: ${config.target.type}`);
+}
+async function setupFrameworkAgent(config, context) {
+    if (config.setup) return config.setup(context);
+    return createDefaultSetup(config, context);
+}
+exports.createDefaultSetup = __webpack_exports__.createDefaultSetup;
+exports.setupFrameworkAgent = __webpack_exports__.setupFrameworkAgent;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createDefaultSetup",
+    "setupFrameworkAgent"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});
+
+//# sourceMappingURL=setup.js.map

package/dist/lib/runtime/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime/setup.js","sources":["webpack/runtime/define_property_getters","webpack/runtime/has_own_property","webpack/runtime/make_namespace_object","../../../src/runtime/setup.ts"],"sourcesContent":["__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n        if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n            Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n        }\n    }\n};","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};","import type {\n  FrameworkSetupResult,\n  MidsceneFrameworkConfig,\n  SetupContext,\n} from '../types';\n\ninterface DefaultSetupContext extends SetupContext {}\n\nasync function createAndroidSetup(\n  config: MidsceneFrameworkConfig,\n  context: DefaultSetupContext,\n): Promise<FrameworkSetupResult> {\n  const { agentFromAdbDevice } = await import('@midscene/android');\n  const options = (config.target?.options || {}) as Record<string, unknown>;\n  const { deviceId, launch, ...deviceOptions } = options;\n\n  const agent = await agentFromAdbDevice(\n    typeof deviceId === 'string' ? deviceId : undefined,\n    {\n      ...context.agentOptions,\n      ...deviceOptions,\n    },\n  );\n\n  if (typeof launch === 'string' && launch) {\n    await agent.launch(launch);\n  }\n\n  return {\n    agent,\n    async teardown() {\n      // Only terminate launched apps, not URLs opened in the default browser.\n      if (typeof launch === 'string' && launch && !launch.startsWith('http')) {\n        await agent.terminate(launch);\n      }\n    },\n  };\n}\n\nasync function createWebSetup(\n  config: MidsceneFrameworkConfig,\n  context: DefaultSetupContext,\n): Promise<FrameworkSetupResult> {\n  const [{ PlaywrightAgent }, { chromium }] = await Promise.all([\n    import('@midscene/web/playwright'),\n    import('playwright'),\n  ]);\n\n  const options = (config.target?.options || {}) as {\n    url?: string;\n    viewport?: { width: number; height: number };\n    headless?: boolean;\n  };\n\n  if (!options.url) {\n    throw new Error('target.options.url is required for the web target');\n  }\n\n  const browser = await chromium.launch({\n    headless: options.headless ?? true,\n    args: ['--no-sandbox', '--disable-setuid-sandbox'],\n  });\n  const browserContext = await browser.newContext({\n    viewport: options.viewport,\n  });\n  const page = await browserContext.newPage();\n  await page.goto(options.url);\n\n  return {\n    agent: new PlaywrightAgent(page, context.agentOptions),\n    browser,\n    context: browserContext,\n    page,\n    async teardown() {\n      await browserContext.close();\n      await browser.close();\n    },\n  };\n}\n\n/**\n * Create an agent from the default `target` config. Only the `web` and\n * `android` targets documented for the first version are supported.\n */\nexport async function createDefaultSetup(\n  config: MidsceneFrameworkConfig,\n  context: DefaultSetupContext,\n): Promise<FrameworkSetupResult> {\n  if (!config.target) {\n    throw new Error('midscene config must provide \"target\" or \"setup\"');\n  }\n\n  if (config.target.type === 'android') {\n    return createAndroidSetup(config, context);\n  }\n\n  if (config.target.type === 'web') {\n    return createWebSetup(config, context);\n  }\n\n  throw new Error(`Unsupported target.type: ${config.target.type}`);\n}\n\n/**\n * Resolve the suite agent. A custom `setup` takes precedence; otherwise the\n * default target setup is used.\n */\nexport async function setupFrameworkAgent(\n  config: MidsceneFrameworkConfig,\n  context: DefaultSetupContext,\n): Promise<FrameworkSetupResult> {\n  if (config.setup) {\n    return config.setup(context);\n  }\n\n  return createDefaultSetup(config, context);\n}\n"],"names":["__webpack_require__","definition","key","Object","obj","prop","Symbol","createAndroidSetup","config","context","agentFromAdbDevice","options","deviceId","launch","deviceOptions","agent","undefined","createWebSetup","PlaywrightAgent","chromium","Promise","Error","browser","browserContext","page","createDefaultSetup","setupFrameworkAgent"],"mappings":";;;IAAAA,oBAAoB,CAAC,GAAG,CAAC,UAASC;QACjC,IAAI,IAAIC,OAAOD,WACR,IAAGD,oBAAoB,CAAC,CAACC,YAAYC,QAAQ,CAACF,oBAAoB,CAAC,CAAC,UAASE,MACzEC,OAAO,cAAc,CAAC,UAASD,KAAK;YAAE,YAAY;YAAM,KAAKD,UAAU,CAACC,IAAI;QAAC;IAGzF;;;ICNAF,oBAAoB,CAAC,GAAG,CAACI,KAAKC,OAAUF,OAAO,SAAS,CAAC,cAAc,CAAC,IAAI,CAACC,KAAKC;;;ICClFL,oBAAoB,CAAC,GAAG,CAAC;QACxB,IAAG,AAAkB,eAAlB,OAAOM,UAA0BA,OAAO,WAAW,EACrDH,OAAO,cAAc,CAAC,UAASG,OAAO,WAAW,EAAE;YAAE,OAAO;QAAS;QAEtEH,OAAO,cAAc,CAAC,UAAS,cAAc;YAAE,OAAO;QAAK;IAC5D;;;;;;;;ACEA,eAAeI,mBACbC,MAA+B,EAC/BC,OAA4B;IAE5B,MAAM,EAAEC,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC;IAC5C,MAAMC,UAAWH,OAAO,MAAM,EAAE,WAAW,CAAC;IAC5C,MAAM,EAAEI,QAAQ,EAAEC,MAAM,EAAE,GAAGC,eAAe,GAAGH;IAE/C,MAAMI,QAAQ,MAAML,mBAClB,AAAoB,YAApB,OAAOE,WAAwBA,WAAWI,QAC1C;QACE,GAAGP,QAAQ,YAAY;QACvB,GAAGK,aAAa;IAClB;IAGF,IAAI,AAAkB,YAAlB,OAAOD,UAAuBA,QAChC,MAAME,MAAM,MAAM,CAACF;IAGrB,OAAO;QACLE;QACA,MAAM;YAEJ,IAAI,AAAkB,YAAlB,OAAOF,UAAuBA,UAAU,CAACA,OAAO,UAAU,CAAC,SAC7D,MAAME,MAAM,SAAS,CAACF;QAE1B;IACF;AACF;AAEA,eAAeI,eACbT,MAA+B,EAC/BC,OAA4B;IAE5B,MAAM,CAAC,EAAES,eAAe,EAAE,EAAE,EAAEC,QAAQ,EAAE,CAAC,GAAG,MAAMC,QAAQ,GAAG,CAAC;QAC5D,MAAM,CAAC;QACP,MAAM,CAAC;KACR;IAED,MAAMT,UAAWH,OAAO,MAAM,EAAE,WAAW,CAAC;IAM5C,IAAI,CAACG,QAAQ,GAAG,EACd,MAAM,IAAIU,MAAM;IAGlB,MAAMC,UAAU,MAAMH,SAAS,MAAM,CAAC;QACpC,UAAUR,QAAQ,QAAQ,IAAI;QAC9B,MAAM;YAAC;YAAgB;SAA2B;IACpD;IACA,MAAMY,iBAAiB,MAAMD,QAAQ,UAAU,CAAC;QAC9C,UAAUX,QAAQ,QAAQ;IAC5B;IACA,MAAMa,OAAO,MAAMD,eAAe,OAAO;IACzC,MAAMC,KAAK,IAAI,CAACb,QAAQ,GAAG;IAE3B,OAAO;QACL,OAAO,IAAIO,gBAAgBM,MAAMf,QAAQ,YAAY;QACrDa;QACA,SAASC;QACTC;QACA,MAAM;YACJ,MAAMD,eAAe,KAAK;YAC1B,MAAMD,QAAQ,KAAK;QACrB;IACF;AACF;AAMO,eAAeG,mBACpBjB,MAA+B,EAC/BC,OAA4B;IAE5B,IAAI,CAACD,OAAO,MAAM,EAChB,MAAM,IAAIa,MAAM;IAGlB,IAAIb,AAAuB,cAAvBA,OAAO,MAAM,CAAC,IAAI,EACpB,OAAOD,mBAAmBC,QAAQC;IAGpC,IAAID,AAAuB,UAAvBA,OAAO,MAAM,CAAC,IAAI,EACpB,OAAOS,eAAeT,QAAQC;IAGhC,MAAM,IAAIY,MAAM,CAAC,yBAAyB,EAAEb,OAAO,MAAM,CAAC,IAAI,EAAE;AAClE;AAMO,eAAekB,oBACpBlB,MAA+B,EAC/BC,OAA4B;IAE5B,IAAID,OAAO,KAAK,EACd,OAAOA,OAAO,KAAK,CAACC;IAGtB,OAAOgB,mBAAmBjB,QAAQC;AACpC"}

package/dist/lib/runtime/source.js

@@ -0,0 +1,61 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    createYamlFrameworkSuiteSource: ()=>createYamlFrameworkSuiteSource
+});
+function createYamlFrameworkSuiteSource(options) {
+    const runtimeImport = options.runtimeImport || '@midscene/testing-framework/runtime';
+    const rstestImport = options.rstestImport || '@rstest/core';
+    const tests = options.cases.map((item)=>`test(${JSON.stringify(item.testName)}, async () => {\n  await runtime.runCase(${JSON.stringify(item.filePath)}, ${JSON.stringify(item.resultFile)});\n});`).join('\n\n');
+    return `import { afterAll, beforeAll, test } from ${JSON.stringify(rstestImport)};
+import config from ${JSON.stringify(options.configPath)};
+import { createSuiteRuntime } from ${JSON.stringify(runtimeImport)};
+
+const runtime = createSuiteRuntime({
+  config,
+  projectDir: ${JSON.stringify(options.projectDir)},
+});
+
+beforeAll(async () => {
+  await runtime.setup();
+});
+
+afterAll(async () => {
+  await runtime.teardown();
+});
+
+${tests}
+`;
+}
+exports.createYamlFrameworkSuiteSource = __webpack_exports__.createYamlFrameworkSuiteSource;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createYamlFrameworkSuiteSource"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});
+
+//# sourceMappingURL=source.js.map

package/dist/lib/runtime/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime/source.js","sources":["webpack/runtime/define_property_getters","webpack/runtime/has_own_property","webpack/runtime/make_namespace_object","../../../src/runtime/source.ts"],"sourcesContent":["__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n        if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n            Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n        }\n    }\n};","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};","export interface FrameworkSuiteSourceCase {\n  filePath: string;\n  testName: string;\n  resultFile: string;\n}\n\nexport interface CreateYamlFrameworkSuiteSourceOptions {\n  configPath: string;\n  projectDir: string;\n  cases: FrameworkSuiteSourceCase[];\n  /** Import specifier for `@midscene/testing-framework/runtime`. */\n  runtimeImport?: string;\n  /** Import specifier for the Rstest test API. */\n  rstestImport?: string;\n}\n\n/**\n * Generate the source of a single Rstest module that owns the whole YAML suite:\n * it sets the shared agent up once, registers one `test()` per YAML case, and\n * tears the agent down once. Each YAML case therefore maps to one Rstest test,\n * while suite-level setup/teardown and shared `state` are preserved.\n */\nexport function createYamlFrameworkSuiteSource(\n  options: CreateYamlFrameworkSuiteSourceOptions,\n): string {\n  const runtimeImport =\n    options.runtimeImport || '@midscene/testing-framework/runtime';\n  const rstestImport = options.rstestImport || '@rstest/core';\n\n  const tests = options.cases\n    .map(\n      (item) =>\n        `test(${JSON.stringify(item.testName)}, async () => {\\n  await runtime.runCase(${JSON.stringify(\n          item.filePath,\n        )}, ${JSON.stringify(item.resultFile)});\\n});`,\n    )\n    .join('\\n\\n');\n\n  return `import { afterAll, beforeAll, test } from ${JSON.stringify(rstestImport)};\nimport config from ${JSON.stringify(options.configPath)};\nimport { createSuiteRuntime } from ${JSON.stringify(runtimeImport)};\n\nconst runtime = createSuiteRuntime({\n  config,\n  projectDir: ${JSON.stringify(options.projectDir)},\n});\n\nbeforeAll(async () => {\n  await runtime.setup();\n});\n\nafterAll(async () => {\n  await runtime.teardown();\n});\n\n${tests}\n`;\n}\n"],"names":["__webpack_require__","definition","key","Object","obj","prop","Symbol","createYamlFrameworkSuiteSource","options","runtimeImport","rstestImport","tests","item","JSON"],"mappings":";;;IAAAA,oBAAoB,CAAC,GAAG,CAAC,UAASC;QACjC,IAAI,IAAIC,OAAOD,WACR,IAAGD,oBAAoB,CAAC,CAACC,YAAYC,QAAQ,CAACF,oBAAoB,CAAC,CAAC,UAASE,MACzEC,OAAO,cAAc,CAAC,UAASD,KAAK;YAAE,YAAY;YAAM,KAAKD,UAAU,CAACC,IAAI;QAAC;IAGzF;;;ICNAF,oBAAoB,CAAC,GAAG,CAACI,KAAKC,OAAUF,OAAO,SAAS,CAAC,cAAc,CAAC,IAAI,CAACC,KAAKC;;;ICClFL,oBAAoB,CAAC,GAAG,CAAC;QACxB,IAAG,AAAkB,eAAlB,OAAOM,UAA0BA,OAAO,WAAW,EACrDH,OAAO,cAAc,CAAC,UAASG,OAAO,WAAW,EAAE;YAAE,OAAO;QAAS;QAEtEH,OAAO,cAAc,CAAC,UAAS,cAAc;YAAE,OAAO;QAAK;IAC5D;;;;;;;ACgBO,SAASI,+BACdC,OAA8C;IAE9C,MAAMC,gBACJD,QAAQ,aAAa,IAAI;IAC3B,MAAME,eAAeF,QAAQ,YAAY,IAAI;IAE7C,MAAMG,QAAQH,QAAQ,KAAK,CACxB,GAAG,CACF,CAACI,OACC,CAAC,KAAK,EAAEC,KAAK,SAAS,CAACD,KAAK,QAAQ,EAAE,yCAAyC,EAAEC,KAAK,SAAS,CAC7FD,KAAK,QAAQ,EACb,EAAE,EAAEC,KAAK,SAAS,CAACD,KAAK,UAAU,EAAE,OAAO,CAAC,EAEjD,IAAI,CAAC;IAER,OAAO,CAAC,0CAA0C,EAAEC,KAAK,SAAS,CAACH,cAAc;mBAChE,EAAEG,KAAK,SAAS,CAACL,QAAQ,UAAU,EAAE;mCACrB,EAAEK,KAAK,SAAS,CAACJ,eAAe;;;;cAIrD,EAAEI,KAAK,SAAS,CAACL,QAAQ,UAAU,EAAE;;;;;;;;;;;AAWnD,EAAEG,MAAM;AACR,CAAC;AACD"}

package/dist/lib/runtime/yaml.js

@@ -0,0 +1,138 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    normalizeYamlCase: ()=>normalizeYamlCase,
+    runBuiltinYamlCase: ()=>runBuiltinYamlCase,
+    runYamlFlowWithCustomSteps: ()=>runYamlFlowWithCustomSteps
+});
+const external_node_path_namespaceObject = require("node:path");
+const external_js_yaml_namespaceObject = require("js-yaml");
+var external_js_yaml_default = /*#__PURE__*/ __webpack_require__.n(external_js_yaml_namespaceObject);
+const external_builtin_steps_js_namespaceObject = require("../builtin-steps.js");
+const caseNameFromPath = (filePath)=>(0, external_node_path_namespaceObject.basename)(filePath, (0, external_node_path_namespaceObject.extname)(filePath)) || 'case';
+function normalizeYamlCase(content, filePath) {
+    const parsed = external_js_yaml_default().load(content);
+    if (!parsed || 'object' != typeof parsed || Array.isArray(parsed)) throw new Error(`${filePath} must be a YAML object`);
+    if (Array.isArray(parsed.flow)) {
+        const { flow, ...rest } = parsed;
+        return {
+            name: caseNameFromPath(filePath),
+            flow: flow,
+            raw: rest
+        };
+    }
+    if (Array.isArray(parsed.tasks)) throw new Error(`${filePath} uses a full "tasks" document; framework cases must use a top-level "flow"`);
+    throw new Error(`${filePath} must include a top-level "flow" array`);
+}
+const dumpSingleStepTask = (caseName, step)=>external_js_yaml_default().dump({
+        tasks: [
+            {
+                name: caseName,
+                flow: [
+                    step
+                ]
+            }
+        ]
+    }, {
+        lineWidth: -1,
+        noRefs: true
+    });
+const resolveStepName = (step, yamlSteps)=>{
+    const keys = Object.keys(step);
+    const customKey = keys.find((key)=>yamlSteps?.[key]);
+    if (customKey) return {
+        stepName: customKey,
+        kind: 'custom'
+    };
+    const builtinKey = keys.find((key)=>external_builtin_steps_js_namespaceObject.BUILTIN_YAML_STEP_NAMES.has(key));
+    if (builtinKey) return {
+        stepName: builtinKey,
+        kind: 'builtin'
+    };
+    return {
+        stepName: keys[0] ?? '',
+        kind: 'unknown'
+    };
+};
+async function runYamlFlowWithCustomSteps(options) {
+    for (const [stepIndex, step] of options.flow.entries()){
+        if (!step || 'object' != typeof step || Array.isArray(step)) throw new Error(`${options.filePath} step ${stepIndex + 1} must be an object`);
+        const stepRecord = step;
+        const { stepName, kind } = resolveStepName(stepRecord, options.yamlSteps);
+        if ('custom' === kind) {
+            const handler = options.yamlSteps[stepName];
+            await handler(stepRecord[stepName], {
+                agent: options.agent,
+                state: options.state,
+                filePath: options.filePath,
+                stepIndex,
+                stepName
+            });
+            continue;
+        }
+        if ('builtin' === kind) {
+            await options.agent.runYaml(dumpSingleStepTask(`${options.caseName}:${stepName}`, step));
+            continue;
+        }
+        throw new Error(`${options.filePath} step ${stepIndex + 1} uses unknown step "${stepName}"`);
+    }
+}
+async function runBuiltinYamlCase(options) {
+    await options.agent.runYaml(external_js_yaml_default().dump({
+        ...options.normalizedCase.raw,
+        tasks: [
+            {
+                name: options.normalizedCase.name,
+                flow: options.normalizedCase.flow
+            }
+        ]
+    }, {
+        lineWidth: -1,
+        noRefs: true
+    }));
+}
+exports.normalizeYamlCase = __webpack_exports__.normalizeYamlCase;
+exports.runBuiltinYamlCase = __webpack_exports__.runBuiltinYamlCase;
+exports.runYamlFlowWithCustomSteps = __webpack_exports__.runYamlFlowWithCustomSteps;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "normalizeYamlCase",
+    "runBuiltinYamlCase",
+    "runYamlFlowWithCustomSteps"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});
+
+//# sourceMappingURL=yaml.js.map

package/dist/lib/runtime/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime/yaml.js","sources":["webpack/runtime/compat_get_default_export","webpack/runtime/define_property_getters","webpack/runtime/has_own_property","webpack/runtime/make_namespace_object","../../../src/runtime/yaml.ts"],"sourcesContent":["// getDefaultExport function for compatibility with non-ESM modules\n__webpack_require__.n = (module) => {\n\tvar getter = module && module.__esModule ?\n\t\t() => (module['default']) :\n\t\t() => (module);\n\t__webpack_require__.d(getter, { a: getter });\n\treturn getter;\n};\n","__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n        if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n            Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n        }\n    }\n};","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};","import { basename, extname } from 'node:path';\nimport type { MidsceneYamlFlowItem } from '@midscene/core';\nimport yaml from 'js-yaml';\nimport { BUILTIN_YAML_STEP_NAMES } from '../builtin-steps';\nimport type {\n  CustomYamlStepHandler,\n  FrameworkAgent,\n  NormalizedYamlCase,\n} from '../types';\n\nconst caseNameFromPath = (filePath: string): string =>\n  basename(filePath, extname(filePath)) || 'case';\n\n/**\n * Convert a framework YAML case (top-level `flow`) into a normalized shape. The\n * first version intentionally requires the documented top-level `flow` form and\n * rejects full `tasks` documents.\n */\nexport function normalizeYamlCase(\n  content: string,\n  filePath: string,\n): NormalizedYamlCase {\n  const parsed = yaml.load(content) as Record<string, unknown> | undefined;\n  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    throw new Error(`${filePath} must be a YAML object`);\n  }\n\n  if (Array.isArray(parsed.flow)) {\n    const { flow, ...rest } = parsed;\n    return {\n      name: caseNameFromPath(filePath),\n      flow: flow as MidsceneYamlFlowItem[],\n      raw: rest,\n    };\n  }\n\n  if (Array.isArray((parsed as { tasks?: unknown }).tasks)) {\n    throw new Error(\n      `${filePath} uses a full \"tasks\" document; framework cases must use a top-level \"flow\"`,\n    );\n  }\n\n  throw new Error(`${filePath} must include a top-level \"flow\" array`);\n}\n\nconst dumpSingleStepTask = (caseName: string, step: unknown): string =>\n  yaml.dump(\n    {\n      tasks: [\n        {\n          name: caseName,\n          flow: [step],\n        },\n      ],\n    },\n    { lineWidth: -1, noRefs: true },\n  );\n\nconst resolveStepName = (\n  step: Record<string, unknown>,\n  yamlSteps: Record<string, CustomYamlStepHandler> | undefined,\n): { stepName: string; kind: 'custom' | 'builtin' | 'unknown' } => {\n  const keys = Object.keys(step);\n\n  // A custom step is identified by the registered key; built-in steps may carry\n  // extra sibling keys (e.g. `aiInput` + `value`), so we look the action key up\n  // instead of requiring exactly one key.\n  const customKey = keys.find((key) => yamlSteps?.[key]);\n  if (customKey) {\n    return { stepName: customKey, kind: 'custom' };\n  }\n\n  const builtinKey = keys.find((key) => BUILTIN_YAML_STEP_NAMES.has(key));\n  if (builtinKey) {\n    return { stepName: builtinKey, kind: 'builtin' };\n  }\n\n  return { stepName: keys[0] ?? '', kind: 'unknown' };\n};\n\n/**\n * Run a flow step by step so built-in steps and custom `yamlSteps` interleave in\n * the authored order. Built-in steps are forwarded to `agent.runYaml`; custom\n * steps invoke their handler with the YAML value and the current context.\n */\nexport async function runYamlFlowWithCustomSteps(options: {\n  agent: FrameworkAgent;\n  filePath: string;\n  caseName: string;\n  flow: MidsceneYamlFlowItem[];\n  yamlSteps?: Record<string, CustomYamlStepHandler>;\n  state: Record<string, unknown>;\n}): Promise<void> {\n  for (const [stepIndex, step] of options.flow.entries()) {\n    if (!step || typeof step !== 'object' || Array.isArray(step)) {\n      throw new Error(\n        `${options.filePath} step ${stepIndex + 1} must be an object`,\n      );\n    }\n\n    const stepRecord = step as Record<string, unknown>;\n    const { stepName, kind } = resolveStepName(stepRecord, options.yamlSteps);\n\n    if (kind === 'custom') {\n      const handler = options.yamlSteps![stepName];\n      await handler(stepRecord[stepName], {\n        agent: options.agent,\n        state: options.state,\n        filePath: options.filePath,\n        stepIndex,\n        stepName,\n      });\n      continue;\n    }\n\n    if (kind === 'builtin') {\n      await options.agent.runYaml(\n        dumpSingleStepTask(`${options.caseName}:${stepName}`, step),\n      );\n      continue;\n    }\n\n    throw new Error(\n      `${options.filePath} step ${stepIndex + 1} uses unknown step \"${stepName}\"`,\n    );\n  }\n}\n\n/**\n * Run a whole built-in case in a single `agent.runYaml` invocation. Used when no\n * custom `yamlSteps` are registered, so the existing YAML runner handles the\n * complete flow at once.\n */\nexport async function runBuiltinYamlCase(options: {\n  agent: FrameworkAgent;\n  normalizedCase: NormalizedYamlCase;\n}): Promise<void> {\n  await options.agent.runYaml(\n    yaml.dump(\n      {\n        ...options.normalizedCase.raw,\n        tasks: [\n          {\n            name: options.normalizedCase.name,\n            flow: options.normalizedCase.flow,\n          },\n        ],\n      },\n      { lineWidth: -1, noRefs: true },\n    ),\n  );\n}\n"],"names":["__webpack_require__","module","getter","definition","key","Object","obj","prop","Symbol","caseNameFromPath","filePath","basename","extname","normalizeYamlCase","content","parsed","yaml","Array","Error","flow","rest","dumpSingleStepTask","caseName","step","resolveStepName","yamlSteps","keys","customKey","builtinKey","BUILTIN_YAML_STEP_NAMES","runYamlFlowWithCustomSteps","options","stepIndex","stepRecord","stepName","kind","handler","runBuiltinYamlCase"],"mappings":"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"}

package/dist/lib/types.js

@@ -0,0 +1,20 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});
+
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":["webpack/runtime/make_namespace_object"],"sourcesContent":["// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};"],"names":["__webpack_require__","Symbol","Object"],"mappings":";;;IACAA,oBAAoB,CAAC,GAAG,CAAC;QACxB,IAAG,AAAkB,eAAlB,OAAOC,UAA0BA,OAAO,WAAW,EACrDC,OAAO,cAAc,CAAC,UAASD,OAAO,WAAW,EAAE;YAAE,OAAO;QAAS;QAEtEC,OAAO,cAAc,CAAC,UAAS,cAAc;YAAE,OAAO;QAAK;IAC5D"}

package/dist/types/builtin-steps.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Built-in Midscene YAML step keys. When a `flow` step's action key matches one
+ * of these, the framework hands the step to the existing `agent.runYaml`
+ * runner. Custom `yamlSteps` are not allowed to reuse these names.
+ *
+ * The set covers the keys documented for #2509 plus the action keys that the
+ * example cases actually use (e.g. `aiWaitFor`, `value`-bearing steps). Extend
+ * it together with a test when a missing built-in key surfaces.
+ */
+export declare const BUILTIN_YAML_STEP_NAMES: ReadonlySet<string>;
+export declare const isBuiltinYamlStep: (stepName: string) => boolean;

package/dist/types/config.d.ts

@@ -0,0 +1,18 @@
+import type { FrameworkTestFile, LoadedMidsceneConfig, MidsceneFrameworkConfig } from './types';
+/**
+ * Type-only helper. It returns the config unchanged so the runtime stays
+ * explicit and the project keeps full control over its own configuration.
+ */
+export declare function defineMidsceneConfig<T extends MidsceneFrameworkConfig>(config: T): T;
+export declare function loadMidsceneConfig(configPath?: string): Promise<LoadedMidsceneConfig>;
+/**
+ * Validate the documented invariants of a `midscene.config.ts`:
+ * - `testDir` and `include` are required.
+ * - `target` and `setup` cannot be defined together (two runtime targets).
+ * - custom `yamlSteps` must not override built-in step names.
+ */
+export declare function validateMidsceneConfig(config: MidsceneFrameworkConfig, source?: string): void;
+export declare function collectFrameworkTestFiles(input: {
+    root: string;
+    config: MidsceneFrameworkConfig;
+}): Promise<FrameworkTestFile[]>;

package/dist/types/dotenv.d.ts

@@ -0,0 +1,28 @@
+import type { MidsceneFrameworkConfig } from './types';
+export interface LoadedDotenvFile {
+    path: string;
+    loaded: boolean;
+}
+/**
+ * Resolve the ordered list of `.env` files to consider for a suite run.
+ * Defaults to `[<cwd>/.env, <configDir>/.env]` so a project can keep its env
+ * either next to the config or at the working directory it was invoked from.
+ * Explicit `env.path` overrides the default lookup entirely.
+ */
+export declare function resolveDotenvCandidates(input: {
+    cwd: string;
+    configDir: string;
+    envConfig?: MidsceneFrameworkConfig['env'];
+}): string[];
+/**
+ * Load `.env` files for a suite run. Mirrors `@midscene/cli` semantics:
+ * existing `process.env` values are preserved unless `override` is set, and
+ * missing files are skipped silently so a project without a `.env` keeps
+ * working. Returns the considered files so the caller can log what was
+ * actually applied.
+ */
+export declare function loadFrameworkDotenv(input: {
+    cwd: string;
+    configDir: string;
+    envConfig?: MidsceneFrameworkConfig['env'];
+}): LoadedDotenvFile[];

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export { collectFrameworkTestFiles, defineMidsceneConfig, loadMidsceneConfig, validateMidsceneConfig, } from './config';
+export { BUILTIN_YAML_STEP_NAMES, isBuiltinYamlStep } from './builtin-steps';
+export { type LoadedDotenvFile, loadFrameworkDotenv, resolveDotenvCandidates, } from './dotenv';
+export { type FrameworkRstestProject, type FrameworkRstestRunner, type RunMidsceneSuiteOptions, runMidsceneSuite, } from './runner';
+export type { CustomYamlStepContext, CustomYamlStepHandler, FrameworkAgent, FrameworkCaseResult, FrameworkSetupResult, FrameworkSuiteSummary, FrameworkTargetConfig, FrameworkTargetType, FrameworkTestFile, LoadedMidsceneConfig, MidsceneFrameworkConfig, NormalizedYamlCase, SetupContext, } from './types';

package/dist/types/runner-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/runner.d.ts

@@ -0,0 +1,33 @@
+import type { FrameworkSuiteSummary } from './types';
+export interface FrameworkRstestProject {
+    root: string;
+    include: string[];
+    virtualModules: Record<string, string>;
+    maxConcurrency?: number;
+    testTimeout?: number;
+    bail?: number;
+    retry?: number;
+}
+export type FrameworkRstestRunner = (project: FrameworkRstestProject) => Promise<{
+    ok: boolean;
+}>;
+export interface RunMidsceneSuiteOptions {
+    /** Path to `midscene.config.ts`. Defaults to the one in `cwd`. */
+    configPath?: string;
+    /** Directory for generated wiring and per-case result files. */
+    outputDir?: string;
+    /** Override the Rstest runner. Mainly for tests. */
+    rstestRunner?: FrameworkRstestRunner;
+    stdio?: 'inherit' | 'pipe';
+}
+/**
+ * Load `midscene.config.ts`, discover cases, run them through Rstest, and write
+ * the suite summary. Intended to be the entire body of a project's
+ * `run-suite.ts`:
+ *
+ * ```ts
+ * import { runMidsceneSuite } from '@midscene/testing-framework';
+ * await runMidsceneSuite();
+ * ```
+ */
+export declare function runMidsceneSuite(options?: RunMidsceneSuiteOptions): Promise<FrameworkSuiteSummary>;

package/dist/types/runtime/index.d.ts

@@ -0,0 +1,24 @@
+import type { MidsceneFrameworkConfig } from '../types';
+export { createYamlFrameworkSuiteSource } from './source';
+export { normalizeYamlCase, runBuiltinYamlCase, runYamlFlowWithCustomSteps, } from './yaml';
+export { createDefaultSetup, setupFrameworkAgent } from './setup';
+export interface SuiteRuntimeOptions {
+    config: MidsceneFrameworkConfig;
+    projectDir: string;
+}
+/**
+ * Suite-level runtime shared by every generated case in a single Rstest module.
+ * The agent and `state` are created once (`beforeAll`) and torn down once
+ * (`afterAll`), so seeded data and cross-step state stay shared across cases.
+ */
+export declare class FrameworkSuiteRuntime {
+    private readonly config;
+    private readonly projectDir;
+    private readonly state;
+    private setupResult?;
+    constructor(options: SuiteRuntimeOptions);
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+    runCase(filePath: string, resultFile?: string): Promise<void>;
+}
+export declare function createSuiteRuntime(options: SuiteRuntimeOptions): FrameworkSuiteRuntime;

package/dist/types/runtime/setup.d.ts

@@ -0,0 +1,14 @@
+import type { FrameworkSetupResult, MidsceneFrameworkConfig, SetupContext } from '../types';
+interface DefaultSetupContext extends SetupContext {
+}
+/**
+ * Create an agent from the default `target` config. Only the `web` and
+ * `android` targets documented for the first version are supported.
+ */
+export declare function createDefaultSetup(config: MidsceneFrameworkConfig, context: DefaultSetupContext): Promise<FrameworkSetupResult>;
+/**
+ * Resolve the suite agent. A custom `setup` takes precedence; otherwise the
+ * default target setup is used.
+ */
+export declare function setupFrameworkAgent(config: MidsceneFrameworkConfig, context: DefaultSetupContext): Promise<FrameworkSetupResult>;
+export {};

package/dist/types/runtime/source.d.ts

@@ -0,0 +1,21 @@
+export interface FrameworkSuiteSourceCase {
+    filePath: string;
+    testName: string;
+    resultFile: string;
+}
+export interface CreateYamlFrameworkSuiteSourceOptions {
+    configPath: string;
+    projectDir: string;
+    cases: FrameworkSuiteSourceCase[];
+    /** Import specifier for `@midscene/testing-framework/runtime`. */
+    runtimeImport?: string;
+    /** Import specifier for the Rstest test API. */
+    rstestImport?: string;
+}
+/**
+ * Generate the source of a single Rstest module that owns the whole YAML suite:
+ * it sets the shared agent up once, registers one `test()` per YAML case, and
+ * tears the agent down once. Each YAML case therefore maps to one Rstest test,
+ * while suite-level setup/teardown and shared `state` are preserved.
+ */
+export declare function createYamlFrameworkSuiteSource(options: CreateYamlFrameworkSuiteSourceOptions): string;

package/dist/types/runtime/yaml.d.ts

@@ -0,0 +1,30 @@
+import type { MidsceneYamlFlowItem } from '@midscene/core';
+import type { CustomYamlStepHandler, FrameworkAgent, NormalizedYamlCase } from '../types';
+/**
+ * Convert a framework YAML case (top-level `flow`) into a normalized shape. The
+ * first version intentionally requires the documented top-level `flow` form and
+ * rejects full `tasks` documents.
+ */
+export declare function normalizeYamlCase(content: string, filePath: string): NormalizedYamlCase;
+/**
+ * Run a flow step by step so built-in steps and custom `yamlSteps` interleave in
+ * the authored order. Built-in steps are forwarded to `agent.runYaml`; custom
+ * steps invoke their handler with the YAML value and the current context.
+ */
+export declare function runYamlFlowWithCustomSteps(options: {
+    agent: FrameworkAgent;
+    filePath: string;
+    caseName: string;
+    flow: MidsceneYamlFlowItem[];
+    yamlSteps?: Record<string, CustomYamlStepHandler>;
+    state: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * Run a whole built-in case in a single `agent.runYaml` invocation. Used when no
+ * custom `yamlSteps` are registered, so the existing YAML runner handles the
+ * complete flow at once.
+ */
+export declare function runBuiltinYamlCase(options: {
+    agent: FrameworkAgent;
+    normalizedCase: NormalizedYamlCase;
+}): Promise<void>;