@prosopo/procaptcha-frictionless 2.16.2 → 2.16.4

package/src/tests/executeBeforeMount.test.tsx

@@ -0,0 +1,231 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Ti18n } from "@prosopo/locale";
+import {
+	type Account,
+	type BotDetectionFunction,
+	type BotDetectionFunctionResult,
+	CaptchaType,
+	ModeEnum,
+	type ProcaptchaClientConfigInput,
+	type ProcaptchaProps,
+	type RandomProvider,
+	StartModeEnum,
+} from "@prosopo/types";
+import { type ReactElement, act, createElement, useEffect } from "react";
+import { type Root, createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+declare global {
+	var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+const EXECUTE_EVENT = "procaptcha:execute";
+
+const mocks = vi.hoisted(() => ({
+	executes: [] as ("container" | "document")[],
+}));
+
+// Listens the way the real inner widgets do: on the container in either
+// mode, and on document only when invisible.
+const ListeningWidget = (props: ProcaptchaProps) => {
+	const { container } = props;
+	const invisible = props.config.mode === "invisible";
+	useEffect(() => {
+		const onContainer = () => mocks.executes.push("container");
+		const onDocument = () => mocks.executes.push("document");
+		container?.addEventListener(EXECUTE_EVENT, onContainer);
+		if (invisible) document.addEventListener(EXECUTE_EVENT, onDocument);
+		return () => {
+			container?.removeEventListener(EXECUTE_EVENT, onContainer);
+			if (invisible) document.removeEventListener(EXECUTE_EVENT, onDocument);
+		};
+	}, [container, invisible]);
+	return createElement("div", { "data-widget": "image" });
+};
+
+vi.mock("@prosopo/procaptcha-react", () => ({ Procaptcha: ListeningWidget }));
+vi.mock("@prosopo/procaptcha-pow", () => ({ ProcaptchaPow: ListeningWidget }));
+vi.mock("@prosopo/procaptcha-puzzle", () => ({
+	ProcaptchaPuzzle: ListeningWidget,
+}));
+
+vi.mock("@prosopo/procaptcha-common", async (importOriginal) => {
+	const actual =
+		await importOriginal<typeof import("@prosopo/procaptcha-common")>();
+	return { ...actual, isSecureBrowserContext: () => true };
+});
+
+const { ProcaptchaFrictionless } = await import("../ProcaptchaFrictionless.js");
+
+const config = (
+	overrides: Partial<ProcaptchaClientConfigInput> = {},
+): ProcaptchaClientConfigInput => ({
+	account: { address: "5siteKey" },
+	userAccountAddress: "",
+	web2: true,
+	mode: ModeEnum.invisible,
+	startMode: StartModeEnum.auto,
+	...overrides,
+});
+
+const i18nStub = {
+	isInitialized: true,
+	language: "en",
+	t: (key: string) => key,
+	changeLanguage: vi.fn(),
+} as unknown as Ti18n;
+
+const detectionResult = (): BotDetectionFunctionResult => ({
+	status: "ok",
+	captchaType: CaptchaType.image,
+	sessionId: "provider-session",
+	provider: { provider: { url: "https://provider.test" } } as RandomProvider,
+	userAccount: { account: { address: "5FakeUserAccountAddress" } } as Account,
+});
+
+interface HeldDetection {
+	detectBot: ReturnType<typeof vi.fn<BotDetectionFunction>>;
+	finish: () => Promise<void>;
+}
+
+const heldDetection = (): HeldDetection => {
+	let resolve: ((result: BotDetectionFunctionResult) => void) | undefined;
+	const detectBot = vi.fn<BotDetectionFunction>().mockImplementation(
+		() =>
+			new Promise<BotDetectionFunctionResult>((r) => {
+				resolve = r;
+			}),
+	);
+	const finish = async () => {
+		await act(async () => {
+			resolve?.(detectionResult());
+		});
+	};
+	return { detectBot, finish };
+};
+
+let host: HTMLDivElement;
+let container: HTMLDivElement;
+let root: Root;
+
+const mountWrapper = async (
+	detectBot: BotDetectionFunction,
+	overrides: Partial<ProcaptchaClientConfigInput> = {},
+): Promise<void> => {
+	await act(async () => {
+		root.render(
+			createElement(ProcaptchaFrictionless, {
+				config: config(overrides),
+				callbacks: {},
+				restart: vi.fn(),
+				i18n: i18nStub,
+				detectBot,
+				container,
+			}) as ReactElement,
+		);
+	});
+};
+
+const dispatch = async (target: EventTarget): Promise<void> => {
+	await act(async () => {
+		target.dispatchEvent(new CustomEvent(EXECUTE_EVENT));
+	});
+};
+
+beforeEach(() => {
+	mocks.executes.length = 0;
+	host = document.createElement("div");
+	container = document.createElement("div");
+	document.body.append(host, container);
+	act(() => {
+		root = createRoot(host);
+	});
+});
+
+afterEach(() => {
+	act(() => {
+		root.unmount();
+	});
+	host.remove();
+	container.remove();
+	vi.clearAllMocks();
+});
+
+describe("execute() before the inner widget is listening", () => {
+	it("replays a bare execute() once the invisible widget mounts", async () => {
+		const { detectBot, finish } = heldDetection();
+		await mountWrapper(detectBot);
+
+		await dispatch(document);
+		expect(mocks.executes).toEqual([]);
+
+		await finish();
+
+		expect(mocks.executes).toEqual(["container"]);
+	});
+
+	it("replays a targeted execute() in visible mode", async () => {
+		const { detectBot, finish } = heldDetection();
+		await mountWrapper(detectBot, { mode: ModeEnum.visible });
+
+		await dispatch(container);
+		await finish();
+
+		expect(mocks.executes).toEqual(["container"]);
+	});
+
+	it("replays repeated early calls only once", async () => {
+		const { detectBot, finish } = heldDetection();
+		await mountWrapper(detectBot);
+
+		await dispatch(document);
+		await dispatch(document);
+		await finish();
+
+		expect(mocks.executes).toEqual(["container"]);
+	});
+
+	it("does not start the widget when execute() was never called", async () => {
+		const { detectBot, finish } = heldDetection();
+		await mountWrapper(detectBot);
+
+		await finish();
+
+		expect(mocks.executes).toEqual([]);
+	});
+
+	it("leaves an execute() after mount to the widget alone", async () => {
+		const { detectBot, finish } = heldDetection();
+		await mountWrapper(detectBot);
+		await finish();
+
+		await dispatch(document);
+
+		expect(mocks.executes).toEqual(["document"]);
+	});
+
+	it("ignores a bare execute() in visible mode, as the widgets do", async () => {
+		const { detectBot, finish } = heldDetection();
+		await mountWrapper(detectBot, { mode: ModeEnum.visible });
+
+		await dispatch(document);
+		await finish();
+
+		expect(mocks.executes).toEqual([]);
+	});
+});

package/src/tests/frictionlessResultGuard.test.ts

@@ -51,7 +51,12 @@ describe("evaluateFrictionlessResult", () => {
 				captchaType: "pow",
 				error: { message: "Boom", key: "API.SOMETHING" },
 			}),
-		).toEqual({ kind: "error", message: "Boom", key: "API.SOMETHING" });
+		).toEqual({
+			kind: "error",
+			message: "Boom",
+			key: "API.SOMETHING",
+			retryable: true,
+		});
 	});
 
 	it("omits key from the outcome when the server error carries no key", () => {
@@ -78,13 +83,18 @@ describe("evaluateFrictionlessResult", () => {
 				// the wire but is not the object shape the guard reads.
 				error: undefined,
 			}),
-		).toEqual({ kind: "error", message: MISSING_CAPTCHA_TYPE_MESSAGE });
+		).toEqual({
+			kind: "error",
+			message: MISSING_CAPTCHA_TYPE_MESSAGE,
+			retryable: false,
+		});
 	});
 
 	it("halts when both captchaType and error are absent (opaque parse failure)", () => {
 		expect(evaluateFrictionlessResult({})).toEqual({
 			kind: "error",
 			message: MISSING_CAPTCHA_TYPE_MESSAGE,
+			retryable: false,
 		});
 	});
 
