@midscene/test 1.15.4 → 1.15.5-beta-20261019120409.0

package/dist/es/cli/index.mjs

@@ -1,7 +1,7 @@
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve as external_node_path_resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { require as api_require } from "tsx/cjs/api";
-import { NodeRegistry, WorkflowError, WorkflowExecutionFailure, WorkflowParseError, WorkflowPublicationError, asExecutionError, buildTestRunReportDump, buildTestRunReportPlan, classifyWorkflowDocumentFormat, collectTestRunReportSources, createProjectRuntime, decideRetry, isFatalDeviceError, isReportSecretKey, isResourceRecoveryError, normalizeSteps, observeResourceOperations, runConcurrentJobs, runDocumentAttempts, runWorkflowDocument, sanitizeReportError, sanitizeReportText } from "@midscene/core/internal/test-runner";
+import { NodeRegistry, WorkflowError, WorkflowExecutionFailure, WorkflowParseError, WorkflowPublicationError, asExecutionError, buildTestRunReportDump, buildTestRunReportPlan, classifyWorkflowDocumentFormat, collectTestRunReportSources, createProjectRuntime, decideRetry, getPendingScopeOperations, getResourceCleanupCompletion, isFatalDeviceError, isReportSecretKey, isResourceRecoveryError, normalizeSteps, observeResourceOperations, runConcurrentJobs, runDocumentAttempts, runWorkflowDocument, sanitizeReportError, sanitizeReportText, trackResourceOperation, waitForScopeOperations } from "@midscene/core/internal/test-runner";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { globSync } from "tinyglobby";
 import { createHash, randomUUID } from "node:crypto";
@@ -14,6 +14,7 @@ const registry_NodeRegistry = NodeRegistry;
 const projectIdFromIndex = (index)=>`project-${index}`;
 const defineTestProject = (definition)=>definition;
 const defineProjectSetup = (definition)=>definition;
