objs-core 2.3.0 → 2.4.1

package/objs-extension/README.md

@@ -0,0 +1,32 @@
+# Objs Test Recorder (Chrome extension)
+
+Manifest V3 extension bundled with **Objs 2.4**. It injects Objs into the **page MAIN world** (`lib/objs-inject.js` + `bridge.js`).
+
+- **Tests** are stored as **JavaScript** from `o.exportTest()` (same idea as **Export Objs test** in the [recording example](../examples/recording/index.html)). Edit that script in the accordion textarea.
+- **Play** runs the exported script with `o.test` (sync) or **legacy JSON** via `o.playRecording`. When a run finishes, the page shows the same **`o.testOverlay()`** panel as the [recording example](../examples/recording/index.html). The **Show succeeded** checkbox sets **`o.tShowOk`** before the run (whether passed steps get “OK” lines in the log / overlay).
+- **Stop** after recording updates both the script and an internal snapshot for `recordingSnapshot` (Playwright export).
+- Each test has **Observe root** (selector) and **`o.autotag`** (default `qa` → `data-qa`), applied on Record / Play in the page before Objs runs.
+
+The Objs project does **not** publish this to the public Chrome Web Store. Package it for your org (zip, private store, policy).
+
+## Load unpacked (development)
+
+1. Run `npm run build` at the repo root so `lib/objs-inject.js` matches `objs.js`.
+2. Open `chrome://extensions`, enable **Developer mode**, **Load unpacked**, select this **`objs-extension`** folder.
+3. Open a normal **http(s)** tab. Open the extension **popup** — tab resolution uses the **browser** window, not the popup.
+
+## Enterprise packaging
+
+- Zip the contents of `objs-extension/` for internal distribution.
+- Adjust `manifest.json` **host_permissions** if `<all_urls>` is too broad for your policy.
+- Sign or deploy via Chrome policy / internal store per your IT guidelines.
+
+## Files
+
+| File | Role |
+|------|------|
+| `manifest.json` | MV3 manifest (`tabs` permission for reliable tab URL resolution) |
+| `background.js` | Service worker: inject Objs, `getTargetTabId`, messaging |
+| `sidepanel.html` / `sidepanel.js` | Accordion UI per test |
+| `bridge.js` | `stopAndExport`, `runExportedTest`, `playRecording`, etc. |
+| `lib/objs-inject.js` | Generated by `npm run build` — do not edit by hand |

package/objs-extension/background.js

