playwright-test-explorer 0.0.10 → 0.0.13

package/README.md

@@ -36,12 +36,15 @@ pw-test-explorer tree
 
 # 保存结果到文件
 pw-test-explorer tree -o output.json
+
+# 根据 Git 变更增量更新已有树（缓存文件及其 state 文件需在构建间保留）
+pw-test-explorer tree --incremental -o output.json
 ```
 
 ### API 使用
 
 ```typescript
-import { listTestFile, listTestCase, treeStructure } from 'playwright-test-explorer';
+import { listTestFile, listTestCase, treeStructure, updateTreeStructure } from 'playwright-test-explorer';
 
 // 列出测试文件
 await listTestFile('/path/to/project', 'playwright.config.ts');
@@ -51,8 +54,21 @@ await listTestCase('/path/to/project', 'playwright.config.ts', ['tests/example.s
 
 // 生成测试树
 await treeStructure('/path/to/project', 'playwright.config.ts');
+
+// 根据缓存记录的 Git 提交之后的变更更新测试树；状态文件默认为 <output>.state.json。
+await updateTreeStructure('/path/to/project', 'playwright.config.ts', '/path/to/project/test-tree.json');
 ```
 
+`tree --incremental` 在没有有效缓存时全量构建测试树。后续运行根据缓存记录的 Git 提交之后的变更，重新收集发生变化的测试文件，并移除已删除或重命名文件的旧节点。CI 构建之间需要同时保留测试树输出文件及其配套的 `.state.json` 状态文件。配置或参与缓存校验的环境变量发生变化时，缓存失效并触发全量重建。
+
+增量比较只考虑已提交的 Git 变更，假设工作区内容与记录的提交一致。工作区可以是 Git 仓库的子目录。非测试文件发生变化时，会保守地触发全量重建。对同一组输出文件和状态文件的更新应串行执行。
+
+缓存默认跟踪 `CI`、`NODE_ENV`、`NODE_OPTIONS`、`TZ`，以及配置文件内容、工作区路径和 Node.js 版本。CI 任务 ID 等临时变量不会使缓存失效。如果配置或测试定义依赖其他环境变量，需要通过 `--cache-env DOC,AI` 声明变量名，或通过 API 的第五个参数传入 `{ environmentKeys: ['DOC', 'AI'] }`。这些项目自定义变量仅在显式声明后参与缓存校验。状态文件只保存计算后的哈希值，不保存环境变量的原始值。升级后，版本 1 的旧缓存会触发一次全量重建。
+
+`tree` 和 `list-tests` 输出的报告文件路径均相对于 Playwright 的 `rootDir`，即使各项目配置了不同的 `testDir`，也使用这一基准。
+
+全量构建通过 Playwright 的 `test --list` 和本库内置的 reporter 收集测试。测试文件在一个子进程中加载，仅将最终测试树传回主进程，省去 test server 模式下 loader 向 server 传输依赖缓存的开销。收集过程不会执行全局 setup、测试正文或用户配置的 reporter。增量收集继续使用 test server。
+
 ## 文档
 
 - [功能规格说明](./SPEC.md) - 完整的功能需求和 API 文档

package/dist/{api-Bc2ZCCQ0.mjs → api-CvJUOXye.mjs}

@@ -1,12 +1,13 @@
 import { createRequire } from "node:module";
 import path from "path";
-import { spawn } from "child_process";
+import { execFile, fork, spawn } from "child_process";
 import WebSocket from "ws";
+import { fileURLToPath } from "url";
 import fs from "fs/promises";
-
-//#region rolldown:runtime
+import { createHash } from "crypto";
+import { promisify } from "util";
+//#region \0rolldown/runtime.js
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
 //#endregion
 //#region src/upstream/teleReceiver.ts
 var TeleReporterReceiver = class {
@@ -406,7 +407,6 @@ function parseRegexPatterns(patterns) {
 		return new RegExp(p.r.source, p.r.flags);
 	});
 }
-
 //#endregion
 //#region src/upstream/events.ts
 let Disposable;
@@ -444,8 +444,8 @@ var EventEmitter = class {
 		});
 		if (!dispatch) return;
 		for (let index = 0; index < this._deliveryQueue.length; index++) {
-			const { listener, event: event$1 } = this._deliveryQueue[index];
-			listener.call(null, event$1);
+			const { listener, event } = this._deliveryQueue[index];
+			listener.call(null, event);
 		}
 		this._deliveryQueue = void 0;
 	}
@@ -454,7 +454,6 @@ var EventEmitter = class {
 		if (this._deliveryQueue) this._deliveryQueue = [];
 	}
 };
-
 //#endregion
 //#region src/upstream/testServerConnection.ts
 var WebSocketTestServerTransport = class {
@@ -635,7 +634,6 @@ var TestServerConnection = class {
 		} catch {}
 	}
 };
-
 //#endregion
 //#region src/utils/pathUtils.ts
 /**
@@ -650,14 +648,6 @@ function escapeRegex(text) {
 	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /**
-* Path resolution strategy for TeleReporterReceiver
-* For file paths (with extensions), return relative path (Playwright format)
-* For directory paths (testDir, outputDir, etc.), return absolute path
-*/
-function resolvePathForFiles(rootDir, relativePath) {
-	return /\.\w+$/.test(relativePath) ? relativePath : path.join(rootDir, relativePath);
-}
-/**
 * Standard path resolution - always returns absolute path
 */
 function resolveAbsolutePath(rootDir, relativePath) {
@@ -674,7 +664,6 @@ function findPlaywrightCli(workspaceFolder) {
 		throw new Error("Playwright installation not found. Please install @playwright/test");
 	}
 }
-
 //#endregion
 //#region src/utils/processUtils.ts
 /**
@@ -711,21 +700,9 @@ function createTestServerEnv(baseEnv, customEnv, cwd) {
 		FORCE_COLOR: "1"
 	}, cwd);
 }
-
 //#endregion
 //#region src/utils/reporterFactory.ts
 /**
-* Create TeleReporterReceiver for listing files
-* Uses special path resolution for preserving relative paths for files
-*/
-function createFileListReceiver(reporter) {
-	return new TeleReporterReceiver(reporter, {
-		mergeProjects: true,
-		mergeTestCases: true,
-		resolvePath: resolvePathForFiles
-	});
-}
-/**
 * Create TeleReporterReceiver for listing tests
 * Uses standard absolute path resolution
 */
@@ -742,7 +719,6 @@ function createTestListReceiver(reporter) {
 function processReport(receiver, report) {
 	for (const message of report) receiver.dispatch(message);
 }
-
 //#endregion
 //#region src/playwrightTestServer.ts
 /**
@@ -781,11 +757,16 @@ var PlaywrightTestServer = class {
 	}
 	async listFiles() {
 		const connection = await this._ensureConnection();
-		const result = { projects: [] };
-		const { report } = await connection.listFiles({});
+		const result = {
+			rootDir: this._config.workspaceFolder,
+			projects: []
+		};
+		const { report, status } = await connection.listFiles({});
 		const workspaceFolder = this._config.workspaceFolder;
-		processReport(createFileListReceiver({
-			onConfigure: (_config) => {},
+		processReport(createTestListReceiver({
+			onConfigure: (_config) => {
+				result.rootDir = _config.rootDir;
+			},
 			onBegin(rootSuite) {
 				for (const projectSuite of rootSuite.suites) {
 					const project = projectSuite.project();
@@ -797,24 +778,31 @@ var PlaywrightTestServer = class {
 						use: project.use || {},
 						files
 					});
-					for (const fileSuite of projectSuite.suites) files.push(fileSuite.location.file);
+					for (const fileSuite of projectSuite.suites) files.push(path.relative(result.rootDir, fileSuite.location.file).replace(/\\/g, "/"));
 				}
 			},
 			onError(error) {
 				result.error = error;
 			}
 		}), report);
+		if (result.error) throw new Error(result.error.message || "Playwright file collection failed");
+		if (status !== "passed") throw new Error(`Playwright file collection ${status}`);
 		return result;
 	}
 	/**
 	* Get raw test report without processing through TeleReporterReceiver
 	* This preserves the complete test.describe hierarchy
 	*/
-	async getRawTestReport(locations, token) {
+	async getRawTestReport(locations, token, projects) {
 		if (token?.isCancellationRequested) return [];
-		const connection = await this._ensureConnection();
-		const escapedLocations = locations.map(escapeRegex);
-		const { report } = await connection.listTests({ locations: escapedLocations });
+		const { report, status } = await (await this._ensureConnection()).listTests({
+			locations: locations?.map(escapeRegex),
+			projects
+		});
+		if (status !== "passed") {
+			const error = report.find((message) => message.method === "onError");
+			throw new Error(error?.params.error.message || `Playwright test collection ${status}`);
+		}
 		return report;
 	}
 	async listTests(locations, reporter, token) {
@@ -912,206 +900,382 @@ var PlaywrightTestServer = class {
 		this._disposeTestServer();
 	}
 };
-
+//#endregion
+//#region src/utils/tree.ts
+/** Consumes the report, reusing its suite/entry arrays instead of retaining two trees. */
+function consumeTestReport(report) {
+	const root = {
+		type: "suite",
+		title: "Root",
+		children: []
+	};
+	const filePath = (file) => file.replace(/\\/g, "/");
+	function convertEntries(entries) {
+		for (let i = 0; i < entries.length; i++) {
+			const entry = entries[i];
+			entries[i] = entry.testId ? {
+				type: "test",
+				title: entry.title,
+				testId: entry.testId,
+				location: {
+					...entry.location,
+					file: filePath(entry.location.file)
+				},
+				tags: entry.tags || [],
+				annotations: entry.annotations || [],
+				expectedStatus: "passed",
+				timeout: 0
+			} : {
+				type: "suite",
+				title: entry.title,
+				file: entry.location ? filePath(entry.location.file) : void 0,
+				children: convertEntries(entry.entries || [])
+			};
+		}
+		return entries;
+	}
+	const error = report.find((message) => message.method === "onError");
+	if (error) throw new Error(error.params.error.message || "Playwright test collection failed");
+	for (let i = 0; i < report.length; i++) {
+		const message = report[i];
+		report[i] = void 0;
+		if (message.method !== "onProject") continue;
+		const project = message.params.project;
+		root.children.push({
+			type: "suite",
+			title: project.name,
+			children: convertEntries(project.suites || [])
+		});
+	}
+	report.length = 0;
+	return root;
+}
+//#endregion
+//#region src/collectTree.ts
+/** CLI list mode loads tests in one process, without transferring the loader's dependency graph. */
+function collectFullTree(workspaceFolder, configFile, token) {
+	if (token?.isCancellationRequested) return Promise.reject(/* @__PURE__ */ new Error("Test collection cancelled"));
+	workspaceFolder = path.resolve(workspaceFolder);
+	const cli = findPlaywrightCli(workspaceFolder);
+	const reporter = fileURLToPath(new URL("./treeReporter.mjs", import.meta.url));
+	return new Promise((resolve, reject) => {
+		const child = fork(cli, [
+			"test",
+			"--list",
+			"--reporter",
+			reporter,
+			"--project",
+			"*",
+			"--repeat-each",
+			"1",
+			"--retries",
+			"0",
+			"--global-timeout",
+			"0",
+			"--pass-with-no-tests",
+			"-c",
+			path.resolve(workspaceFolder, configFile)
+		], {
+			cwd: workspaceFolder,
+			env: createTestServerEnv(process.env, {}, workspaceFolder),
+			execArgv: [],
+			serialization: "advanced",
+			stdio: [
+				"ignore",
+				"ignore",
+				"pipe",
+				"ipc"
+			]
+		});
+		let result;
+		let stderr = "";
+		child.stderr.on("data", (chunk) => {
+			stderr = (stderr + chunk).slice(-64 * 1024);
+		});
+		child.on("message", (message) => {
+			if (message && typeof message === "object" && "type" in message && message.type === "test-explorer:tree") result = message;
+		});
+		const cancellation = token?.onCancellationRequested(() => child.kill());
+		child.once("error", reject);
+		child.once("close", (code, signal) => {
+			cancellation?.dispose();
+			if (token?.isCancellationRequested) reject(/* @__PURE__ */ new Error("Test collection cancelled"));
+			else if (code !== 0 || !result?.tree || result.error) reject(new Error(result?.error || stderr.trim() || `Playwright test collection failed (${signal || code})`));
+			else resolve(result.tree);
+		});
+	});
+}
 //#endregion
 //#region src/api.ts
-async function listTestFile(workspaceFolder = process.cwd(), configFile = "playwright.config.ts", outputFile) {
-	const testServer = new PlaywrightTestServer({
+const execFileAsync = promisify(execFile);
+const GIT_MAX_BUFFER = 32 * 1024 * 1024;
+const COLLECTION_ENV_KEYS = [
+	"CI",
+	"NODE_ENV",
+	"NODE_OPTIONS",
+	"TZ"
+];
+async function runGit(workspaceFolder, args) {
+	const { stdout } = await execFileAsync("git", args, {
+		cwd: workspaceFolder,
+		encoding: "buffer",
+		maxBuffer: GIT_MAX_BUFFER
+	});
+	return stdout;
+}
+function sha256(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+async function incrementalInputHash(workspaceFolder, configFile, options) {
+	const configPath = path.resolve(workspaceFolder, configFile);
+	const environment = [...new Set([...COLLECTION_ENV_KEYS, ...options.environmentKeys ?? []])].sort().map((key) => [key, process.env[key]]);
+	return createHash("sha256").update(JSON.stringify([
 		workspaceFolder,
-		configFile: path.join(workspaceFolder, configFile)
+		configPath,
+		process.version,
+		environment
+	])).update("\0").update(await fs.readFile(configPath)).digest("hex");
+}
+function parseGitNameStatus(buffer) {
+	const fields = buffer.toString("utf8").split("\0");
+	const changes = [];
+	for (let i = 0; i < fields.length;) {
+		const status = fields[i++];
+		if (!status) continue;
+		if (status.startsWith("R") || status.startsWith("C")) changes.push({
+			status: status[0],
+			from: fields[i++],
+			to: fields[i++]
+		});
+		else changes.push({
+			status: status[0],
+			path: fields[i++]
+		});
+	}
+	return changes;
+}
+function normalizePath(file) {
+	return file.replace(/\\/g, "/");
+}
+function isWithin(directory, file) {
+	const relative = path.relative(directory, file);
+	return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/** Share untouched branches; only replace affected project/file arrays. */
+function mergeIncrementalTree(cachedTree, changedTree, updatedFilesByProject) {
+	const changedProjects = new Map((changedTree.children ?? []).map((project) => [project.title, project]));
+	const projects = [...cachedTree.children ?? []];
+	const knownProjects = new Set(projects.map((project) => project.title));
+	for (const project of changedTree.children ?? []) if (!knownProjects.has(project.title)) projects.push({
+		...project,
+		children: []
 	});
+	return {
+		...cachedTree,
+		children: projects.map((project) => {
+			const files = updatedFilesByProject.get(project.title);
+			if (!files?.size) return project;
+			const children = (project.children ?? []).filter((node) => !files.has(normalizePath(node.file || "")));
+			for (const node of changedProjects.get(project.title)?.children ?? []) if (files.has(normalizePath(node.file || ""))) children.push(node);
+			children.sort((a, b) => (a.file || "") < (b.file || "") ? -1 : (a.file || "") > (b.file || "") ? 1 : 0);
+			return {
+				...project,
+				children
+			};
+		}).filter((project) => project.children?.length)
+	};
+}
+async function writeFileAtomic(file, value) {
+	const temporary = `${file}.${process.pid}.tmp`;
 	try {
-		const output = { projects: (await testServer.listFiles()).projects.map((project) => ({
-			...project,
-			files: project.files.map((filePath) => filePath.replace(/\\/g, "/"))
-		})) };
-		const jsonString = JSON.stringify(output, null, 2);
-		if (outputFile) {
-			await fs.writeFile(outputFile, jsonString, "utf-8");
-			console.log(`Results saved to: ${outputFile}`);
-		} else console.log(jsonString);
-		testServer.close();
-	} catch (error) {
-		console.error("Error:", error);
-		testServer.close();
+		await fs.writeFile(temporary, value);
+		await fs.rename(temporary, file);
+	} finally {
+		await fs.unlink(temporary).catch(() => {});
 	}
 }
-async function listTestCase(workspaceFolder = process.cwd(), configFile = "playwright.config.ts", relativePaths, outputFile) {
-	const testServer = new PlaywrightTestServer({
-		workspaceFolder,
-		configFile: path.join(workspaceFolder, configFile)
+async function readIncrementalState(stateFile) {
+	try {
+		return JSON.parse(await fs.readFile(stateFile, "utf8"));
+	} catch {
+		return;
+	}
+}
+async function isGitAncestor(workspaceFolder, base, head) {
+	if (base === head) return true;
+	try {
+		await runGit(workspaceFolder, [
+			"merge-base",
+			"--is-ancestor",
+			base,
+			head
+		]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function isTestFile(file) {
+	return /\.(?:spec|test)\.(?:[cm]?[jt]sx?)$/i.test(file);
+}
+function createServer(workspaceFolder, configFile) {
+	return new PlaywrightTestServer({
+		workspaceFolder: path.resolve(workspaceFolder),
+		configFile: path.resolve(workspaceFolder, configFile)
 	});
+}
+/** Update committed test changes; non-test changes conservatively rebuild the tree. */
+async function updateTreeStructure(workspaceFolder, configFile, outputFile, stateFile = `${outputFile}.state.json`, options = {}) {
+	workspaceFolder = path.resolve(workspaceFolder);
+	const head = (await runGit(workspaceFolder, ["rev-parse", "HEAD"])).toString("utf8").trim();
+	const inputHash = await incrementalInputHash(workspaceFolder, configFile, options);
+	const state = await readIncrementalState(stateFile);
+	let treeContent = await fs.readFile(outputFile).catch(() => void 0);
+	const validCache = state?.version === 2 && state.inputHash === inputHash && treeContent !== void 0 && state.treeHash === sha256(treeContent) && await isGitAncestor(workspaceFolder, state.commit, head);
+	const save = async (tree) => {
+		const content = `${JSON.stringify(tree, null, 2)}\n`;
+		const nextState = {
+			version: 2,
+			commit: head,
+			inputHash,
+			treeHash: sha256(content)
+		};
+		await writeFileAtomic(outputFile, content);
+		await writeFileAtomic(stateFile, `${JSON.stringify(nextState, null, 2)}\n`);
+	};
+	if (validCache && state.commit === head) return {
+		mode: "unchanged",
+		updatedFiles: 0,
+		deletedFiles: 0
+	};
+	const gitRoot = (await runGit(workspaceFolder, ["rev-parse", "--show-toplevel"])).toString("utf8").trim();
+	const changes = validCache ? parseGitNameStatus(await runGit(gitRoot, [
+		"diff",
+		"--no-relative",
+		"--name-status",
+		"-z",
+		"--find-renames",
+		`${state.commit}...${head}`
+	])) : [];
+	if (validCache && !changes.length) {
+		await writeFileAtomic(stateFile, `${JSON.stringify({
+			...state,
+			commit: head
+		}, null, 2)}\n`);
+		return {
+			mode: "unchanged",
+			updatedFiles: 0,
+			deletedFiles: 0
+		};
+	}
+	const needsFullBuild = !validCache || changes.some((change) => ("from" in change ? [change.from, change.to] : [change.path]).some((file) => !isTestFile(file)));
+	let cachedTree;
+	if (!needsFullBuild) try {
+		cachedTree = JSON.parse(treeContent.toString("utf8"));
+		if (cachedTree?.type !== "suite" || !Array.isArray(cachedTree.children)) cachedTree = void 0;
+	} catch {}
+	treeContent = void 0;
+	if (!cachedTree) {
+		await save(await collectFullTree(workspaceFolder, configFile));
+		return {
+			mode: "full",
+			updatedFiles: 0,
+			deletedFiles: 0
+		};
+	}
+	const server = createServer(workspaceFolder, configFile);
 	try {
-		const token = new CancellationToken();
-		const expandedPaths = [];
-		for (const relativePath of relativePaths) {
-			const normalizedInputPath = relativePath.replace(/\\/g, "/").replace(/\/$/, "");
-			const absolutePath = path.join(workspaceFolder, relativePath);
-			try {
-				if ((await fs.stat(absolutePath)).isDirectory()) {
-					const files = await testServer.listFiles();
-					for (const project of files.projects) {
-						const testDirRelative = project.testDir || "";
-						for (const file of project.files) {
-							const fullPath = testDirRelative ? path.join(testDirRelative, file).replace(/\\/g, "/") : file.replace(/\\/g, "/");
-							if (fullPath.startsWith(normalizedInputPath + "/") || fullPath === normalizedInputPath) expandedPaths.push(fullPath);
-						}
-					}
-				} else expandedPaths.push(normalizedInputPath);
-			} catch {
-				expandedPaths.push(normalizedInputPath);
+		const listed = await server.listFiles();
+		const affected = /* @__PURE__ */ new Set();
+		const deleted = /* @__PURE__ */ new Set();
+		const candidates = /* @__PURE__ */ new Set();
+		for (const change of changes) {
+			if ("from" in change && change.status === "R") {
+				const oldFile = normalizePath(path.relative(listed.rootDir, path.resolve(gitRoot, change.from)));
+				affected.add(oldFile);
+				deleted.add(oldFile);
 			}
+			const file = normalizePath(path.relative(listed.rootDir, path.resolve(gitRoot, "to" in change ? change.to : change.path)));
+			affected.add(file);
+			if (change.status === "D") deleted.add(file);
+			else candidates.add(file);
 		}
-		if (expandedPaths.length === 0) {
-			testServer.close();
-			return;
-		}
-		const report = await testServer.getRawTestReport(expandedPaths, token);
-		function parseEntry(entry, testDir) {
-			if (entry.testId) {
-				const filePath = testDir ? path.join(testDir, entry.location.file).replace(/\\/g, "/") : entry.location.file.replace(/\\/g, "/");
-				return {
-					type: "test",
-					title: entry.title,
-					testId: entry.testId,
-					location: {
-						file: filePath,
-						line: entry.location.line,
-						column: entry.location.column
-					},
-					tags: entry.tags || [],
-					annotations: entry.annotations || [],
-					expectedStatus: "passed",
-					timeout: 0
-				};
-			} else {
-				const filePath = entry.location && testDir ? path.join(testDir, entry.location.file).replace(/\\/g, "/") : entry.location?.file.replace(/\\/g, "/");
-				const node = {
-					type: "suite",
-					title: entry.title,
-					file: filePath,
-					children: []
-				};
-				if (entry.entries && Array.isArray(entry.entries)) for (const childEntry of entry.entries) node.children.push(parseEntry(childEntry, testDir));
-				return node;
+		const pathsToCollect = /* @__PURE__ */ new Set();
+		const updatedByProject = /* @__PURE__ */ new Map();
+		const deletedFiles = /* @__PURE__ */ new Set();
+		for (const project of cachedTree.children ?? []) {
+			const files = /* @__PURE__ */ new Set();
+			for (const node of project.children ?? []) {
+				const file = normalizePath(node.file || "");
+				if (affected.has(file)) files.add(file);
+				if (deleted.has(file)) deletedFiles.add(file);
 			}
+			updatedByProject.set(project.title, files);
 		}
-		const rootNode = {
-			type: "suite",
-			title: "Root",
-			children: []
-		};
-		for (const message of report) if (message.method === "onProject") {
-			const project = message.params.project;
-			const projectNode = {
-				type: "suite",
-				title: project.name,
-				children: []
-			};
-			let testDir = "";
-			if (project.testDir) testDir = path.isAbsolute(project.testDir) ? path.relative(workspaceFolder, project.testDir).replace(/\\/g, "/") : project.testDir.replace(/\\/g, "/");
-			if (project.suites && Array.isArray(project.suites)) for (const suite of project.suites) {
-				const suiteNode = parseEntry(suite, testDir);
-				projectNode.children.push(suiteNode);
+		for (const project of listed.projects) {
+			const files = updatedByProject.get(project.name) ?? /* @__PURE__ */ new Set();
+			for (const file of project.files) {
+				if (!candidates.has(file)) continue;
+				files.add(file);
+				pathsToCollect.add(path.resolve(listed.rootDir, file));
 			}
-			rootNode.children.push(projectNode);
+			updatedByProject.set(project.name, files);
 		}
-		const jsonString = JSON.stringify(rootNode, null, 2);
-		if (outputFile) {
-			await fs.writeFile(outputFile, jsonString, "utf-8");
-			console.log(`Results saved to: ${outputFile}`);
-		} else console.log(jsonString);
-		testServer.close();
-	} catch (error) {
-		console.error("Error:", error);
-		testServer.close();
+		const partialTree = pathsToCollect.size ? consumeTestReport(await server.getRawTestReport([...pathsToCollect])) : consumeTestReport([]);
+		const merged = mergeIncrementalTree(cachedTree, partialTree, updatedByProject);
+		const projectOrder = new Map(listed.projects.map((project, index) => [project.name, index]));
+		merged.children.sort((a, b) => projectOrder.get(a.title) - projectOrder.get(b.title));
+		await save(merged);
+		const updatedFiles = pathsToCollect.size;
+		return {
+			mode: updatedFiles || deletedFiles.size ? "incremental" : "unchanged",
+			updatedFiles,
+			deletedFiles: deletedFiles.size
+		};
+	} finally {
+		server.close();
 	}
 }
-async function treeStructure(workspaceFolder = process.cwd(), configFile = "playwright.config.ts", cancellationToken, outputFile) {
-	const testServer = new PlaywrightTestServer({
-		workspaceFolder,
-		configFile: path.join(workspaceFolder, configFile)
-	});
+async function outputJson(value, outputFile) {
+	const content = JSON.stringify(value, null, 2);
+	if (outputFile) {
+		await fs.writeFile(outputFile, content, "utf8");
+		console.log(`Results saved to: ${outputFile}`);
+	} else console.log(content);
+}
+async function listTestFile(workspaceFolder = process.cwd(), configFile = "playwright.config.ts", outputFile) {
+	const server = createServer(workspaceFolder, configFile);
 	try {
-		const token = cancellationToken || new CancellationToken();
-		const files = await testServer.listFiles();
-		if (files.projects.length === 0) {
-			testServer.close();
-			return;
-		}
-		const allRelativePaths = [];
-		for (const project of files.projects) if (project.files.length > 0) {
-			const testDirRelative = project.testDir || "";
-			const relativePaths = project.files.map((file) => {
-				return testDirRelative ? path.join(testDirRelative, file).replace(/\\/g, "/") : file.replace(/\\/g, "/");
-			});
-			allRelativePaths.push(...relativePaths);
-		}
-		if (allRelativePaths.length === 0) {
-			testServer.close();
-			return;
-		}
-		const report = await testServer.getRawTestReport(allRelativePaths, token);
-		function parseEntry(entry, testDir) {
-			if (entry.testId) {
-				const filePath = entry.location.file.replace(/\\/g, "/");
-				return {
-					type: "test",
-					title: entry.title,
-					testId: entry.testId,
-					location: {
-						file: filePath,
-						line: entry.location.line,
-						column: entry.location.column
-					},
-					tags: entry.tags || [],
-					annotations: entry.annotations || [],
-					expectedStatus: "passed",
-					timeout: 0
-				};
-			} else {
-				const filePath = entry.location?.file.replace(/\\/g, "/");
-				const node = {
-					type: "suite",
-					title: entry.title,
-					file: filePath,
-					children: []
-				};
-				if (entry.entries && Array.isArray(entry.entries)) for (const childEntry of entry.entries) node.children.push(parseEntry(childEntry, testDir));
-				return node;
-			}
-		}
-		const rootNode = {
-			type: "suite",
-			title: "Root",
-			children: []
-		};
-		for (const message of report) if (message.method === "onProject") {
-			const project = message.params.project;
-			const projectNode = {
-				type: "suite",
-				title: project.name,
-				children: []
-			};
-			let testDir = "";
-			if (project.testDir) testDir = path.isAbsolute(project.testDir) ? path.relative(workspaceFolder, project.testDir).replace(/\\/g, "/") : project.testDir.replace(/\\/g, "/");
-			if (project.suites && Array.isArray(project.suites)) for (const suite of project.suites) {
-				const suiteNode = parseEntry(suite, testDir);
-				projectNode.children.push(suiteNode);
-			}
-			rootNode.children.push(projectNode);
+		const { projects } = await server.listFiles();
+		await outputJson({ projects }, outputFile);
+	} finally {
+		server.close();
+	}
+}
+async function listTestCase(workspaceFolder = process.cwd(), configFile = "playwright.config.ts", relativePaths, outputFile) {
+	workspaceFolder = path.resolve(workspaceFolder);
+	const server = createServer(workspaceFolder, configFile);
+	try {
+		const expandedPaths = /* @__PURE__ */ new Set();
+		let listed;
+		for (const input of relativePaths) {
+			const absolutePath = path.resolve(workspaceFolder, normalizePath(input));
+			if ((await fs.stat(absolutePath).catch(() => void 0))?.isDirectory()) {
+				listed ??= await server.listFiles();
+				for (const project of listed.projects) for (const file of project.files) {
+					const absoluteFile = path.resolve(listed.rootDir, file);
+					if (isWithin(absolutePath, absoluteFile)) expandedPaths.add(absoluteFile);
+				}
+			} else expandedPaths.add(absolutePath);
 		}
-		const jsonString = JSON.stringify(rootNode, null, 2);
-		if (outputFile) {
-			await fs.writeFile(outputFile, jsonString, "utf-8");
-			console.log(`Results saved to: ${outputFile}`);
-		} else console.log(jsonString);
-		testServer.close();
-	} catch (error) {
-		console.error("Error:", error);
-		testServer.close();
+		if (!expandedPaths.size) return;
+		await outputJson(consumeTestReport(await server.getRawTestReport([...expandedPaths])), outputFile);
+	} finally {
+		server.close();
 	}
 }
-
+async function treeStructure(workspaceFolder = process.cwd(), configFile = "playwright.config.ts", cancellationToken, outputFile) {
+	await outputJson(await collectFullTree(workspaceFolder, configFile, cancellationToken), outputFile);
+}
 //#endregion
-export { CancellationToken as i, listTestFile as n, treeStructure as r, listTestCase as t };
+export { CancellationToken as a, updateTreeStructure as i, listTestFile as n, treeStructure as r, listTestCase as t };

package/dist/cli.mjs

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
-import { i as CancellationToken, n as listTestFile, r as treeStructure, t as listTestCase } from "./api-Bc2ZCCQ0.mjs";
+import { a as CancellationToken, i as updateTreeStructure, n as listTestFile, r as treeStructure, t as listTestCase } from "./api-CvJUOXye.mjs";
 import path from "path";
 import { program } from "commander";
 import chalk from "chalk";
 import ora from "ora";
-
 //#region src/cli.ts
 /**
 * Playwright Test Explorer CLI
@@ -41,8 +40,8 @@ program.command("list-tests").description("List all test cases in specified file
 		process.exit(1);
 	}
 });
-program.command("tree").description("Display test structure as a tree").option("-w, --workspace <path>", "workspace folder path", process.cwd()).option("-c, --config <file>", "config file path (relative to workspace)", "playwright.config.ts").option("-o, --output <file>", "output file path to save JSON results").action(async (options) => {
-	const spinner = ora("Building test tree...").start();
+program.command("tree").description("Display test structure as a tree").option("-w, --workspace <path>", "workspace folder path", process.cwd()).option("-c, --config <file>", "config file path (relative to workspace)", "playwright.config.ts").option("-o, --output <file>", "output file path to save JSON results").option("--incremental", "update a saved tree from Git changes").option("--state <file>", "incremental state file path (defaults to <output>.state.json)").option("--cache-env <names>", "additional collection environment keys, comma-separated").action(async (options) => {
+	const spinner = ora(options.incremental ? "Updating test tree..." : "Building test tree...").start();
 	try {
 		const workspaceFolder = path.resolve(options.workspace);
 		const token = new CancellationToken();
@@ -52,8 +51,15 @@ program.command("tree").description("Display test structure as a tree").option("
 			process.exit(0);
 		});
 		const outputFile = options.output ? path.resolve(options.output) : void 0;
-		await treeStructure(workspaceFolder, options.config, token, outputFile);
-		spinner.succeed(chalk.green("Test tree built successfully"));
+		if (options.incremental) {
+			const incrementalOutput = outputFile || path.join(workspaceFolder, "test-case.json");
+			const stateFile = options.state ? path.resolve(options.state) : `${incrementalOutput}.state.json`;
+			const result = await updateTreeStructure(workspaceFolder, options.config, incrementalOutput, stateFile, { environmentKeys: options.cacheEnv?.split(",").map((key) => key.trim()).filter(Boolean) });
+			spinner.succeed(chalk.green(`Test tree ${result.mode}: ${result.updatedFiles} updated, ${result.deletedFiles} deleted`));
+		} else {
+			await treeStructure(workspaceFolder, options.config, token, outputFile);
+			spinner.succeed(chalk.green("Test tree built successfully"));
+		}
 	} catch (error) {
 		spinner.fail(chalk.red("Failed to build test tree"));
 		console.error(chalk.red("Error:"), error instanceof Error ? error.message : String(error));
@@ -90,10 +96,12 @@ ${chalk.bold("Examples:")}
   ${chalk.cyan("# Save tree structure to JSON file")}
   $ pw-test-explorer tree -o tree.json
 
+  ${chalk.cyan("# Incrementally update a saved tree from Git changes")}
+  $ pw-test-explorer tree --incremental -o tree.json
+
   ${chalk.cyan("# Display tree for specific workspace")}
   $ pw-test-explorer tree -w /path/to/project
 `);
 program.parse();
-
 //#endregion
-export {  };
+export {};

package/dist/index.d.mts

@@ -25,7 +25,6 @@ interface Event<T> {
 }
 //#endregion
 //#region src/playwrightTestServer.d.ts
-
 declare class CancellationToken {
   private _isCancelled;
   private _onCancelEmitter;
@@ -35,8 +34,19 @@ declare class CancellationToken {
 }
 //#endregion
 //#region src/api.d.ts
+type IncrementalTreeOptions = {
+  /** Additional environment variables that affect configuration or test collection. */environmentKeys?: string[];
+};
+type IncrementalTreeResult = {
+  mode: 'full' | 'incremental' | 'unchanged';
+  updatedFiles: number;
+  deletedFiles: number;
+};
+/** Share untouched branches; only replace affected project/file arrays. */
+/** Update committed test changes; non-test changes conservatively rebuild the tree. */
+declare function updateTreeStructure(workspaceFolder: string, configFile: string, outputFile: string, stateFile?: string, options?: IncrementalTreeOptions): Promise<IncrementalTreeResult>;
 declare function listTestFile(workspaceFolder?: string, configFile?: string, outputFile?: string): Promise<void>;
 declare function listTestCase(workspaceFolder: string | undefined, configFile: string | undefined, relativePaths: string[], outputFile?: string): Promise<void>;
 declare function treeStructure(workspaceFolder?: string, configFile?: string, cancellationToken?: CancellationToken, outputFile?: string): Promise<void>;
 //#endregion
-export { listTestCase, listTestFile, treeStructure };
+export { type IncrementalTreeOptions, listTestCase, listTestFile, treeStructure, updateTreeStructure };

package/dist/index.mjs

@@ -1,3 +1,2 @@
-import { n as listTestFile, r as treeStructure, t as listTestCase } from "./api-Bc2ZCCQ0.mjs";
-
-export { listTestCase, listTestFile, treeStructure };
+import { i as updateTreeStructure, n as listTestFile, r as treeStructure, t as listTestCase } from "./api-CvJUOXye.mjs";
+export { listTestCase, listTestFile, treeStructure, updateTreeStructure };

package/dist/treeReporter.mjs

@@ -0,0 +1,54 @@
+import path from "node:path";
+//#region src/treeReporter.mjs
+var TreeReporter = class {
+	tree;
+	errors = [];
+	printsToStdio() {
+		return true;
+	}
+	onBegin(config, rootSuite) {
+		const location = (value) => value && {
+			...value,
+			file: path.relative(config.rootDir, value.file).replace(/\\/g, "/")
+		};
+		const convert = (entry) => entry.type === "test" ? {
+			type: "test",
+			title: entry.title,
+			testId: entry.id,
+			location: location(entry.location),
+			tags: entry.tags || [],
+			annotations: entry.annotations.map((annotation) => ({
+				...annotation,
+				location: location(annotation.location)
+			})),
+			expectedStatus: "passed",
+			timeout: 0
+		} : {
+			type: "suite",
+			title: entry.title,
+			file: location(entry.location)?.file,
+			children: entry.entries().map(convert)
+		};
+		this.tree = {
+			type: "suite",
+			title: "Root",
+			children: rootSuite.suites.map((project) => ({
+				type: "suite",
+				title: project.title,
+				children: project.entries().map(convert)
+			}))
+		};
+	}
+	onError(error) {
+		this.errors.push(error.message || error.value || "Playwright test collection failed");
+	}
+	async onEnd(result) {
+		await new Promise((resolve, reject) => process.send({
+			type: "test-explorer:tree",
+			tree: result.status === "passed" ? this.tree : void 0,
+			error: this.errors.join("\n")
+		}, (error) => error ? reject(error) : resolve()));
+	}
+};
+//#endregion
+export { TreeReporter as default };

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "playwright-test-explorer",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "description": "A CLI tool and library for exploring Playwright tests",
   "type": "module",
   "license": "MIT",
-  "homepage": "https://github.com/author/library#readme",
+  "homepage": "https://github.com/li-zhixin/playwright-test-explorer#readme",
   "bugs": {
-    "url": "https://github.com/author/library/issues"
+    "url": "https://github.com/li-zhixin/playwright-test-explorer/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/author/library.git"
+    "url": "git+https://github.com/li-zhixin/playwright-test-explorer.git"
   },
   "author": "Author Name <author.name@mail.com>",
   "files": [
@@ -42,18 +42,18 @@
   },
   "dependencies": {
     "chalk": "^5.6.2",
-    "commander": "^14.0.2",
-    "ora": "^9.0.0",
-    "ws": "^8.18.3"
+    "commander": "^14.0.3",
+    "ora": "^9.3.0",
+    "ws": "^8.20.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.57.0",
-    "@types/node": "^24.10.1",
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.5.0",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "4.0.14",
-    "bumpp": "^10.3.2",
-    "tsdown": "^0.16.7",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.14"
+    "@vitest/coverage-v8": "4.1.2",
+    "bumpp": "^11.0.1",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
   }
 }