@shivaedev/test-story 0.13.0 → 0.15.0

package/src/server/internal/fakeHttpReceive.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { FakeHttpReply, FakeHttpRequest, FakeHttpRoute, FakeHttpServiceOptions } from "#fakeHttpService.ts";
+import type { FakeHttpRequest, FakeHttpRoute, FakeHttpServiceOptions } from "#fakeHttpService.ts";
+import { fakeHttpAnswer } from "#internal/fakeHttpAnswer.ts";
 import type { fakeHttpControls } from "#internal/fakeHttpControls.ts";
 import { fakeHttpSend } from "#internal/fakeHttpSend.ts";
 
@@ -35,17 +36,6 @@ function decodeParams(params: Record<string, string>) {
 	}
 }
 
-function pageReply(route: FakeHttpRoute, request: FakeHttpRequest): FakeHttpReply {
-	if (route.reply) {
-		return route.reply(request);
-	}
-	const page = Number(request.query.get("page") ?? "1");
-	if (!Number.isInteger(page) || page < 1) {
-		return { body: { error: "page must be a positive integer" }, status: 400 };
-	}
-	return { body: { items: route.pages[page - 1] ?? [], next: page < route.pages.length ? page + 1 : null } };
-}
-
 export async function fakeHttpReceive(
 	incoming: IncomingMessage,
 	response: ServerResponse,
@@ -82,7 +72,7 @@ export async function fakeHttpReceive(
 			await fakeHttpSend(response, { status: 400 });
 			return;
 		}
-		if (options.guard && !options.guard(request)) {
+		if ((options.guard && !options.guard(request)) || (found?.route.guard && !found.route.guard(request))) {
 			tell(`fake HTTP rejected ${method} ${path} with 401`);
 			await fakeHttpSend(response, { status: 401 });
 			return;
@@ -92,13 +82,7 @@ export async function fakeHttpReceive(
 			await fakeHttpSend(response, { status: 404 });
 			return;
 		}
-		controls.arrive(found.name, response);
-		if (!(await controls.pause(found.name, response))) {
-			return;
-		}
-		const reply = controls.takeReply(found.name) ?? pageReply(found.route, request);
-		tell(`fake HTTP answered ${method} ${path} with ${reply.status ?? 200}`);
-		await fakeHttpSend(response, reply, controls.stallBody(found.name));
+		await fakeHttpAnswer(found.name, found.route, request, response, controls, tell);
 	} catch (error) {
 		tell(`fake HTTP could not answer: ${String(error)}`);
 		if (response.headersSent) {

package/src/server/internal/fakeHttpScripts.ts

@@ -0,0 +1,40 @@
+import { Effect } from "effect";
+import type { FakeHttpFault, FakeHttpRequest, FakeHttpScript, FakeHttpScriptOptions } from "#fakeHttpService.ts";
+import { fakeHttpSelection } from "#internal/fakeHttpSelection.ts";
+
+export function fakeHttpScripts(tell: (line: string) => void) {
+	const scripts = new Set<{
+		selection: ReturnType<typeof fakeHttpSelection>;
+		fault: FakeHttpFault;
+		options: FakeHttpScriptOptions;
+	}>();
+	return {
+		clear: () => scripts.clear(),
+		make: (route: string, fault: FakeHttpFault, options: FakeHttpScriptOptions = {}, narrate = true): FakeHttpScript => {
+			const selection = fakeHttpSelection(route, options);
+			const script = { fault, options, selection };
+			scripts.add(script);
+			if (narrate) {
+				tell(`fake HTTP ${selection.label} will fault ${fault.kind} ${options.phase ?? "before"} reply ${options.repeat ? "until lifted" : "once"}`);
+			}
+			return {
+				lift: Effect.sync(() => {
+					if (scripts.delete(script)) {
+						tell(`fake HTTP ${selection.label} fault ${fault.kind} lifted`);
+					}
+				}),
+			};
+		},
+		take: (route: string, request: FakeHttpRequest, phase: "before" | "after") => {
+			for (const script of scripts) {
+				if ((script.options.phase ?? "before") === phase && script.selection.matches(route, request)) {
+					if (!script.options.repeat) {
+						scripts.delete(script);
+					}
+					return script.fault;
+				}
+			}
+			return undefined;
+		},
+	};
+}

package/src/server/internal/fakeHttpSelection.ts

@@ -0,0 +1,10 @@
+import type { FakeHttpRequest, FakeHttpScope } from "#fakeHttpService.ts";
+
+export function fakeHttpSelection(route: string, scope: FakeHttpScope = {}) {
+	const params = Object.entries(scope.params ?? {}).sort(([left], [right]) => left.localeCompare(right));
+	const label = params.length > 0 ? `${route} matching ${JSON.stringify(Object.fromEntries(params))}` : route;
+	return {
+		label,
+		matches: (name: string, request: FakeHttpRequest) => name === route && params.every(([key, value]) => request.params[key] === value),
+	};
+}

package/src/server/internal/fakeHttpSend.ts

@@ -1,5 +1,5 @@
 import type { ServerResponse } from "node:http";
-import type { FakeHttpReply } from "#fakeHttpService.ts";
+import type { FakeHttpFault, FakeHttpReply } from "#fakeHttpService.ts";
 
 export function fakeHttpConnection(response: ServerResponse) {
 	const closed = new Promise<undefined>((resolve) => response.once("close", () => resolve(undefined)));
@@ -53,3 +53,12 @@ export async function fakeHttpSend(response: ServerResponse, reply: FakeHttpRepl
 		response.end(body);
 	}
 }
+
+export async function fakeHttpStrike(response: ServerResponse, fault: Exclude<FakeHttpFault, { kind: "status" }>, reply: FakeHttpReply = {}) {
+	if (fault.kind === "reset") {
+		response.writeHead(reply.status ?? 200, { "content-type": "application/json", ...reply.headers });
+		response.flushHeaders();
+		await new Promise<void>((resolve) => response.write("", () => resolve()));
+	}
+	response.destroy();
+}

package/src/server/internal/screenAccessibility.ts

@@ -0,0 +1,50 @@
+import { computeAccessibleName, getRole, isInaccessible } from "dom-accessibility-api";
+import type { ScreenTarget } from "#screenDriver.ts";
+
+export function accessibility(element: Element) {
+	return { name: computeAccessibleName(element), role: getRole(element) };
+}
+
+export function targetName(target: ScreenTarget): string {
+	return typeof target === "string"
+		? target
+		: `${target.role} named ${typeof target.name === "string" ? JSON.stringify(target.name) : String(target.name)}`;
+}
+
+export function isRendered(found: HTMLElement) {
+	const visibility = getComputedStyle(found).visibility;
+	if (visibility === "hidden" || visibility === "collapse") {
+		return false;
+	}
+	for (let ancestor: HTMLElement | null = found; ancestor; ancestor = ancestor.parentElement) {
+		const style = getComputedStyle(ancestor);
+		if (ancestor.hidden || style.display === "none" || style.contentVisibility === "hidden") {
+			return false;
+		}
+	}
+	return true;
+}
+
+export function roleElement(root: HTMLElement, target: Exclude<ScreenTarget, string>) {
+	const candidates = Array.from(root.querySelectorAll<HTMLElement>("*"))
+		.filter((element) => isRendered(element) && !isInaccessible(element))
+		.map((element) => ({ ...accessibility(element), element }))
+		.filter(({ role }) => role !== null);
+	const matches = candidates.filter(({ role, name }) => {
+		if (role !== target.role) {
+			return false;
+		}
+		if (typeof target.name === "string") {
+			return name === target.name;
+		}
+		return new RegExp(target.name.source, target.name.flags).test(name);
+	});
+	const found = matches[0];
+	if (matches.length === 1 && found) {
+		return found.element;
+	}
+	const listing = candidates.map(({ role, name }) => `  - ${role} named ${JSON.stringify(name)}`).join("\n");
+	throw new Error(
+		`The screen has ${matches.length} matches for ${targetName(target)}.\nhelp: Use a role and name for exactly one visible target.\nCandidates on screen:\n${listing || "  (none)"}`,
+	);
+}

package/src/server/internal/screenElements.ts

@@ -1,17 +1,17 @@
+import { isRendered, roleElement, targetName } from "#internal/screenAccessibility.ts";
+import type { ScreenTarget } from "#screenDriver.ts";
+
 export function screenElements(root: () => HTMLElement) {
 	function rendered(found: HTMLElement, selector: string) {
-		const visibility = getComputedStyle(found).visibility;
-		let hidden = visibility === "hidden" || visibility === "collapse";
-		for (let ancestor: HTMLElement | null = found; ancestor; ancestor = ancestor.parentElement) {
-			const style = getComputedStyle(ancestor);
-			hidden ||= Boolean(ancestor.hidden) || style.display === "none" || style.contentVisibility === "hidden";
-		}
-		if (hidden) {
+		if (!isRendered(found)) {
 			throw new Error(`The screen's ${selector} is not rendered.\nhelp: Reveal the target and its ancestors before acting on or reading it.`);
 		}
 		return found;
 	}
-	function element(selector: string) {
+	function element(selector: ScreenTarget) {
+		if (typeof selector !== "string") {
+			return roleElement(root(), selector);
+		}
 		const matches = root().querySelectorAll<HTMLElement>(selector);
 		const found = matches[0];
 		if (matches.length !== 1 || found === undefined) {
@@ -21,26 +21,28 @@ export function screenElements(root: () => HTMLElement) {
 		}
 		return rendered(found, selector);
 	}
-	function input(selector: string) {
+	function input(selector: ScreenTarget) {
 		const found = element(selector);
 		if (!(found instanceof HTMLInputElement || found instanceof HTMLTextAreaElement)) {
-			throw new Error(`The screen's ${selector} is not a text field.\nhelp: Select a rendered input or textarea to enter or read a value.`);
+			throw new Error(
+				`The screen's ${targetName(selector)} is not a text field.\nhelp: Select a rendered input or textarea to enter or read a value.`,
+			);
 		}
 		return found;
 	}
-	function enabled(found: HTMLElement, selector: string) {
+	function enabled(found: HTMLElement, selector: ScreenTarget) {
 		if (found.matches(":disabled") || found.closest("[inert]")) {
-			throw new Error(`The screen's ${selector} is disabled.\nhelp: Wait for the app to enable the control before acting on it.`);
+			throw new Error(`The screen's ${targetName(selector)} is disabled.\nhelp: Wait for the app to enable the control before acting on it.`);
 		}
 	}
 	return {
 		element,
 		enabled,
-		enter: (selector: string, value: string) => {
+		enter: (selector: ScreenTarget, value: string) => {
 			const field = input(selector);
 			enabled(field, selector);
 			if (field.readOnly) {
-				throw new Error(`The screen's ${selector} is read-only.\nhelp: Select an editable input or textarea.`);
+				throw new Error(`The screen's ${targetName(selector)} is read-only.\nhelp: Select an editable input or textarea.`);
 			}
 			field.focus();
 			const prototype = field instanceof HTMLInputElement ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
@@ -48,10 +50,10 @@ export function screenElements(root: () => HTMLElement) {
 			field.dispatchEvent(new Event("input", { bubbles: true }));
 			field.dispatchEvent(new Event("change", { bubbles: true }));
 		},
-		form: (selector: string) => {
+		form: (selector: ScreenTarget) => {
 			const found = element(selector);
 			if (!(found instanceof HTMLFormElement)) {
-				throw new Error(`The screen's ${selector} is not a form.\nhelp: Select a rendered form to submit.`);
+				throw new Error(`The screen's ${targetName(selector)} is not a form.\nhelp: Select a rendered form to submit.`);
 			}
 			enabled(found, selector);
 			return found;

package/src/server/screenDriver.ts

@@ -1,8 +1,10 @@
-import { computeAccessibleName, getRole } from "dom-accessibility-api";
 import { Effect } from "effect";
 import { withLive } from "@shivaedev/effect-test/withLive.ts";
+import { accessibility, targetName } from "#internal/screenAccessibility.ts";
 import { screenElements } from "#internal/screenElements.ts";
 
+export type ScreenTarget = string | { readonly role: string; readonly name: string | RegExp };
+
 export interface ScreenDriverOptions {
 	readonly act?: (action: () => Promise<void>) => PromiseLike<void>;
 	readonly pending: () => boolean;
@@ -45,30 +47,33 @@ export function screenDriver({ root, pending, tell, act = (action) => action(),
 		return withLive(wait.pipe(Effect.timeoutOrElse({ duration: limit, orElse: timedOut })));
 	}
 	return {
-		accessible: (selector: string) => {
+		accessible: (selector: string | Element) => {
+			if (typeof selector !== "string") {
+				return accessibility(selector);
+			}
 			const element = elements.element(selector);
-			const accessible = { name: computeAccessibleName(element), role: getRole(element) };
+			const accessible = accessibility(element);
 			tell(`read the accessibility of ${selector}: ${JSON.stringify(accessible)}`);
 			return accessible;
 		},
-		click: (selector: string) =>
-			perform(`click ${selector}`, () => {
+		click: (selector: ScreenTarget) =>
+			perform(`click ${targetName(selector)}`, () => {
 				const element = elements.element(selector);
 				elements.enabled(element, selector);
 				element.focus();
 				element.click();
 			}),
-		enter: (selector: string, value: string) => perform(`enter a value in ${selector}`, () => elements.enter(selector, value)),
+		enter: (selector: ScreenTarget, value: string) => perform(`enter a value in ${targetName(selector)}`, () => elements.enter(selector, value)),
 		settle,
-		submit: (selector = "form") => perform(`submit ${selector}`, () => elements.form(selector).requestSubmit()),
-		text: (selector?: string) => {
+		submit: (selector: ScreenTarget = "form") => perform(`submit ${targetName(selector)}`, () => elements.form(selector).requestSubmit()),
+		text: (selector?: ScreenTarget) => {
 			const text = (selector === undefined ? elements.rendered(currentRoot(), "root") : elements.element(selector)).innerText;
-			tell(`read ${selector ?? "the screen"}: ${JSON.stringify(text)}`);
+			tell(`read ${selector === undefined ? "the screen" : targetName(selector)}: ${JSON.stringify(text)}`);
 			return text;
 		},
-		value: (selector: string) => {
+		value: (selector: ScreenTarget) => {
 			const value = elements.input(selector).value;
-			tell(`read the value in ${selector}: ${JSON.stringify(value)}`);
+			tell(`read the value in ${targetName(selector)}: ${JSON.stringify(value)}`);
 			return value;
 		},
 	};