@@ -99,6 +109,71 @@ describe("evaluateFrictionlessResult", () => {
 			kind: "error",
 			message: "Server error",
 			key: "API.SERVER_ERROR",
+			retryable: true,
+		});
+	});
+
+	describe("retryable classification", () => {
+		const retryableOf = (key?: string): boolean => {
+			const outcome = evaluateFrictionlessResult({
+				error: { message: "msg", ...(key !== undefined && { key }) },
+			});
+			if (outcome.kind !== "error") throw new Error("expected error outcome");
+			return outcome.retryable;
+		};
+
+		it.each([
+			"API.SITE_KEY_NOT_REGISTERED",
+			"API.INVALID_SITE_KEY",
+			"API.UNAUTHORIZED_ORIGIN_URL",
+			"API.INCORRECT_CAPTCHA_TYPE",
+		])("shows integration fault %s rather than re-rolling", (key: string) => {
+			// Another provider returns the same answer, and the text is what
+			// tells the site owner what to change.
+			expect(retryableOf(key)).toBe(false);
+		});
+
+		it.each([
+			"API.ACCESS_POLICY_BLOCK",
+			"API.ABUSER_BLOCKED",
+			"API.CRAWLER_BLOCKED",
+			"API.DATACENTER_BLOCKED",
+			"API.DISALLOWED_WEBVIEW",
+			"API.MOBILE_BLOCKED",
+			"API.PROXY_BLOCKED",
+			"API.SATELLITE_BLOCKED",
+			"API.TOR_BLOCKED",
+			"API.VPN_BLOCKED",
+			"API.FORBIDDEN",
+			"API.UNAUTHORIZED",
+		])("does not re-roll policy denial %s", (key: string) => {
+			// Every provider shares the decision; retrying would hammer the
+			// fleet on behalf of traffic already refused.
+			expect(retryableOf(key)).toBe(false);
+		});
+
+		it("leaves CAPTCHA.NO_SESSION_FOUND to its own restart timer", () => {
+			expect(retryableOf("CAPTCHA.NO_SESSION_FOUND")).toBe(false);
+		});
+
+		it("re-rolls API.BAD_REQUEST, which is what an unhandled provider throw becomes", () => {
+			// An unhandled throw in a handler serialises to this with a 400, and
+			// the client does not throw on a 400 with a JSON body — so without
+			// re-rolling, one unhealthy provider stranded the user on the first
+			// response while the rest of the fleet was up.
+			expect(retryableOf("API.BAD_REQUEST")).toBe(true);
+		});
+
+		it.each(["API.UNKNOWN", "API.INTERNAL_SERVER_ERROR", "DATABASE.UNKNOWN"])(
+			"re-rolls unrecognised provider fault %s",
+			(key: string) => {
+				expect(retryableOf(key)).toBe(true);
+			},
+		);
+
+		it("does not re-roll an error with no key at all", () => {
+			// Hard blocks arrive as a bare `{ error: "..." }` string with no key.
+			expect(retryableOf(undefined)).toBe(false);
 		});
 	});
 });

package/src/tests/manualStart.test.tsx

@@ -132,8 +132,7 @@ const checkbox = (): HTMLInputElement => {
 	return element;
 };
 
-const spinner = (): Element | null =>
-	host.querySelector('[aria-label="Loading spinner"]');
+const spinner = (): Element | null => host.querySelector('[role="status"]');
 
 const lastMountOf = (widget: InnerWidget) => {
 	const mount = mocks.mounts.filter((m) => m.widget === widget).at(-1);