@prosopo/procaptcha-puzzle 2.10.40 → 2.10.42

package/src/tests/managerHarness.ts

@@ -0,0 +1,169 @@
+// 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 {
+	Account,
+	FrictionlessState,
+	GetPuzzleCaptchaResponse,
+	MouseMovementPoint,
+	ProcaptchaCallbacks,
+	ProcaptchaClientConfigInput,
+	ProcaptchaState,
+	PuzzleCaptchaSolutionResponse,
+	PuzzleEvent,
+	RandomProvider,
+} from "@prosopo/types";
+import { vi } from "vitest";
+
+/**
+ * Shared fixtures for the puzzle suites. Kept out of the test files so the mock
+ * factories, which vitest hoists above every import, can build their canned
+ * responses from the same shapes the assertions use.
+ */
+
+export const PROVIDER_URL = "https://provider.one";
+export const OTHER_PROVIDER_URL = "https://provider.two";
+export const USER_ADDRESS = "user-address";
+export const SITE_KEY = "site-key";
+
+export const config = (
+	overrides: Partial<ProcaptchaClientConfigInput> = {},
+): ProcaptchaClientConfigInput => ({
+	account: { address: SITE_KEY },
+	defaultEnvironment: "production",
+	...overrides,
+});
+
+export const state = (
+	overrides: Partial<ProcaptchaState> = {},
+): ProcaptchaState => ({
+	isHuman: false,
+	index: 0,
+	solutions: [],
+	captchaApi: undefined,
+	challenge: undefined,
+	showModal: false,
+	loading: false,
+	account: undefined,
+	dappAccount: undefined,
+	submission: undefined,
+	timeout: undefined,
+	successfullChallengeTimeout: undefined,
+	sendData: false,
+	attemptCount: 0,
+	error: undefined,
+	sessionId: undefined,
+	...overrides,
+});
+
+export type SignRaw = NonNullable<
+	NonNullable<Account["extension"]>["signer"]["signRaw"]
+>;
+
+/**
+ * An account carrying just enough of an injected extension to sign: the rest of
+ * the interface is never touched by the manager, but the type demands it.
+ */
+export const account = (signRaw?: SignRaw): Account => ({
+	account: { address: USER_ADDRESS },
+	extension: {
+		name: "test-extension",
+		version: "0.0.0",
+		accounts: {
+			get: async () => [{ address: USER_ADDRESS }],
+			subscribe: () => () => undefined,
+		},
+		signer: signRaw ? { signRaw } : {},
+	},
+});
+
+export const accountWithoutExtension = (): Account => ({
+	account: { address: USER_ADDRESS },
+});
+
+export const randomProvider = (url: string = PROVIDER_URL): RandomProvider => ({
+	providerAccount: "provider-account",
+	provider: { url },
+});
+
+export const challengeResponse = (
+	overrides: Partial<GetPuzzleCaptchaResponse> = {},
+): GetPuzzleCaptchaResponse => ({
+	challenge: "0x1___0xdeadbeef___1700000000000",
+	targetX: 200,
+	targetY: 80,
+	originX: 20,
+	originY: 100,
+	tolerance: 10,
+	timestamp: "1700000000000",
+	signature: { provider: { challenge: "0xprovider-challenge" } },
+	status: "ok",
+	...overrides,
+});
+
+export const solutionResponse = (
+	overrides: Partial<PuzzleCaptchaSolutionResponse> = {},
+): PuzzleCaptchaSolutionResponse => ({
+	verified: true,
+	status: "ok",
+	...overrides,
+});
+
+export const puzzleEvents = (): PuzzleEvent[] => [
+	{ x: 20, y: 100, t: 0 },
+	{ x: 120, y: 90, t: 120 },
+	{ x: 200, y: 80, t: 260 },
+];
+
+export const callbacks = (
+	overrides: Partial<ProcaptchaCallbacks> = {},
+): ProcaptchaCallbacks => ({ ...overrides });
+
+/**
+ * The signer every fixture account uses, so a test can assert on what the
+ * manager asked the extension to sign without rebuilding the frictionless
+ * state it was handed.
+ */
+export const signRawMock = vi.fn<SignRaw>();
+
+export const frictionless = (
+	overrides: Partial<FrictionlessState> = {},
+): FrictionlessState => ({
+	provider: randomProvider(),
+	userAccount: account(signRawMock),
+	restart: () => undefined,
+	...overrides,
+});
+
+/**
+ * A behaviour collector holding a fixed set of points. The manager only ever
+ * calls `getData`, but the type demands the whole lifecycle, so the rest are
+ * stubs rather than omissions.
+ */
+export const collector = (
+	points: MouseMovementPoint[],
+): NonNullable<FrictionlessState["behaviorCollector1"]> => ({
+	start: () => undefined,
+	stop: () => undefined,
+	getData: () => points,
+	clear: () => undefined,
+});
+
+/**
+ * jsdom's setTimeout hands back a plain number while the shared state types the
+ * handle as Node's Timeout, so tests that seed a pending timer have to bridge
+ * the two. The value the manager passes to clearTimeout is the number itself.
+ */
+export const timerHandle = (id: number): ReturnType<typeof setTimeout> =>
+	id as unknown as ReturnType<typeof setTimeout>;