+const defineFileSetup = (definition)=>definition;
 const getDefaultExport = (loaded, absolutePath)=>{
     if ('object' == typeof loaded && null !== loaded && 'default' in loaded) {
         const defaultExport = loaded.default;
@@ -130,9 +131,14 @@ const validateNonNegativeInteger = (value, fallback, label)=>{
     if (!Number.isInteger(value) || value < 0) throw new TypeError(`Midscene config ${label} must be a non-negative integer.`);
     return value;
 };
-const validateExecutionProjects = (value, defaultSetup, globalNodes)=>{
+const validateFileConcurrency = (maxConcurrentFiles, fileSetup, label)=>{
+    if (void 0 !== maxConcurrentFiles && maxConcurrentFiles > 1 && !fileSetup) throw new TypeError(`Midscene config ${label}.fileSetup is required when the effective maxConcurrentFiles is greater than 1.`);
+};
+const validateExecutionProjects = (value, defaultSetup, defaultFileSetup, globalNodes, test)=>{
     if (void 0 === value) {
         const setup = validateSetup(defaultSetup, 'setup');
+        const fileSetup = validateSetup(defaultFileSetup, 'fileSetup');
+        validateFileConcurrency(test.maxConcurrentFiles, fileSetup, 'default');
         return {
             hasExplicitProjects: false,
             projects: Object.freeze([
@@ -142,6 +148,12 @@ const validateExecutionProjects = (value, defaultSetup, globalNodes)=>{
                     ...setup ? {
                         setup
                     } : {},
+                    ...fileSetup ? {
+                        fileSetup
+                    } : {},
+                    ...void 0 === test.maxConcurrentFiles ? {} : {
+                        maxConcurrentFiles: test.maxConcurrentFiles
+                    },
                     tags: Object.freeze({
                         include: [],
                         exclude: []
@@ -154,6 +166,7 @@ const validateExecutionProjects = (value, defaultSetup, globalNodes)=>{
         };
     }
     if (void 0 !== defaultSetup) throw new TypeError('Midscene config setup cannot be used together with projects. Move setup to projects[].setup.');
+    if (void 0 !== defaultFileSetup) throw new TypeError('Midscene config fileSetup cannot be used together with projects. Move fileSetup to projects[].fileSetup.');
     if (!Array.isArray(value) || 0 === value.length) throw new TypeError('Midscene config projects must be a non-empty array when declared.');
     const names = new Set();
     const projects = value.map((candidate, index)=>{
@@ -162,6 +175,8 @@ const validateExecutionProjects = (value, defaultSetup, globalNodes)=>{
         rejectUnknownKeys(candidate, [
             'name',
             'setup',
+            'fileSetup',
+            'maxConcurrentFiles',
             'nodes',
             'files',
             'tags',
@@ -178,10 +193,20 @@ const validateExecutionProjects = (value, defaultSetup, globalNodes)=>{
             ...globalNodes.definitions().filter((node)=>!localNodes.has(node.name)),
             ...localNodes.definitions()
         ]);
+        const fileSetup = validateSetup(candidate.fileSetup, `${label}.fileSetup`);
+        if (void 0 === test.maxConcurrentFiles && (void 0 !== fileSetup || void 0 !== candidate.maxConcurrentFiles)) throw new TypeError(`Midscene config ${label}.fileSetup/maxConcurrentFiles requires test.maxConcurrentFiles.`);
+        const maxConcurrentFiles = void 0 === test.maxConcurrentFiles ? void 0 : Math.min(test.maxConcurrentFiles, validatePositiveInteger(candidate.maxConcurrentFiles, test.maxConcurrentFiles, `${label}.maxConcurrentFiles`));
+        validateFileConcurrency(maxConcurrentFiles, fileSetup, label);
         return Object.freeze({
             projectId: projectIdFromIndex(index),
             name: candidate.name,
             nodes,
+            ...fileSetup ? {
+                fileSetup
+            } : {},
+            ...void 0 === maxConcurrentFiles ? {} : {
+                maxConcurrentFiles
+            },
             ...files ? {
                 files
             } : {},
@@ -201,7 +226,15 @@ const validateExecutionProjects = (value, defaultSetup, globalNodes)=>{
 const validateTestOptions = (value)=>{
     if (void 0 !== value && !isRecord(value)) throw new TypeError('Midscene config test must be an object.');
     const candidate = value ?? {};
+    const fileMode = void 0 !== candidate.maxConcurrentFiles;
+    if (fileMode && void 0 !== candidate.maxConcurrency) throw new TypeError('Midscene config test.maxConcurrentFiles cannot be combined with test.maxConcurrency.');
+    if (!fileMode && (void 0 !== candidate.setupTimeout || void 0 !== candidate.teardownTimeout)) throw new TypeError('Midscene config test.setupTimeout/teardownTimeout requires test.maxConcurrentFiles.');
     return Object.freeze({
+        ...fileMode ? {
+            maxConcurrentFiles: validatePositiveInteger(candidate.maxConcurrentFiles, 1, 'test.maxConcurrentFiles'),
+            setupTimeout: validatePositiveInteger(candidate.setupTimeout, 120000, 'test.setupTimeout'),
+            teardownTimeout: validatePositiveInteger(candidate.teardownTimeout, 30000, 'test.teardownTimeout')
+        } : {},
         maxConcurrency: validatePositiveInteger(candidate.maxConcurrency, 1, 'test.maxConcurrency'),
         bail: validateNonNegativeInteger(candidate.bail, 0, 'test.bail'),
         testTimeout: validatePositiveInteger(candidate.testTimeout, 120000, 'test.testTimeout')
@@ -232,16 +265,19 @@ const validateTestProjectDefinition = (definition)=>{
     if ('testRunner' in definition) throw new TypeError('Midscene config testRunner is not supported. Rename it to test.');
     rejectUnknownKeys(definition, [
         'setup',
+        'fileSetup',
         'projects',
         'test',
         'output',
         'nodes'
     ], 'root');
     const nodes = new registry_NodeRegistry(definition.nodes);
-    const resolvedProjects = validateExecutionProjects(definition.projects, definition.setup, nodes);
+    const test = validateTestOptions(definition.test);
+    if (void 0 !== definition.fileSetup && void 0 === test.maxConcurrentFiles) throw new TypeError('Midscene config fileSetup requires test.maxConcurrentFiles.');
+    const resolvedProjects = validateExecutionProjects(definition.projects, definition.setup, definition.fileSetup, nodes, test);
     return {
         ...resolvedProjects,
-        test: validateTestOptions(definition.test),
+        test,
         output: validateOutput(definition.output),
         nodes,
         resolveNode: (name)=>nodes.get(name)
@@ -263,7 +299,7 @@ async function loadTestProject(configPath) {
     if (!configPath) return validateTestProjectDefinition({
         nodes: []
     });
-    const absolutePath = resolve(configPath);
+    const absolutePath = external_node_path_resolve(configPath);
     const extension = assertSupportedConfig(absolutePath);
     let loaded;
     try {
@@ -759,7 +795,7 @@ const DEFAULT_TEST_FILE_SELECTION = {
 };
 const project_preparation_toPosix = (value)=>value.split(sep).join('/');
 const discoverResolvedTestFiles = (projectRoot, selection)=>{
-    const root = resolve(projectRoot);
+    const root = external_node_path_resolve(projectRoot);
     const match = (patterns)=>globSync(patterns, {
             absolute: true,
             caseSensitiveMatch: false,
@@ -775,7 +811,7 @@ const discoverResolvedTestFiles = (projectRoot, selection)=>{
         }).filter((file)=>/\.ya?ml$/i.test(file));
     const files = match(selection.include);
     return [
-        ...new Set(files.map((file)=>resolve(file)))
+        ...new Set(files.map((file)=>external_node_path_resolve(file)))
     ].sort((a, b)=>{
         const relativeA = project_preparation_toPosix(relative(root, a));
         const relativeB = project_preparation_toPosix(relative(root, b));
@@ -788,7 +824,7 @@ const discoverTestFiles = (projectRoot, selection = DEFAULT_TEST_FILE_SELECTION)
     return discoverResolvedTestFiles(projectRoot, normalized);
 };
 const discoverTestConfig = (projectRoot)=>{
-    const root = resolve(projectRoot);
+    const root = external_node_path_resolve(projectRoot);
     const candidates = readdirSync(root).filter((name)=>name.startsWith(CONFIG_PREFIX)).sort();
     const supported = candidates.filter((name)=>CONFIG_NAMES.includes(name));
     const unsupported = candidates.filter((name)=>!CONFIG_NAMES.includes(name));
@@ -842,7 +878,7 @@ const selectProjects = (projects, names)=>{
 async function prepareProject(project, projectRoot, runDir, defaultTimeoutMs, options = {}) {
     const platform = options.platform?.trim();
     const fileSelection = project.files ?? DEFAULT_TEST_FILE_SELECTION;
-    const prerequisiteFile = options.prerequisiteFile ? resolve(options.prerequisiteFile) : void 0;
+    const prerequisiteFile = options.prerequisiteFile ? external_node_path_resolve(options.prerequisiteFile) : void 0;
     const mainFiles = options.files ?? discoverResolvedTestFiles(projectRoot, fileSelection);
     const files = [
         ...prerequisiteFile ? [
@@ -920,7 +956,24 @@ async function prepareProject(project, projectRoot, runDir, defaultTimeoutMs, op
             defaultTimeoutMs,
             reportEnabled: true,
             bindings: {
-                resolveNode: project.nodes.require.bind(project.nodes)
+                resolveNode: project.nodes.require.bind(project.nodes),
+                ...project.fileSetup ? {
+                    documentSetup: {
+                        name: project.fileSetup.name,
+                        setup ({ projectContext, document, signal, onTeardown }) {
+                            return project.fileSetup.setup({
+                                project,
+                                projectContext,
+                                file: document,
+                                env: Object.freeze({
+                                    ...process.env
+                                }),
+                                signal,
+                                onTeardown
+                            });
+                        }
+                    }
+                } : {}
             }
         });
     } catch (error) {
@@ -966,9 +1019,9 @@ const assertDirectory = (path, label)=>{
     if (!existsSync(path) || !statSync(path).isDirectory()) throw new Error(`${label} does not exist or is not a directory: ${path}`);
 };
 const resolveRunInput = (options)=>{
-    const cwd = resolve(options.cwd ?? process.cwd());
+    const cwd = external_node_path_resolve(options.cwd ?? process.cwd());
     assertDirectory(cwd, 'Test working directory');
-    const inputPath = options.projectRoot ? resolve(cwd, options.projectRoot) : void 0;
+    const inputPath = options.projectRoot ? external_node_path_resolve(cwd, options.projectRoot) : void 0;
     const singleFile = inputPath && existsSync(inputPath) && statSync(inputPath).isFile() ? inputPath : void 0;
     if (singleFile && !/\.ya?ml$/i.test(singleFile)) throw new Error(`Test input must be a YAML file or project directory: ${singleFile}`);
     const cliProjectRoot = singleFile ? dirname(singleFile) : inputPath;
@@ -987,14 +1040,14 @@ async function prepareTestRun(options) {
     const startedAt = new Date();
     const runId = createTestRunId(startedAt);
     const input = resolveRunInput(options);
-    const configPath = options.configPath ? resolve(input.configSearchRoot, options.configPath) : discoverTestConfig(input.configSearchRoot);
+    const configPath = options.configPath ? external_node_path_resolve(input.configSearchRoot, options.configPath) : discoverTestConfig(input.configSearchRoot);
     if (options.configPath && /\.ya?ml$/i.test(configPath)) throw new Error(`midscene-test --config only accepts a native TypeScript or JavaScript project config: ${configPath}. Run legacy batch YAML with \`midscene --config ${options.configPath}\`.`);
     if (options.configPath && !existsSync(configPath)) throw new Error(`Midscene config does not exist: ${configPath}`);
     const definition = await loadTestProject(configPath);
-    const resultDir = options.resultDir ? resolve(input.cwd, options.resultDir) : join(input.projectRoot, '.midscene', 'test-results');
+    const resultDir = options.resultDir ? external_node_path_resolve(input.cwd, options.resultDir) : join(input.projectRoot, '.midscene', 'test-results');
     const runDir = join(resultDir, runId);
     const summaryPath = join(runDir, 'summary.json');
-    const reportDir = resolve(input.projectRoot, definition.output.reportDir);
+    const reportDir = external_node_path_resolve(input.projectRoot, definition.output.reportDir);
     mkdirSync(resultDir, {
         recursive: true
     });
@@ -1123,11 +1176,40 @@ const documentHasFatalError = (result)=>[
         ...result.beforeAll,
         ...result.afterAll
     ].some((step)=>step.error && isFatalDeviceError(step.error)) || (result.teardownErrors ?? []).some(isFatalDeviceError) || !!result.executionErrors?.some(isResourceRecoveryError);
+const isSharedResourceFailure = (error)=>{
+    const seen = new Set();
+    const pending = [
+        error
+    ];
+    while(pending.length && seen.size < 50){
+        const item = pending.pop();
+        if ('object' != typeof item || null === item || seen.has(item)) continue;
+        seen.add(item);
+        const failure = item;
+        if ('PROJECT_RESOURCE_ERROR' === failure.code) return true;
+        if (failure.cause) pending.push(failure.cause);
+        if (Array.isArray(failure.errors)) pending.push(...failure.errors.slice(0, 50));
+    }
+    return false;
+};
 async function executeDocumentInvocation(options) {
     const { invocation, project, sinks } = options;
+    const isProjectResourceFailure = options.isProjectResourceFailure ?? (()=>false);
     const { document } = invocation;
     const documentRetry = 'document' === invocation.retry.scope;
     const attempts = [];
+    const fileSetup = invocation.bindings.documentSetup;
+    const documentSetup = options.isProjectResourceFailure && fileSetup ? {
+        ...fileSetup,
+        async setup (ctx) {
+            try {
+                return await fileSetup.setup(ctx);
+            } catch (error) {
+                if (isProjectResourceFailure(error)) options.markProjectFatal();
+                throw error;
+            }
+        }
+    } : fileSetup;
     await runDocumentAttempts({
         retry: documentRetry ? invocation.retry.count : 0,
         signal: options.signal,
@@ -1138,6 +1220,9 @@ async function executeDocumentInvocation(options) {
             plan: invocation.plan,
             documentAttemptIndex: documentRetry ? documentAttemptIndex : void 0,
             ...invocation.bindings,
+            documentSetup,
+            setupTimeoutMs: options.setupTimeoutMs,
+            teardownTimeoutMs: options.teardownTimeoutMs,
             project,
             projectContext: options.projectContext,
             retry: documentRetry ? 0 : invocation.retry.count,
@@ -1149,7 +1234,7 @@ async function executeDocumentInvocation(options) {
                     ...run.beforeEach,
                     ...run.steps,
                     ...run.afterEach
-                ].some((step)=>step.error && isFatalDeviceError(step.error)) || (run.teardownErrors ?? []).some(isFatalDeviceError),
+                ].some((step)=>step.error && (isFatalDeviceError(step.error) || isProjectResourceFailure(step.error))) || (run.teardownErrors ?? []).some((error)=>isFatalDeviceError(error) || isProjectResourceFailure(error)),
             onCaseStart: (collectedCase)=>{
                 options.onProgress(`    [case ${collectedCase.caseIndex + 1}/${document.cases.length}] ${collectedCase.definition.name}`);
             },
@@ -1158,6 +1243,7 @@ async function executeDocumentInvocation(options) {
                 options.onProgress(`${indent}→ ${formatStep(info)}`);
             },
             onStepResult: async (info, result)=>{
+                if (isProjectResourceFailure(result.error)) options.markProjectFatal();
                 await invocation.bindings.onStepResult?.(info, result);
                 options.onProgress(formatStepResult(info, result));
             },
@@ -1166,7 +1252,12 @@ async function executeDocumentInvocation(options) {
                 options.onProgress(`    ${'success' === attempt.status ? '✓' : '✗'} attempt ${attempt.attemptIndex + 1}/${documentRetry ? 1 : invocation.retry.count + 1}: ${attempt.name} (${attempt.durationMs} ms)`);
             },
             onCaseOutcome: (outcome)=>{
-                if (caseHasFatalError(outcome)) options.markProjectFatal();
+                if (outcome.attempts?.some((attempt)=>[
+                        ...attempt.beforeEach,
+                        ...attempt.steps,
+                        ...attempt.afterEach
+                    ].some((step)=>isProjectResourceFailure(step.error)) || attempt.teardownErrors?.some(isProjectResourceFailure))) options.markProjectFatal();
+                if (!options.isolatedContext && caseHasFatalError(outcome)) options.markProjectFatal();
                 if (!documentRetry && 'failed' === outcome.status) options.addFailedCases(1);
             },
             onDocumentResult: options.onDocumentResult
@@ -1175,7 +1266,7 @@ async function executeDocumentInvocation(options) {
                 const partial = error.result;
                 const resourceOnly = error.errors.length > 0 && error.errors.every((failure)=>isResourceRecoveryError(failure) || partial.document.hostErrors?.some((host)=>'cleanup' === host.phase && (host.error === failure || host.error instanceof Error && host.error.cause === failure)));
                 if (resourceOnly) {
-                    if (error.errors.some(isResourceRecoveryError)) options.markProjectFatal();
+                    if (!options.isolatedContext && error.errors.some(isResourceRecoveryError)) options.markProjectFatal();
                     return partial;
                 }
                 if (documentRetry) partial.document.retryDecision = decideRetry({
@@ -1204,7 +1295,17 @@ async function executeDocumentInvocation(options) {
             }
             throw error;
         });
-        if (documentHasFatalError(execution.document)) options.markProjectFatal();
+        if (!options.isolatedContext && documentHasFatalError(execution.document)) options.markProjectFatal();
+        if ([
+            ...execution.document.beforeAll,
+            ...execution.document.afterAll,
+            ...(execution.document.hostErrors ?? []).map(({ error })=>({
+                    error
+                })),
+            ...(execution.document.teardownErrors ?? []).map((error)=>({
+                    error
+                }))
+        ].some(({ error })=>isProjectResourceFailure(error))) options.markProjectFatal();
         const owners = [
             execution.document,
             ...execution.cases.flatMap((outcome)=>outcome.attempts ?? [])
@@ -1212,7 +1313,10 @@ async function executeDocumentInvocation(options) {
         const cleanupPending = owners.some((owner)=>owner.cleanup?.status === 'pending');
         const operationPending = owners.some((owner)=>!!owner.pendingOperations?.length);
         const cleanupFailed = owners.some((owner)=>owner.cleanup?.status === 'failed' || !!owner.teardownErrors?.length || 'hostErrors' in owner && owner.hostErrors?.some(({ phase })=>'cleanup' === phase));
-        if (cleanupPending || cleanupFailed || operationPending) options.markProjectFatal();
+        if (cleanupPending || operationPending) {
+            options.markProjectFatal();
+            options.onUnresolvedResources?.();
+        } else if (cleanupFailed && !options.isolatedContext) options.markProjectFatal();
         const failed = 'failed' === execution.document.status || execution.cases.some((item)=>'success' !== item.status);
         const decision = decideRetry({
             scope: 'document',
@@ -1265,6 +1369,213 @@ async function executeDocumentInvocation(options) {
     if (documentRetry && failedCases) options.addFailedCases(failedCases);
     else if ('failed' === final.document.status && 0 === failedCases) options.addFailedCases(Math.max(1, failedCases));
 }
+async function runPreparedFiles(options) {
+    const states = options.projects.map((prepared)=>({
+            prepared,
+            cases: [],
+            documents: [],
+            cursor: 0,
+            active: 0,
+            initializing: false,
+            finished: false,
+            fatal: false,
+            setupFailed: false
+        }));
+    let nextProject = 0;
+    let resourcesUnresolved = false;
+    let occupied = 0;
+    const cleanupQueue = [];
+    const release = ()=>{
+        occupied--;
+        while(occupied < options.maxConcurrentFiles && cleanupQueue.length){
+            occupied++;
+            cleanupQueue.shift()();
+        }
+        wake?.();
+    };
+    let wake;
+    const running = new Set();
+    const stopped = (state)=>options.signal.aborted || options.shouldBail() || state.fatal;
+    const invalid = (state)=>options.preflightFailed || state.prepared.collectionErrors.length > 0;
+    const unresolved = ()=>{
+        if (resourcesUnresolved) return;
+        resourcesUnresolved = true;
+        options.onInfrastructureError(new WorkflowError('Resources are still running or cleanup is pending. No new test files will start.', {
+            code: 'UNRESOLVED_FILE_RESOURCES'
+        }));
+    };
+    const finishProject = async (state)=>{
+        if (!state.runtime || state.finished) return;
+        state.finished = true;
+        const failed = state.fatal || options.signal.aborted || state.cases.some((item)=>'success' !== item.status) || state.documents.some((item)=>'success' !== item.status);
+        state.lifecycle = await state.runtime.finish(failed ? 'failed' : 'success');
+        if (state.lifecycle.cleanup?.status === 'pending' || state.lifecycle.pendingOperations?.length) unresolved();
+    };
+    const admit = ()=>{
+        for(let offset = 0; offset < states.length; offset++){
+            const index = (nextProject + offset) % states.length;
+            const state = states[index];
+            if (invalid(state) || state.finished || state.initializing) continue;
+            const cleanupOnly = !!state.runtime && 0 === state.active && (stopped(state) || state.cursor === state.prepared.invocations.length);
+            if (!cleanupOnly && (stopped(state) || state.cursor >= state.prepared.invocations.length || state.active >= (state.prepared.project.maxConcurrentFiles ?? options.maxConcurrentFiles))) continue;
+            nextProject = (index + 1) % states.length;
+            occupied++;
+            state.active++;
+            if (!state.runtime && !cleanupOnly) state.initializing = true;
+            const invocationIndex = cleanupOnly ? -1 : state.cursor++;
+            return {
+                state,
+                index,
+                invocationIndex
+            };
+        }
+    };
+    const run = async ({ state, index, invocationIndex })=>{
+        const { prepared } = state;
+        const { project } = prepared;
+        let fileResourcesPending = false;
+        try {
+            if (invocationIndex < 0) return void await finishProject(state);
+            if (!state.runtime) {
+                state.runtime = createProjectRuntime({
+                    project,
+                    setup: project.setup,
+                    signal: options.signal,
+                    setupTimeoutMs: options.setupTimeoutMs,
+                    teardownTimeoutMs: options.teardownTimeoutMs
+                });
+                setMaxListeners(Math.max(10, Math.min(prepared.invocations.length, project.maxConcurrentFiles ?? options.maxConcurrentFiles) + 1), state.runtime.signal);
+                options.announceProject(prepared, index);
+                await state.runtime.start();
+                state.initializing = false;
+                if (!state.runtime.canRun) {
+                    state.fatal = true;
+                    state.setupFailed = true;
+                }
+                wake?.();
+            }
+            if (stopped(state)) return;
+            const invocation = prepared.invocations[invocationIndex];
+            options.onProgress(prepared, `  [document ${invocationIndex + 1}/${prepared.invocations.length}] ${invocation.document.sourcePath}`);
+            await executeDocumentInvocation({
+                invocation,
+                project,
+                projectContext: state.runtime.context,
+                runDir: options.runDir,
+                signal: state.runtime.signal,
+                rootSignal: options.signal,
+                shouldBail: options.shouldBail,
+                isProjectFatal: ()=>state.fatal,
+                markProjectFatal: ()=>{
+                    if (state.fatal) return;
+                    state.fatal = true;
+                    state.runtime?.abort(new WorkflowError(`Project "${project.name}" shared execution environment is unavailable.`, {
+                        code: 'PROJECT_RESOURCE_ERROR'
+                    }));
+                },
+                addFailedCases: options.addFailedCases,
+                onProgress: (message)=>options.onProgress(prepared, message),
+                sinks: state,
+                isolatedContext: void 0 !== project.fileSetup,
+                isProjectResourceFailure: isSharedResourceFailure,
+                setupTimeoutMs: options.setupTimeoutMs,
+                teardownTimeoutMs: options.teardownTimeoutMs,
+                onUnresolvedResources: ()=>{
+                    fileResourcesPending = true;
+                    unresolved();
+                }
+            });
+        } catch (error) {
+            state.fatal = true;
+            fileResourcesPending = !!state.runtime && getPendingScopeOperations(state.runtime.signal).length > 0;
+            options.onInfrastructureError(error);
+        } finally{
+            state.initializing = false;
+            try {
+                if (1 === state.active && (stopped(state) || state.cursor === prepared.invocations.length)) await finishProject(state);
+            } catch (error) {
+                options.onInfrastructureError(error);
+            }
+            state.active--;
+            if (state.runtime && (fileResourcesPending || state.lifecycle?.cleanup?.status === 'pending')) waitForScopeOperations(state.runtime.signal).then(release, (error)=>{
+                options.onInfrastructureError(error);
+                release();
+            });
+            else release();
+            wake?.();
+        }
+    };
+    while(true){
+        const changed = new Promise((resolve)=>{
+            wake = resolve;
+        });
+        while(occupied < options.maxConcurrentFiles){
+            const job = admit();
+            if (!job) break;
+            const task = run(job);
+            running.add(task);
+            const settled = ()=>{
+                running.delete(task);
+                wake?.();
+            };
+            task.then(settled, (error)=>{
+                options.onInfrastructureError(error);
+                settled();
+            });
+        }
+        if (!running.size) break;
+        await changed;
+    }
+    wake = void 0;
+    await Promise.all(states.map(async (state)=>{
+        if (!state.runtime || state.finished) return;
+        const admission = new Promise((resolve)=>{
+            cleanupQueue.push(resolve);
+        });
+        trackResourceOperation({}, admission, state.runtime.signal);
+        while(occupied < options.maxConcurrentFiles && cleanupQueue.length){
+            occupied++;
+            cleanupQueue.shift()();
+        }
+        try {
+            await finishProject(state);
+        } catch (error) {
+            options.onInfrastructureError(error);
+        } finally{
+            Promise.all([
+                admission,
+                getResourceCleanupCompletion(state.runtime.signal)
+            ]).then(release, (error)=>{
+                options.onInfrastructureError(error);
+                release();
+            });
+        }
+    }));
+    for (const state of states){
+        const { prepared } = state;
+        if (!state.runtime) options.announceProject(prepared, states.indexOf(state));
+        const completed = new Set(state.cases.map((item)=>item.caseId));
+        const reason = invalid(state) ? 'project-preflight-failed' : state.setupFailed ? 'project-setup-failed' : options.signal.aborted ? 'interrupted' : state.fatal ? 'fatal-error' : 'bail';
+        for (const document of prepared.documents)for (const item of document.cases)if (!completed.has(item.caseId)) state.cases.push({
+            documentId: document.documentId,
+            caseId: item.caseId,
+            projectName: prepared.project.name,
+            name: item.definition.name,
+            sourcePath: item.sourcePath,
+            caseIndex: item.caseIndex,
+            status: 'not-run',
+            notRunReason: reason
+        });
+        const order = new Map(prepared.documents.map((document, i)=>[
+                document.documentId,
+                i
+            ]));
+        const position = (id)=>order.get(id) ?? Number.MAX_SAFE_INTEGER;
+        state.cases.sort((a, b)=>position(a.documentId) - position(b.documentId) || a.caseIndex - b.caseIndex);
+        state.documents.sort((a, b)=>position(a.documentId) - position(b.documentId));
+    }
+    return states;
+}
 function createOperationJournal(runDir) {
     const path = join(runDir, 'operations.jsonl');
     writeFileSync(path, '', {
@@ -1334,7 +1645,7 @@ async function runPreparedTestProject(plan) {
     const totalCases = preparedProjects.reduce((total, prepared)=>total + prepared.selectedCaseCount, 0);
     const totalErrors = preparedProjects.reduce((total, prepared)=>total + prepared.collectionErrors.length, 0);
     progress(`midscene-test: preflighted ${preparedProjects.length} projects, ${totalDocuments} documents, ${totalCases} cases, ${totalErrors} collection errors`);
-    const effectiveConcurrency = Math.min(definition.test.maxConcurrency, preparedProjects.length);
+    const effectiveConcurrency = Math.min(definition.test.maxConcurrentFiles ?? definition.test.maxConcurrency, void 0 === definition.test.maxConcurrentFiles ? preparedProjects.length : Math.max(1, totalDocuments));
     await writeTestRunPlan(runDir, preparedProjects);
     const journal = createOperationJournal(runDir);
     const rootController = new AbortController();
@@ -1348,6 +1659,18 @@ async function runPreparedTestProject(plan) {
     process.on('SIGTERM', sigterm);
     let failedCaseCount = 0;
     const bailReached = ()=>definition.test.bail > 0 && failedCaseCount >= definition.test.bail;
+    let shutdownDeadline;
+    const beginShutdown = ()=>{
+        if (void 0 !== definition.test.maxConcurrentFiles) shutdownDeadline ??= Date.now() + definition.test.teardownTimeout;
+    };
+    rootController.signal.addEventListener('abort', beginShutdown, {
+        once: true
+    });
+    const addFailedCases = (count)=>{
+        failedCaseCount += count;
+        if (bailReached()) beginShutdown();
+    };
+    const teardownTimeoutMs = ()=>Math.max(0, Math.min(definition.test.teardownTimeout, void 0 === shutdownDeadline ? 1 / 0 : shutdownDeadline - Date.now()));
     let hasInfrastructureError = false;
     const infrastructureErrors = [];
     const recordInfrastructureError = (error)=>{
@@ -1450,9 +1773,7 @@ async function runPreparedTestProject(plan) {
                             markProjectFatal: ()=>{
                                 projectFatal = true;
                             },
-                            addFailedCases: (count)=>{
-                                failedCaseCount += count;
-                            },
+                            addFailedCases,
                             onProgress: projectProgress,
                             sinks: {
                                 cases,
@@ -1505,7 +1826,25 @@ async function runPreparedTestProject(plan) {
     };
     const projectResults = new Array(preparedProjects.length);
     try {
-        await runConcurrentJobs(preparedProjects, {
+        if (void 0 !== definition.test.maxConcurrentFiles) {
+            const states = await runPreparedFiles({
+                projects: preparedProjects,
+                maxConcurrentFiles: definition.test.maxConcurrentFiles,
+                setupTimeoutMs: definition.test.setupTimeout,
+                teardownTimeoutMs,
+                signal: rootController.signal,
+                runDir,
+                preflightFailed: 'run' === plan.preflightScope && totalErrors > 0,
+                shouldBail: bailReached,
+                addFailedCases,
+                announceProject,
+                onProgress: (prepared, message)=>runInfrastructureCallback(()=>progress(effectiveConcurrency > 1 ? `[${prepared.project.name}]${message}` : message)),
+                onInfrastructureError: recordInfrastructureError
+            });
+            states.forEach((state, index)=>{
+                projectResults[index] = buildProjectResult(state.prepared, state.cases, state.documents, state.lifecycle);
+            });
+        } else await runConcurrentJobs(preparedProjects, {
             concurrency: effectiveConcurrency,
             shouldStop: ()=>hasInfrastructureError || rootController.signal.aborted || bailReached()
         }, async (prepared, index)=>{
@@ -1621,6 +1960,6 @@ async function runPreparedTestProject(plan) {
 async function runTestProject(options = {}) {
     return runPreparedTestProject(await prepareTestRun(options));
 }
-export { DEFAULT_TEST_FILE_SELECTION, createTestRunId, defineProjectSetup, defineTestProject, discoverTestConfig, discoverTestFiles, loadTestProject, runTestProject, validateTestFileSelection };
+export { DEFAULT_TEST_FILE_SELECTION, createTestRunId, defineFileSetup, defineProjectSetup, defineTestProject, discoverTestConfig, discoverTestFiles, loadTestProject, runTestProject, validateTestFileSelection };
 
 //# sourceMappingURL=index.mjs.map