🧪 明确验证模式开关与示例契约

Author: cyfung1031

docs/references/verification-methods.md

@@ -77,7 +77,7 @@ From a session the same call is one command, since `eval` already runs on an ext
 
 ```bash
 node e2e/drive.mjs open options
-node e2e/drive.mjs eval "const r = await chrome.runtime.sendMessage({action:'serviceWorker/popup/getPopupData', data:{tabId, url}}); return r.data.scriptList"
+node e2e/drive.mjs eval "const [tab] = await chrome.tabs.query({active:true,lastFocusedWindow:true}); if (!tab?.id || !tab.url) throw new Error('no active tab'); const r = await chrome.runtime.sendMessage({action:'serviceWorker/popup/getPopupData', data:{tabId:tab.id, url:tab.url}}); return r.data.scriptList"
 ```
 
 This drives the real SW → content → sandbox → callback path, behaviourally identical to the popup button, which discards the DOM event and calls the same message. It is a substitution: the verdict row names it and says the popup's own click path was not covered.

e2e/fixtures.ts

@@ -32,8 +32,9 @@ const chromeArgs = [
  * 必须作为启动参数下发：`--headless=new` 会覆盖 Playwright 的 `headless` 选项，
  * 所以单独把 `headless` 设成 false（含 `--debug`/PWDEBUG）并不会开出窗口。
  */
-export function headlessArgs(): string[] {
-  return process.env.E2E_HEADED ? [] : ["--headless=new"];
+export function headlessArgs(value = process.env.E2E_HEADED): string[] {
+  const headed = /^(1|true|yes)$/i.test(value?.trim() ?? "");
+  return headed ? [] : ["--headless=new"];
 }
 
 // CI（GitHub Actions）跑在非 root 用户下不会自动应用 --no-sandbox，关掉沙箱能省下每次

tests/verification-tools.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { headlessArgs } from "../e2e/fixtures";
+
+describe("headlessArgs", () => {
+  it.each([undefined, "", "0", "false", "no"])("keeps %j headless", (value) => {
+    expect(headlessArgs(value)).toEqual(["--headless=new"]);
+  });
+
+  it.each(["1", "true", "yes"])("enables headed mode for %j", (value) => {
+    expect(headlessArgs(value)).toEqual([]);
+  });
+});