package/src/tests/procaptchaPuzzle.test-d.ts

@@ -0,0 +1,191 @@
+// 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 {
+	FrictionlessState,
+	GetPuzzleCaptchaResponse,
+	ProcaptchaCallbacks,
+	ProcaptchaClientConfigInput,
+	ProcaptchaProps,
+	ProcaptchaState,
+	ProcaptchaStateUpdateFn,
+	PuzzleEvent,
+} from "@prosopo/types";
+import type { ReactElement } from "react";
+import { assertType, describe, expectTypeOf, test } from "vitest";
+import { PuzzleCanvas } from "../components/PuzzleCanvas.js";
+import type * as entrypoint from "../index.js";
+import { ProcaptchaPuzzle } from "../index.js";
+import { Manager } from "../services/Manager.js";
+import {
+	challengeResponse,
+	config,
+	frictionless,
+	puzzleEvents,
+	state,
+} from "./managerHarness.js";
+
+/** The widget only ever reads `language`/`changeLanguage` off this. */
+const i18n = (): Ti18n => undefined as unknown as Ti18n;
+
+describe("the package entrypoint's types", () => {
+	test("ProcaptchaPuzzle takes the shared widget props and renders an element", () => {
+		expectTypeOf(ProcaptchaPuzzle).parameters.toEqualTypeOf<
+			[ProcaptchaProps]
+		>();
+		expectTypeOf(ProcaptchaPuzzle).returns.toExtend<ReactElement>();
+	});
+
+	test("the inner widget's default export is not re-exported", () => {
+		// `export *` skips default exports, so consumers can only reach the lazy
+		// wrapper — the one that works without a code-splitting bundler.
+		expectTypeOf<keyof typeof entrypoint>().toEqualTypeOf<"ProcaptchaPuzzle">();
+	});
+
+	test("config, callbacks and i18n are all required", () => {
+		// @ts-expect-error - a widget with no config has no provider to talk to.
+		assertType<ProcaptchaProps>({ callbacks: {}, i18n: i18n() });
+		// @ts-expect-error - callbacks decide what a solve reports back.
+		assertType<ProcaptchaProps>({ config: config(), i18n: i18n() });
+		assertType<ProcaptchaProps>({
+			config: config(),
+			callbacks: {},
+			i18n: i18n(),
+		});
+	});
+});
+
+describe("Manager's types", () => {
+	const updateState: ProcaptchaStateUpdateFn = () => undefined;
+	const callbacks: ProcaptchaCallbacks = {};
+
+	test("only the first four arguments are required", () => {
+		assertType<ReturnType<typeof Manager>>(
+			Manager(config(), state(), updateState, callbacks),
+		);
+		// @ts-expect-error - callbacks decide what a solve reports back.
+		Manager(config(), state(), updateState);
+	});
+
+	test("the optional arguments keep their positions", () => {
+		expectTypeOf(Manager)
+			.parameter(4)
+			.toEqualTypeOf<FrictionlessState | undefined>();
+		expectTypeOf(Manager)
+			.parameter(5)
+			.toEqualTypeOf<(() => string | undefined) | undefined>();
+	});
+
+	test("it exposes exactly start, submitSolution and resetState", () => {
+		expectTypeOf<keyof ReturnType<typeof Manager>>().toEqualTypeOf<
+			"start" | "submitSolution" | "resetState"
+		>();
+	});
+
+	test("start hands back the challenge the canvas needs to draw", () => {
+		// Unlike the POW manager, which reports only through state, the puzzle
+		// manager returns the challenge — the widget cannot render a board
+		// without the origin/target coordinates.
+		expectTypeOf<ReturnType<typeof Manager>["start"]>().toEqualTypeOf<
+			(x?: number, y?: number) => Promise<GetPuzzleCaptchaResponse | undefined>
+		>();
+	});
+
+	test("submitSolution takes the drop point and the full event trail", () => {
+		expectTypeOf<
+			Parameters<ReturnType<typeof Manager>["submitSolution"]>
+		>().toEqualTypeOf<
+			[finalX: number, finalY: number, events: PuzzleEvent[]]
+		>();
+		expectTypeOf<
+			ReturnType<ReturnType<typeof Manager>["submitSolution"]>
+		>().toEqualTypeOf<Promise<boolean>>();
+	});
+
+	test("resetState takes the frictionless restart callback and nothing else", () => {
+		expectTypeOf<
+			Parameters<ReturnType<typeof Manager>["resetState"]>
+		>().toEqualTypeOf<[frictionlessRestart?: (() => void) | undefined]>();
+		expectTypeOf<
+			ReturnType<ReturnType<typeof Manager>["resetState"]>
+		>().toEqualTypeOf<void>();
+	});
+
+	test("coordinates come off DOM events, so they are numbers", () => {
+		const manager: ReturnType<typeof Manager> = Manager(
+			config(),
+			state(),
+			updateState,
+			callbacks,
+			frictionless(),
+		);
+		// @ts-expect-error - never strings, whatever the DOM stringifies to.
+		manager.start("1", "2");
+		// @ts-expect-error - the trail is required; an empty drag still sends [].
+		manager.submitSolution(1, 2);
+	});
+});
+
+describe("PuzzleCanvas' types", () => {
+	const onComplete = (
+		_finalX: number,
+		_finalY: number,
+		_events: PuzzleEvent[],
+	): void => undefined;
+
+	test("every prop is required, since none has a sensible default", () => {
+		// @ts-expect-error - a board with no target cannot be solved.
+		PuzzleCanvas({ originX: 0, originY: 0 });
+		// @ts-expect-error - `submitting` gates the drag; omitting it unlocks it.
+		PuzzleCanvas({
+			originX: 0,
+			originY: 0,
+			targetX: 1,
+			targetY: 1,
+			onComplete,
+			showRetry: false,
+		});
+	});
+
+	test("the full prop set renders an element", () => {
+		expectTypeOf(
+			PuzzleCanvas({
+				originX: 0,
+				originY: 0,
+				targetX: 1,
+				targetY: 1,
+				onComplete,
+				showRetry: false,
+				submitting: false,
+			}),
+		).toExtend<ReactElement>();
+	});
+
+	test("the drop is reported synchronously, not as a promise", () => {
+		// The widget's own handler is async, but the canvas must not await it:
+		// a returned promise here would be dropped on the floor.
+		expectTypeOf(onComplete).returns.toEqualTypeOf<void>();
+	});
+});
+
+describe("the harness fixtures match the shared types", () => {
+	test("they build the real shapes, not lookalikes", () => {
+		expectTypeOf(config()).toEqualTypeOf<ProcaptchaClientConfigInput>();
+		expectTypeOf(state()).toEqualTypeOf<ProcaptchaState>();
+		expectTypeOf(frictionless()).toEqualTypeOf<FrictionlessState>();
+		expectTypeOf(challengeResponse()).toEqualTypeOf<GetPuzzleCaptchaResponse>();
+		expectTypeOf(puzzleEvents()).toEqualTypeOf<PuzzleEvent[]>();
+	});
+});