@@ -0,0 +1,110 @@
+/**
+ * Objs Test Recorder — MV3 service worker
+ *
+ * UI opens via action.default_popup (sidepanel.html). No side_panel manifest key —
+ * that key is Chromium-version-specific and triggers “Unrecognized manifest key” in
+ * many browsers; popup works everywhere.
+ *
+ * Tab resolution: chrome.tabs.query({ active: true, lastFocusedWindow: true }) from the
+ * popup often returns no tab (the popup window has focus). Resolve the last-focused
+ * *normal* browser window’s active http(s) tab instead.
+ */
+async function getTargetTabId() {
+	const tryUrl = (u) => u && /^https?:\/\//i.test(u);
+
+	/* Prefer a normal browser window (not the extension popup) */
+	try {
+		const normalActive = await chrome.tabs.query({ active: true, windowType: "normal" });
+		const na = normalActive.find((x) => tryUrl(x.url));
+		if (na?.id != null) return na.id;
+	} catch {
+		/* windowType not supported in some builds */
+	}
+
+	const last = await chrome.windows.getLastFocused({ populate: true });
+	if (last.type === "normal" && last.tabs) {
+		const t = last.tabs.find((x) => x.active && tryUrl(x.url));
+		if (t?.id != null) return t.id;
+	}
+
+	const wins = await chrome.windows.getAll({ populate: true, windowTypes: ["normal"] });
+	for (const w of wins) {
+		const t = w.tabs?.find((x) => x.active && tryUrl(x.url));
+		if (t?.id != null) return t.id;
+	}
+
+	const any = await chrome.tabs.query({});
+	const t = any.find((x) => x.active && tryUrl(x.url));
+	if (t?.id != null) return t.id;
+
+	throw new Error("Open an http(s) page in a normal tab and try again.");
+}
+
+async function ensureInjected(tabId) {
+	const [check] = await chrome.scripting.executeScript({
+		target: { tabId },
+		world: "MAIN",
+		func: () => ({
+			hasO: typeof window.o !== "undefined",
+			hasBridge: typeof window.__objsExtensionBridge !== "undefined",
+		}),
+	});
+	const { hasO, hasBridge } = check.result || {};
+	if (hasO && hasBridge) return;
+	await chrome.scripting.executeScript({
+		target: { tabId },
+		world: "MAIN",
+		files: ["lib/objs-inject.js", "bridge.js"],
+	});
+}
+
+async function invokeBridge(tabId, method, arg) {
+	await ensureInjected(tabId);
+	const [out] = await chrome.scripting.executeScript({
+		target: { tabId },
+		world: "MAIN",
+		func: async (payload) => {
+			const b = window.__objsExtensionBridge;
+			if (!b) return { error: "Bridge not loaded" };
+			try {
+				const fn = b[payload.method];
+				if (typeof fn !== "function") return { error: "Unknown method: " + payload.method };
+				const r = fn.call(b, payload.arg);
+				if (r && typeof r.then === "function") {
+					return { value: await r };
+				}
+				return { value: r };
+			} catch (e) {
+				return { error: String(e && e.message ? e.message : e) };
+			}
+		},
+		args: [{ method, arg }],
+	});
+	const res = out.result;
+	if (res.error) throw new Error(res.error);
+	return res.value;
+}
+
+chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
+	if (msg.type === "getTabId") {
+		getTargetTabId()
+			.then((tabId) => sendResponse({ ok: true, tabId }))
+			.catch((e) => sendResponse({ ok: false, error: String(e && e.message ? e.message : e) }));
+		return true;
+	}
+	if (msg.type === "invoke") {
+		const tabId = msg.tabId;
+		if (tabId == null) {
+			getTargetTabId()
+				.then((id) => invokeBridge(id, msg.method, msg.arg))
+				.then((r) => sendResponse({ ok: true, result: r }))
+				.catch((e) => sendResponse({ ok: false, error: String(e && e.message ? e.message : e) }));
+		} else {
+			invokeBridge(tabId, msg.method, msg.arg)
+				.then((r) => sendResponse({ ok: true, result: r }))
+				.catch((e) => sendResponse({ ok: false, error: String(e && e.message ? e.message : e) }));
+		}
+		return true;
+	}
+	return false;
+});

package/objs-extension/bridge.js

