@venn-lang/browser 0.1.0

package/dist/index.js

@@ -0,0 +1,641 @@
+import { VennError } from "@venn-lang/contracts";
+import { Duration, arg, defineAction, defineMatcher, definePlugin, defineResource, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/drivers/fake-driver.ts
+/**
+* Discards an already-evaluated side effect and resolves void. Lets a method
+* body stay a single expression whatever the mutation returned.
+*/
+function after(_effect) {
+	return Promise.resolve();
+}
+function navigate(state, url) {
+	state.url = url;
+	state.history.push(url);
+}
+function recordFill(state, args) {
+	state.fills.push({
+		selector: args.selector,
+		value: args.value
+	});
+	const element = state.elements.get(args.selector);
+	if (element) element.value = args.value;
+}
+function enterFrame(state, name) {
+	state.frame = name;
+}
+function bumpCookies(state) {
+	state.cookiesCleared += 1;
+}
+function toElements(input) {
+	const elements = /* @__PURE__ */ new Map();
+	for (const [selector, partial] of Object.entries(input)) elements.set(selector, {
+		visible: true,
+		text: "",
+		value: "",
+		...partial
+	});
+	return elements;
+}
+function initState(options) {
+	const url = options.url ?? "about:blank";
+	return {
+		url,
+		history: options.url ? [url] : [],
+		clicks: [],
+		fills: [],
+		frame: void 0,
+		cookiesCleared: 0,
+		evalResult: { ok: true },
+		elements: toElements(options.elements ?? {})
+	};
+}
+function coreMethods(state) {
+	return {
+		launch: (opts) => Promise.resolve({
+			id: "browser-1",
+			engine: opts.engine ?? "chromium"
+		}),
+		newContext: () => Promise.resolve({
+			id: "page-1",
+			url: state.url
+		}),
+		visit: (args) => after(navigate(state, args.url)),
+		click: (selector) => after(state.clicks.push(selector)),
+		fill: (args) => after(recordFill(state, args)),
+		select: (args) => after(recordFill(state, args)),
+		hover: () => Promise.resolve(),
+		press: () => Promise.resolve()
+	};
+}
+function extraMethods(state) {
+	return {
+		upload: () => Promise.resolve(),
+		download: () => Promise.resolve({
+			path: "/artifacts/download.bin",
+			bytes: 0
+		}),
+		screenshot: (name) => Promise.resolve({
+			name,
+			path: `/artifacts/${name}.png`
+		}),
+		waitFor: () => Promise.resolve(),
+		waitForUrl: (url) => after(navigate(state, url)),
+		evaluate: () => Promise.resolve(state.evalResult),
+		frame: (args) => after(enterFrame(state, args.name)),
+		clearCookies: () => after(bumpCookies(state))
+	};
+}
+/**
+* The offline `BrowserDriver`. Every method resolves at once against an
+* in-memory page, so a test never waits on a real browser.
+*
+* @param options elements to preload and the URL to start at.
+* @returns a fresh driver whose `state` records what the flow did.
+*/
+function createFakeBrowserDriver(options = {}) {
+	const state = initState(options);
+	return {
+		...coreMethods(state),
+		...extraMethods(state),
+		state,
+		element: (selector) => state.elements.get(selector)
+	};
+}
+//#endregion
+//#region src/port/browser-driver.port.ts
+/**
+* The port every `browser` verb reaches through. Requires the `net` capability,
+* so a host without it fails to load the plugin rather than failing mid-run.
+*
+* `methods` must list every method a verb calls. An omission is not checked at
+* load time, so it surfaces as a TypeError mid-run instead of a legible VN2011.
+*/
+const BrowserDriverPort = {
+	id: "venn.port.browser-driver",
+	version: 1,
+	requires: ["net"],
+	methods: [
+		"launch",
+		"newContext",
+		"visit",
+		"click",
+		"fill",
+		"select",
+		"hover",
+		"press",
+		"upload",
+		"download",
+		"screenshot",
+		"waitFor",
+		"waitForUrl",
+		"evaluate",
+		"frame",
+		"clearCookies"
+	]
+};
+//#endregion
+//#region src/port/preview-provider.port.ts
+/**
+* The port a live view of a run pulls frames from. Requires no capability: both
+* implementations here are in-process, so the port loads anywhere.
+*/
+const PreviewProviderPort = {
+	id: "venn.port.preview-provider",
+	version: 1,
+	requires: [],
+	methods: [
+		"start",
+		"stop",
+		"latestFrame"
+	]
+};
+//#endregion
+//#region src/drivers/real-driver.ts
+function notImplemented() {
+	return new VennError({
+		code: "VN8090",
+		message: "browser real driver not implemented in this build"
+	});
+}
+/**
+* The engine-driving `BrowserDriver`. Not wired up in this repo, which ships
+* the language rather than an automation backend.
+*
+* Methods are generated from the port descriptor, so the stub cannot fall
+* behind the interface.
+*
+* @returns a driver whose every method throws, so the gap is a legible failure
+* rather than a test that passes against nothing.
+* @throws {VennError} `VN8090` on any call.
+*/
+function createRealBrowserDriver() {
+	const fail = () => {
+		throw notImplemented();
+	};
+	const entries = BrowserDriverPort.methods.map((method) => [method, fail]);
+	return Object.fromEntries(entries);
+}
+//#endregion
+//#region src/actions/support.ts
+/** The browser driver bound to this run. */
+function browserDriver(ctx) {
+	return ctx.port(BrowserDriverPort);
+}
+/** The first positional argument as a string. A missing one reads as `""`. */
+function arg0(input) {
+	return String(input.args[0] ?? "");
+}
+/** The second positional argument as a string. A missing one reads as `""`. */
+function arg1(input) {
+	return String(input.args[1] ?? "");
+}
+//#endregion
+//#region src/actions/capture.ts
+/**
+* `browser.screenshot "checkout-empty"`.
+*
+* Captures the page as it stands and files it under the given name.
+*
+* @returns a `browser.Screenshot` saying where the image landed.
+*/
+const screenshot = defineAction({
+	name: "screenshot",
+	doc: "Capture a screenshot by name.",
+	args: [arg("name", t.string, "What to file it under.")],
+	result: t.ref("browser.Screenshot"),
+	run: (ctx, input) => browserDriver(ctx).screenshot(arg0(input))
+});
+/**
+* `browser.download "#invoice-pdf"`.
+*
+* Clicks something that starts a download and waits for the file to land.
+*
+* @returns a `browser.Download` saying where the file landed and how big it is.
+*/
+const download = defineAction({
+	name: "download",
+	doc: "Trigger and capture a download from a selector.",
+	args: [arg("selector", t.string, "What to act on: a CSS selector, or visible text.")],
+	result: t.ref("browser.Download"),
+	run: (ctx, input) => browserDriver(ctx).download({ selector: arg0(input) })
+});
+/**
+* `browser.evaluate "document.title"`.
+*
+* Runs JavaScript inside the page and hands back what it evaluated to. The
+* escape hatch for whatever the other verbs cannot reach.
+*
+* The result is `dynamic`: narrowing it would be a guess about someone else's
+* script.
+*/
+const evaluate = defineAction({
+	name: "evaluate",
+	doc: "Evaluate a script in the page and return its value.",
+	args: [arg("script", t.string, "JavaScript to run in the page.")],
+	result: t.dynamic,
+	run: (ctx, input) => browserDriver(ctx).evaluate({ script: arg0(input) })
+});
+//#endregion
+//#region src/actions/frame.ts
+/**
+* `browser.frame "payment-iframe"`.
+*
+* Points the following steps at an iframe, by its name or a selector for it.
+* Selectors do not cross a frame boundary, so anything inside one needs this
+* first.
+*/
+const frame = defineAction({
+	name: "frame",
+	doc: "Enter an iframe by name or selector for nested steps.",
+	args: [arg("name", t.string, "The iframe's name, or a selector for it.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).frame({ name: arg0(input) })
+});
+//#endregion
+//#region src/actions/input.ts
+const uploadParams = z.object({ file: z.string() });
+function pressArgs(input) {
+	return input.args.length > 1 ? {
+		selector: arg0(input),
+		key: arg1(input)
+	} : { key: arg0(input) };
+}
+/**
+* `browser.click "#submit"`.
+*
+* Clicks the matching element, waiting for it to be ready first.
+*/
+const click = defineAction({
+	name: "click",
+	doc: "Click the element matching a selector.",
+	args: [arg("selector", t.string, "What to act on: a CSS selector, or visible text.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).click(arg0(input))
+});
+/**
+* `browser.fill "#email" "ada@example.test"`.
+*
+* Replaces whatever an input holds with the given value.
+*/
+const fill = defineAction({
+	name: "fill",
+	doc: "Fill an input with a value.",
+	args: [arg("selector", t.string, "What to act on: a CSS selector, or visible text."), arg("value", t.string, "What to type into it.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).fill({
+		selector: arg0(input),
+		value: arg1(input)
+	})
+});
+/**
+* `browser.select "#country" "BR"`.
+*
+* Picks an option in a dropdown. The second argument is the option's value
+* attribute, not the label the user sees.
+*/
+const select = defineAction({
+	name: "select",
+	doc: "Select an option by value.",
+	args: [arg("selector", t.string, "What to act on: a CSS selector, or visible text."), arg("value", t.string, "The option's value, not its label.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).select({
+		selector: arg0(input),
+		value: arg1(input)
+	})
+});
+/**
+* `browser.hover ".menu-trigger"`.
+*
+* Moves the pointer over an element, which is how a hover menu or tooltip is
+* made to appear.
+*/
+const hover = defineAction({
+	name: "hover",
+	doc: "Hover over an element.",
+	args: [arg("selector", t.string, "What to act on: a CSS selector, or visible text.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).hover(arg0(input))
+});
+/**
+* `browser.press "Enter"`, or `browser.press "#search" "Enter"`.
+*
+* Sends a keystroke. Called with one argument, the page has focus and the
+* argument is the key. Called with two, the first is a selector to focus and
+* the second is the key.
+*
+* Both shapes are strings, so a single signature of two strings covers them.
+*/
+const press = defineAction({
+	name: "press",
+	doc: "Press a key, optionally focused on a selector.",
+	args: [arg("key", t.string, "The key to press: `Enter`, `Escape`, `Control+A`."), arg("selector", t.string, "What to focus first. Omit it and the page has focus.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).press(pressArgs(input))
+});
+/**
+* `browser.upload "#avatar" { file: "./fixtures/face.png" }`.
+*
+* Hands a file to a file input, as picking one in the OS dialog would.
+*/
+const upload = defineAction({
+	name: "upload",
+	doc: "Upload a file to a file input.",
+	params: uploadParams,
+	args: [arg("selector", t.string, "What to act on: a CSS selector, or visible text.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).upload({
+		selector: arg0(input),
+		file: input.params.file
+	})
+});
+//#endregion
+//#region src/actions/navigation.ts
+const launchParams = z.object({
+	engine: z.string().optional(),
+	headless: z.boolean().optional()
+});
+const contextParams = z.object({
+	locale: z.string().optional(),
+	viewport: z.object({
+		width: z.number(),
+		height: z.number()
+	}).optional()
+});
+const visitParams = z.object({ headers: z.record(z.string(), z.string()).optional() });
+/**
+* `browser.launch { engine: "chromium", headless: true }`.
+*
+* Starts a browser engine. Everything else in the namespace needs one running.
+*
+* @returns a `browser.Browser` handle.
+*/
+const launch = defineAction({
+	name: "launch",
+	doc: "Launch a browser engine.",
+	params: launchParams.optional(),
+	result: t.ref("browser.Browser"),
+	run: (ctx, input) => browserDriver(ctx).launch(input.params ?? {})
+});
+/**
+* `browser.visit "/checkout" { headers: { "X-Debug": "1" } }`.
+*
+* Navigates the page and waits for it to load. A relative path joins the base
+* URL; an absolute one is used as given.
+*/
+const visit = defineAction({
+	name: "visit",
+	doc: "Navigate the page to a URL.",
+	params: visitParams.optional(),
+	args: [arg("url", t.string, "Where to go. Relative paths join the base URL.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).visit({
+		url: arg0(input),
+		headers: input.params?.headers
+	})
+});
+/**
+* `browser.waitForUrl "/orders/*"`.
+*
+* Blocks until the page lands on a matching URL. Use it after an action that
+* navigates on its own, such as a form submit or a redirect.
+*/
+const waitForUrl = defineAction({
+	name: "waitForUrl",
+	doc: "Wait until the page URL matches.",
+	args: [arg("url", t.string, "The URL to wait for. A pattern is allowed.")],
+	result: t.void,
+	run: (ctx, input) => browserDriver(ctx).waitForUrl(arg0(input))
+});
+/**
+* `browser.newContext { locale: "pt-BR", viewport: { width: 1280, height: 800 } }`.
+*
+* Opens an isolated context: its own cookies, storage and viewport. Two
+* contexts in one browser cannot see each other's session.
+*
+* @returns a `browser.Page` handle.
+*/
+const newContext = defineAction({
+	name: "newContext",
+	doc: "Open an isolated browser context (a Page).",
+	params: contextParams.optional(),
+	result: t.ref("browser.Page"),
+	run: (ctx, input) => browserDriver(ctx).newContext(input.params ?? {})
+});
+/**
+* `browser.clearCookies`.
+*
+* Drops every cookie in the current context, logging the session out. Storage
+* is left alone.
+*/
+const clearCookies = defineAction({
+	name: "clearCookies",
+	doc: "Clear all cookies in the current context.",
+	result: t.void,
+	run: (ctx) => browserDriver(ctx).clearCookies()
+});
+//#endregion
+//#region src/actions/index.ts
+/** Every verb in the `browser` namespace, in the order the plugin registers them. */
+const browserActions = [
+	launch,
+	visit,
+	click,
+	fill,
+	select,
+	hover,
+	press,
+	upload,
+	download,
+	screenshot,
+	defineAction({
+		name: "waitFor",
+		doc: "Wait for a condition (text or selector) on the page.",
+		params: z.object({
+			text: z.string().optional(),
+			selector: z.string().optional(),
+			timeout: Duration.optional()
+		}).optional(),
+		result: t.void,
+		run: (ctx, input) => browserDriver(ctx).waitFor(input.params ?? {})
+	}),
+	waitForUrl,
+	evaluate,
+	frame,
+	newContext,
+	clearCookies
+];
+//#endregion
+//#region src/matchers/text.ts
+/**
+* `expect element text "Order confirmed"`.
+*
+* Passes when the element's text equals or contains the expected string.
+* Containment is deliberate: assertions about copy should survive a stray
+* space or a wrapping node.
+*/
+const text = defineMatcher({
+	name: "text",
+	args: [arg("value", t.string, "The text the element should carry.")],
+	appliesTo: "Element",
+	test: ({ subject, args }) => matchesText(subject, String(args[0])),
+	message: ({ args }) => `expected the element text to contain "${String(args[0])}"`
+});
+function matchesText(subject, expected) {
+	const actual = subject?.text ?? "";
+	return actual === expected || actual.includes(expected);
+}
+//#endregion
+//#region src/matchers/visible.ts
+/**
+* `expect element visible`.
+*
+* Passes when the element is on screen. An element that is absent, or whose
+* subject is not an element at all, fails rather than erroring.
+*/
+const visible = defineMatcher({
+	name: "visible",
+	appliesTo: "Element",
+	test: ({ subject }) => isVisible(subject),
+	message: () => "expected the element to be visible"
+});
+function isVisible(subject) {
+	return subject?.visible === true;
+}
+//#endregion
+//#region src/matchers/index.ts
+/** Every matcher the `browser` namespace contributes to `expect`. */
+const browserMatchers = [visible, text];
+/** Runtime validators for the nominal types the `browser` namespace registers. */
+const browserTypes = {
+	Browser: z.object({
+		id: z.string(),
+		engine: z.string()
+	}),
+	Page: z.object({
+		id: z.string(),
+		url: z.string()
+	}),
+	Element: z.object({
+		visible: z.boolean(),
+		text: z.string(),
+		value: z.string()
+	})
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* The `@venn-lang/browser` plugin. Registers the `browser` namespace: sixteen verbs,
+* the `visible` and `text` matchers, the `Browser` and `Page` resources, and
+* the nominal types those hand around. Requires the `net` capability.
+*/
+const browserPlugin = definePlugin({
+	name: "venn/browser",
+	version: "0.0.0",
+	namespace: "browser",
+	requires: ["net"],
+	actions: browserActions,
+	matchers: browserMatchers,
+	resources: [defineResource({
+		name: "Browser",
+		scope: "worker",
+		open: () => ({
+			id: "browser-1",
+			engine: "chromium"
+		}),
+		close: () => void 0
+	}), defineResource({
+		name: "Page",
+		scope: "flow",
+		open: () => ({
+			id: "page-1",
+			url: "about:blank"
+		}),
+		close: () => void 0
+	})],
+	types: browserTypes,
+	typeDefs: {
+		/** A launched engine. Held, passed to the `browser` verbs, closed by scope. */
+		Browser: t.opaque("browser.Browser", {
+			id: t.string,
+			engine: t.string
+		}),
+		/** An isolated context: which one it is, and where it currently points. */
+		Page: t.opaque("browser.Page", {
+			id: t.string,
+			url: t.string
+		}),
+		/**
+		* A resolved element: the subject `visible` and `text` match against. The
+		* selector is how an element is found, not something it carries, so what the
+		* matchers are handed is `{ visible, text, value }`, all three always set.
+		*/
+		Element: t.record({
+			visible: t.bool,
+			text: t.string,
+			value: t.string
+		}, { open: true }),
+		/** What `browser.download` captured: where it landed, and how big it was. */
+		Download: t.record({
+			path: t.string,
+			bytes: t.number
+		}),
+		/** What `browser.screenshot` captured, under the name it was asked for. */
+		Screenshot: t.record({
+			name: t.string,
+			path: t.string
+		})
+	}
+});
+//#endregion
+//#region src/preview/fake-preview.ts
+function startStream(streaming, worker) {
+	streaming.add(worker);
+	return Promise.resolve();
+}
+function stopStream(streaming, worker) {
+	streaming.delete(worker);
+	return Promise.resolve();
+}
+function cannedFrame(worker) {
+	return {
+		seq: worker + 1,
+		width: 1280,
+		height: 800,
+		mime: "image/jpeg",
+		data: "ZmFrZS1mcmFtZQ=="
+	};
+}
+/**
+* The in-memory `PreviewProvider`. Hands back a fixed JPEG for any worker that
+* has been started, and nothing for one that has not.
+*
+* @returns a fresh provider with no worker streaming.
+*/
+function createFakePreviewProvider() {
+	const streaming = /* @__PURE__ */ new Set();
+	return {
+		start: (target) => startStream(streaming, target.worker),
+		stop: (target) => stopStream(streaming, target.worker),
+		latestFrame: (target) => streaming.has(target.worker) ? cannedFrame(target.worker) : void 0
+	};
+}
+//#endregion
+//#region src/preview/none-preview.ts
+/**
+* The `PreviewProvider` that captures nothing. The default on CI, where nobody
+* is watching and a frame stream is pure cost.
+*
+* @returns a provider that accepts every call and never yields a frame.
+*/
+function createNonePreviewProvider() {
+	return {
+		start: () => Promise.resolve(),
+		stop: () => Promise.resolve(),
+		latestFrame: () => void 0
+	};
+}
+//#endregion
+export { BrowserDriverPort, PreviewProviderPort, browserPlugin, browserPlugin as default, createFakeBrowserDriver, createFakePreviewProvider, createNonePreviewProvider, createRealBrowserDriver };
+
+//# sourceMappingURL=index.js.map