package/src/tests/procaptchaPuzzle.unit.test.ts

@@ -0,0 +1,123 @@
+// 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 { ProcaptchaProps } from "@prosopo/types";
+import { type ReactElement, act, createElement } from "react";
+import { type Root, createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import * as entrypoint from "../index.js";
+import { config } from "./managerHarness.js";
+
+/**
+ * The outer component exists only to lazy-load the widget and hand it the props
+ * it was given, so what is worth pinning down is that nothing is dropped on the
+ * way through — a wrapper that names props one at a time silently loses the
+ * ones added later.
+ */
+const mocks = vi.hoisted(() => ({
+	received: [] as ProcaptchaProps[],
+}));
+
+vi.mock("../components/ProcaptchaWidget.js", async () => {
+	const { createElement: create } = await import("react");
+	return {
+		default: (props: ProcaptchaProps) => {
+			mocks.received.push(props);
+			return create("div", { "data-testid": "widget" });
+		},
+	};
+});
+
+let container: HTMLDivElement;
+let root: Root;
+
+const props = (overrides: Partial<ProcaptchaProps> = {}): ProcaptchaProps => ({
+	config: config(),
+	callbacks: {},
+	i18n: undefined as unknown as Ti18n,
+	...overrides,
+});
+
+const render = async (widgetProps: ProcaptchaProps): Promise<void> => {
+	await act(async () => {
+		root.render(
+			createElement(entrypoint.ProcaptchaPuzzle, widgetProps) as ReactElement,
+		);
+	});
+};
+
+beforeEach(() => {
+	mocks.received.length = 0;
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	act(() => {
+		root = createRoot(container);
+	});
+});
+
+afterEach(() => {
+	act(() => {
+		root.unmount();
+	});
+	container.remove();
+});
+
+describe("ProcaptchaPuzzle", () => {
+	test("renders the widget once it has loaded", async () => {
+		await render(props());
+		expect(container.querySelector('[data-testid="widget"]')).not.toBeNull();
+	});
+
+	test("passes on the props the widget needs but never names", async () => {
+		const onSessionInvalidated = vi.fn<(x?: number, y?: number) => void>();
+		await render(
+			props({
+				autoStart: true,
+				startCoords: { x: 1, y: 2 },
+				onSessionInvalidated,
+			}),
+		);
+		expect(mocks.received[0]).toMatchObject({
+			autoStart: true,
+			startCoords: { x: 1, y: 2 },
+			onSessionInvalidated,
+		});
+	});
+
+	test("passes on the props it does name, too", async () => {
+		const callbacks = { onHuman: vi.fn<(token: string) => void>() };
+		await render(props({ callbacks }));
+		expect(mocks.received[0]?.callbacks).toBe(callbacks);
+		expect(mocks.received[0]?.config).toEqual(config());
+	});
+
+	test("mounts one widget per render, not one per prop change", async () => {
+		await render(props());
+		await render(props({ autoStart: true }));
+		expect(container.querySelectorAll('[data-testid="widget"]')).toHaveLength(
+			1,
+		);
+	});
+});
+
+describe("the package entrypoint", () => {
+	test("exports the wrapper a consumer mounts", () => {
+		// The inner ProcaptchaWidget is a default export, which `export *` does
+		// not re-export: consumers get the lazy-loading wrapper only, which is
+		// the one that works outside a bundler that can code-split.
+		expect(typeof entrypoint.ProcaptchaPuzzle).toBe("function");
+		expect(Object.keys(entrypoint)).toEqual(["ProcaptchaPuzzle"]);
+	});
+});