@@ -0,0 +1,193 @@
+/**
+ * Objs extension bridge — runs in page MAIN world after objs-inject.js
+ */
+(function () {
+	function ensureO() {
+		if (typeof window.o === "undefined") {
+			throw new Error("Objs is not loaded");
+		}
+	}
+
+	/** Maps extension “Show succeeded” to o.tShowOk (whether OK step lines are written to o.tLog). */
+	function applyTShowOkFromPayload(payload) {
+		if (payload && payload.overlay && typeof payload.overlay.showSucceeded === "boolean") {
+			window.o.tShowOk = payload.overlay.showSucceeded;
+		}
+	}
+
+	/** Sets o.autotag (data-{name} for selectors); empty string clears it. */
+	function applyAutotagFromPayload(payload) {
+		if (!payload || typeof payload.autotag !== "string" || typeof window.o === "undefined") return;
+		const s = payload.autotag.trim();
+		window.o.autotag = s === "" ? undefined : s;
+	}
+
+	/** Same as recording example: draggable panel with o.tLog / o.tRes (pass/fail per test). */
+	function showTestResultsOverlay() {
+		const o = window.o;
+		if (typeof o.testOverlay !== "function") return;
+		try {
+			o.testOverlay();
+			if (o.testOverlay.showPanel) o.testOverlay.showPanel();
+		} catch {
+			/* ignore */
+		}
+	}
+
+	window.__objsExtensionBridge = {
+		ping() {
+			return typeof window.o !== "undefined";
+		},
+
+		/** Open o.testOverlay() + results list on the page (same as after Play). */
+		showTestOverlay(payload) {
+			ensureO();
+			applyTShowOkFromPayload(payload || {});
+			showTestResultsOverlay();
+			return { shown: true };
+		},
+
+		startRecording(payload) {
+			ensureO();
+			applyAutotagFromPayload(payload || {});
+			const p = payload || {};
+			const observe = p.observe ? String(p.observe) : undefined;
+			const bag = {};
+			if (observe) bag.observe = observe;
+			if (p.strictCaptureAssertions) bag.strictCaptureAssertions = true;
+			if (p.strictCaptureNetwork) bag.strictCaptureNetwork = true;
+			if (p.strictCaptureWebSocket) bag.strictCaptureWebSocket = true;
+			if (Object.keys(bag).length > 0) window.o.startRecording(bag);
+			else window.o.startRecording();
+			return { active: true };
+		},
+
+		stopRecording() {
+			ensureO();
+			return window.o.stopRecording();
+		},
+
+		/**
+		 * Stop recording and return both raw recording and o.exportTest() JS (primary format for the extension).
+		 */
+		stopAndExport(payload) {
+			ensureO();
+			const recording = window.o.stopRecording();
+			const options = Object.assign({}, (payload && payload.options) || {}, { extensionExport: true });
+			const script = window.o.exportTest(recording, options);
+			return { recording, script };
+		},
+
+		/**
+		 * Run an o.exportTest() script: executes o.test(..., { sync: true }, ...) in-page and polls tFinalized.
+		 * Legacy scripts with o.addTest are rewritten to o.test + sync (addTest + run() interleaves async steps wrong).
+		 */
+		runExportedTest(payload) {
+			ensureO();
+			applyAutotagFromPayload(payload || {});
+			applyTShowOkFromPayload(payload);
+			const code = String((payload && payload.code) || "");
+			if (!code.includes("o.addTest") && !code.includes("o.test")) {
+				throw new Error("Script must contain o.test(...) or o.addTest(...) from o.exportTest()");
+			}
+			let patched = code.trim();
+			if (patched.includes("o.addTest")) {
+				patched = patched.replace(
+					/\bo\.addTest\s*\(\s*(['"])Recorded test\1\s*,\s*\[/,
+					"const __objsExtensionTestRun = o.test($1Recorded test$1,"
+				);
+				patched = patched.replace(
+					/\]\s*\n(\s*\/\/ Add manual checks[^\n]*)/,
+					"],\n$1"
+				);
+				patched = patched.replace(
+					/\n\s*\]\s*,\s*\(\)\s*=>\s*\{\s*\r?\n\s*\/\/ teardown/,
+					",\n{ sync: true }, () => {\n  // teardown"
+				);
+			}
+			if (!patched.includes("__objsExtensionTestRun")) {
+				throw new Error("Expected const __objsExtensionTestRun from o.exportTest(); legacy addTest upgrade failed");
+			}
+			const fullCode = patched + "\nreturn __objsExtensionTestRun;";
+			let testId;
+			try {
+				testId = new Function("o", fullCode)(window.o);
+			} catch (e) {
+				throw new Error((e && e.message) || String(e));
+			}
+			const tid = Number(testId);
+			if (!Number.isFinite(tid) || tid < 0) {
+				throw new Error("o.test did not return a valid test id");
+			}
+			return new Promise((resolve, reject) => {
+				try {
+					const deadline = Date.now() + 120000;
+					let finished = false;
+					const poll = () => {
+						if (finished) return;
+						if (window.o.tFinalized && window.o.tFinalized[tid]) {
+							finished = true;
+							showTestResultsOverlay();
+							resolve({
+								testId: tid,
+								passed: !!window.o.tRes[tid],
+							});
+							return;
+						}
+						if (Date.now() > deadline) {
+							finished = true;
+							showTestResultsOverlay();
+							resolve({
+								testId: tid,
+								passed: !!window.o.tRes[tid],
+								timedOut: true,
+							});
+							return;
+						}
+						setTimeout(poll, 40);
+					};
+					setTimeout(poll, 0);
+				} catch (e) {
+					reject(e);
+				}
+			});
+		},
+
+		playRecording(payload) {
+			ensureO();
+			applyAutotagFromPayload(payload || {});
+			applyTShowOkFromPayload(payload);
+			const recording = payload.recording;
+			const opts = Object.assign({ runAssertions: true }, payload.opts || {});
+			return new Promise((resolve, reject) => {
+				try {
+					opts.onComplete = (assertionResult) => {
+						showTestResultsOverlay();
+						resolve({ assertionResult: assertionResult || null });
+					};
+					window.o.playRecording(recording, opts);
+				} catch (e) {
+					reject(e);
+				}
+			});
+		},
+
+		exportTest(payload) {
+			ensureO();
+			return window.o.exportTest(
+				payload.recording,
+				Object.assign({}, payload.options || {}, { extensionExport: true }),
+			);
+		},
+
+		exportPlaywrightTest(payload) {
+			ensureO();
+			return window.o.exportPlaywrightTest(payload.recording, payload.options || {});
+		},
+
+		recorderActive() {
+			if (typeof window.o === "undefined") return false;
+			return !!(window.o.recorder && window.o.recorder.active);
+		},
+	};
+})();