@chipmobilesdk/rn-ads 0.5.0 → 0.6.0

package/src/testing/index.ts

@@ -1,463 +1,475 @@
-/**
- * Deterministic in-memory ads engine for tests (SC-012).
- *
- * This is a real implementation of the same `AdsEngine` port the AdMob adapter
- * implements, not a parallel mock — so a contract change breaks it at compile
- * time and it cannot drift. Nothing here touches a native module or a network.
- *
- * It exists to make the package's guarantees provable. The recorded call log is
- * what SC-002 asserts against ("zero production identifiers reached the
- * adapter") and what SC-003 asserts against ("zero calls before consent").
- * Callback emission is fully caller-driven, which is what lets a test run the
- * reward-before-dismiss and dismiss-before-reward orderings and demand the same
- * outcome from both (SC-007).
- *
- * Exported from `@chipmobilesdk/rn-ads/testing`, never from the main entrypoint,
- * so test doubles cannot reach a production bundle.
- */
-
-import type { FullScreenFormat, Reward, Unsubscribe } from '../config/types';
-import type { Scheduler } from '../core/timers';
-import type {
-	AdsEngine,
-	ConsentPort,
-	EngineAdEvent,
-	EngineAdHandle,
-	EngineConsentInfo,
-	EngineConsentOptions,
-	EnginePrivacy,
-	EngineRequestOptions,
-} from '../engine/port';
-
-/**
- * A clock a test can move by hand.
- *
- * Retry backoff, app-open expiry, the undecided-state warning, and the
- * ad-originated-return windows are all time-dependent, and all four must be
- * assertable exactly rather than approximately. Advancing a clock makes "two
- * retries, 2s then 4s" a precise assertion; sleeping would make it a flaky one.
- *
- * Callbacks fire in due order, and a callback scheduled *during* an advance is
- * honored within the same advance if its deadline has also passed — matching how
- * real timers behave when work chains.
- */
-export interface TestClock {
-	now(): number;
-	advance(ms: number): void;
-	readonly scheduler: Scheduler;
-	pending(): number;
-}
-
-export function createTestClock(startMs = 1_000_000): TestClock {
-	let current = startMs;
-	let sequence = 0;
-	const timers = new Map<number, { at: number; callback: () => void }>();
-
-	const scheduler: Scheduler = {
-		setTimeout(callback, ms) {
-			sequence += 1;
-			timers.set(sequence, { at: current + ms, callback });
-			return sequence;
-		},
-		clearTimeout(handle) {
-			timers.delete(handle as number);
-		},
-	};
-
-	return {
-		now: () => current,
-		advance(ms) {
-			const target = current + ms;
-			// Loop rather than iterate once: a fired callback may schedule another
-			// timer that is also due before `target`, which is exactly what a retry
-			// chain does.
-			for (;;) {
-				let nextId: number | null = null;
-				let nextAt = Number.POSITIVE_INFINITY;
-				for (const [id, timer] of timers) {
-					if (timer.at <= target && timer.at < nextAt) {
-						nextAt = timer.at;
-						nextId = id;
-					}
-				}
-				if (nextId === null) {
-					break;
-				}
-				const timer = timers.get(nextId)!;
-				timers.delete(nextId);
-				current = timer.at;
-				timer.callback();
-			}
-			current = target;
-		},
-		scheduler,
-		pending: () => timers.size,
-	};
-}
-
-export type FakeConsentCall =
-	| { readonly kind: 'requestInfoUpdate'; readonly options: EngineConsentOptions }
-	| { readonly kind: 'showFormIfRequired' }
-	| { readonly kind: 'showPrivacyOptionsForm' }
-	| { readonly kind: 'getInfo' }
-	| { readonly kind: 'reset' };
-
-/**
- * A privacy options form the test is holding open (0.4.0).
- *
- * Settle it whenever the test chooses, which is what lets `busy`, a second
- * call, a consent update, and `dispose()` all be exercised *while* the form is
- * on screen — in any order, rather than only the one a resolved promise allows.
- */
-export interface HeldPrivacyOptionsForm {
-	/**
-	 * The user closes the form. `info` is what the provider reports afterwards,
-	 * merged over the current information; omit it for a user who changed nothing.
-	 */
-	close(info?: Partial<EngineConsentInfo>): void;
-	/** The form fails while open. */
-	fail(cause?: unknown): void;
-}
-
-export type FakeEngineCall =
-	| { readonly kind: 'initialize'; readonly privacy: EnginePrivacy }
-	| {
-			readonly kind: 'createFullScreen';
-			readonly format: FullScreenFormat;
-			readonly adUnitId: string;
-			readonly handleId: string;
-			/** Per-request privacy as the package sent it (FR-017's personalization half). */
-			readonly request?: EngineRequestOptions;
-	  }
-	| { readonly kind: 'show'; readonly handleId: string }
-	| { readonly kind: 'dispose'; readonly handleId: string };
-
-export interface FakeEngineOptions {
-	/** Simulates an unsupported platform or a missing bridge (FR-025). */
-	readonly available?: boolean;
-	/** Rejects `initialize`, for the failed-initialization path (FR-024). */
-	readonly failInitialize?: unknown;
-	/**
-	 * Withholds the `loaded` callback so a load runs to its timeout. This is how
-	 * FR-032's timeout behavior is tested without waiting on a real network.
-	 */
-	readonly neverCallBack?: boolean;
-	/** Rejects `show`, for the display-failure path (FR-044). */
-	readonly failShow?: unknown;
-	/** Initial consent information. Defaults to the not-required, allowed case. */
-	readonly consentInfo?: Partial<EngineConsentInfo>;
-	/** Drives time for retry, expiry, and the undecided warning. */
-	readonly clock?: TestClock;
-}
-
-const DEFAULT_CONSENT: EngineConsentInfo = {
-	status: 'not_required',
-	canRequestAds: true,
-	isFormAvailable: false,
-	privacyOptions: 'not_required',
-};
-
-export interface FakeAdsEngine extends AdsEngine {
-	/** Every call the package made, in order. */
-	readonly calls: readonly FakeEngineCall[];
-	/** Ad unit ids passed to `createFullScreen`, in order — the SC-002 assertion. */
-	adUnitIds(): readonly string[];
-	/** Handle ids currently alive; non-empty after dispose means a leak. */
-	liveHandles(): readonly string[];
-	/** Emits a provider callback for one handle. The caller controls ordering. */
-	emit(handleId: string, event: EngineAdEvent): void;
-	/** Convenience for the common `loaded` case. */
-	completeLoad(handleId: string): void;
-	/** Emits a reward with a normalized payload. */
-	emitReward(handleId: string, reward?: Reward): void;
-	/** How many listeners are attached; must reach zero after cleanup (SC-008). */
-	listenerCount(): number;
-	/** Drops every recorded call, for tests that assert on a later window only. */
-	reset(): void;
-
-	/** The clock driving this engine's timers. Wire it into `createAds`. */
-	readonly clock: TestClock;
-	/** Moves the clock and fires anything due. */
-	advance(ms: number): void;
-
-	/** Every consent call the package made, in order (FR-113's assertion surface). */
-	readonly consentCalls: readonly FakeConsentCall[];
-	/** Sets what the consent platform will report from now on. */
-	setConsentInfo(info: Partial<EngineConsentInfo>): void;
-	/** Makes `requestInfoUpdate` reject — the flow must yield `error`, never granted. */
-	failConsentRequest(cause?: unknown): void;
-	/** Makes `showFormIfRequired` reject — dismissal is not consent (FR-106). */
-	failConsentForm(cause?: unknown): void;
-
-	/**
-	 * What the privacy options form reports when the user closes it, merged over
-	 * the current information. Unset, the form closes with nothing changed — the
-	 * same as a user who opens it and backs out.
-	 */
-	setPrivacyOptionsFormResult(info: Partial<EngineConsentInfo>): void;
-	/** Makes `showPrivacyOptionsForm` reject — a failure is never consent (FR-106). */
-	failPrivacyOptionsForm(cause?: unknown): void;
-	/** Holds the next privacy options form open until the test settles it. */
-	holdPrivacyOptionsForm(): HeldPrivacyOptionsForm;
-	/** Makes `getInfo` reject, for the case where even the re-read after a failed form fails. */
-	failConsentInfoRead(cause?: unknown): void;
-}
-
-export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEngine {
-	const calls: FakeEngineCall[] = [];
-	const consentCalls: FakeConsentCall[] = [];
-	const clock = options.clock ?? createTestClock();
-	let consentInfo: EngineConsentInfo = { ...DEFAULT_CONSENT, ...options.consentInfo };
-	let consentRequestFailure: unknown;
-	let consentFormFailure: unknown;
-	let privacyFormFailure: unknown;
-	let privacyFormResult: Partial<EngineConsentInfo> = {};
-	let consentReadFailure: unknown;
-	/** Set by `holdPrivacyOptionsForm`; consumed by the next form. */
-	let heldForm: Promise<Partial<EngineConsentInfo>> | null = null;
-
-	const consent: ConsentPort = {
-		async requestInfoUpdate(consentOptions) {
-			consentCalls.push({ kind: 'requestInfoUpdate', options: consentOptions });
-			if (consentRequestFailure !== undefined) {
-				throw consentRequestFailure;
-			}
-			return consentInfo;
-		},
-		async showFormIfRequired() {
-			consentCalls.push({ kind: 'showFormIfRequired' });
-			if (consentFormFailure !== undefined) {
-				throw consentFormFailure;
-			}
-			// A presented form that the user completes moves the status on. The
-			// fake only does this when a form was actually required, mirroring the
-			// provider: showing nothing cannot change an answer.
-			// A region that required a form is one that requires a way back into
-			// it, which is what the provider reports once consent is obtained.
-			if (consentInfo.status === 'required' && consentInfo.isFormAvailable) {
-				consentInfo = {
-					status: 'obtained',
-					canRequestAds: true,
-					isFormAvailable: false,
-					privacyOptions: 'required',
-				};
-			}
-			return consentInfo;
-		},
-		async showPrivacyOptionsForm() {
-			consentCalls.push({ kind: 'showPrivacyOptionsForm' });
-			const held = heldForm;
-			heldForm = null;
-			if (held) {
-				// Rejects if the test calls `fail`, which is exactly the provider's
-				// failure path; resolves with what the user left behind otherwise.
-				consentInfo = { ...consentInfo, ...(await held) };
-				return consentInfo;
-			}
-			if (privacyFormFailure !== undefined) {
-				throw privacyFormFailure;
-			}
-			consentInfo = { ...consentInfo, ...privacyFormResult };
-			return consentInfo;
-		},
-		async getInfo() {
-			consentCalls.push({ kind: 'getInfo' });
-			if (consentReadFailure !== undefined) {
-				throw consentReadFailure;
-			}
-			return consentInfo;
-		},
-		reset() {
-			consentCalls.push({ kind: 'reset' });
-			consentInfo = {
-				status: 'unknown',
-				canRequestAds: false,
-				isFormAvailable: true,
-				privacyOptions: 'unknown',
-			};
-		},
-	};
-	const listeners = new Map<string, Set<(event: EngineAdEvent) => void>>();
-	/** Callbacks queued before anyone subscribed; see `subscribe`. */
-	const pending = new Map<string, EngineAdEvent>();
-	const live = new Set<string>();
-	let counter = 0;
-
-	function record(call: FakeEngineCall): void {
-		calls.push(call);
-	}
-
-	return {
-		calls,
-		consentCalls,
-		consent,
-		clock,
-
-		advance(ms) {
-			clock.advance(ms);
-		},
-
-		setConsentInfo(info) {
-			consentInfo = { ...consentInfo, ...info };
-		},
-
-		failConsentRequest(cause = new Error('consent request failed')) {
-			consentRequestFailure = cause;
-		},
-
-		failConsentForm(cause = new Error('consent form failed')) {
-			consentFormFailure = cause;
-		},
-
-		setPrivacyOptionsFormResult(info) {
-			privacyFormResult = info;
-		},
-
-		failPrivacyOptionsForm(cause = new Error('privacy options form failed')) {
-			privacyFormFailure = cause;
-		},
-
-		holdPrivacyOptionsForm() {
-			let settle!: {
-				resolve: (info: Partial<EngineConsentInfo>) => void;
-				reject: (cause: unknown) => void;
-			};
-			const promise = new Promise<Partial<EngineConsentInfo>>((resolve, reject) => {
-				settle = { resolve, reject };
-			});
-			heldForm = promise;
-			return {
-				close(info = {}) {
-					settle.resolve(info);
-				},
-				fail(cause = new Error('privacy options form failed')) {
-					settle.reject(cause);
-				},
-			};
-		},
-
-		failConsentInfoRead(cause = new Error('consent information read failed')) {
-			consentReadFailure = cause;
-		},
-
-		isAvailable() {
-			return options.available !== false;
-		},
-
-		async initialize(privacy) {
-			record({ kind: 'initialize', privacy });
-			if (options.failInitialize !== undefined) {
-				throw options.failInitialize;
-			}
-		},
-
-		async createFullScreen(format, adUnitId, request) {
-			counter += 1;
-			const id = `fake-${counter}`;
-			record({ kind: 'createFullScreen', format, adUnitId, handleId: id, request });
-			live.add(id);
-			// A real provider delivers `loaded` to a listener attached after the
-			// ad object exists, so the callback is queued here and flushed when
-			// the caller subscribes. Emitting eagerly would race the caller's own
-			// subscribe and the event would be dropped — which is a property of
-			// this fake, not of the package, and would make the load look hung.
-			if (!options.neverCallBack) {
-				pending.set(id, { type: 'loaded' });
-			}
-			return { id } satisfies EngineAdHandle;
-		},
-
-		async show(handle) {
-			record({ kind: 'show', handleId: handle.id });
-			if (options.failShow !== undefined) {
-				throw options.failShow;
-			}
-			if (!options.neverCallBack) {
-				// `show` is called with a listener already attached, so this one
-				// can go out directly on the next microtask.
-				queueMicrotask(() => {
-					for (const listener of Array.from(listeners.get(handle.id) ?? [])) {
-						listener({ type: 'opened' });
-					}
-				});
-			}
-		},
-
-		subscribe(handle, listener): Unsubscribe {
-			let set = listeners.get(handle.id);
-			if (!set) {
-				set = new Set();
-				listeners.set(handle.id, set);
-			}
-			set.add(listener);
-			// Flush whatever the provider would have delivered between creating
-			// the ad and this subscription.
-			const queued = pending.get(handle.id);
-			if (queued) {
-				pending.delete(handle.id);
-				queueMicrotask(() => {
-					for (const target of Array.from(listeners.get(handle.id) ?? [])) {
-						target(queued);
-					}
-				});
-			}
-			let active = true;
-			return () => {
-				if (!active) {
-					return;
-				}
-				active = false;
-				set?.delete(listener);
-				if (set && set.size === 0) {
-					listeners.delete(handle.id);
-				}
-			};
-		},
-
-		dispose(handle) {
-			record({ kind: 'dispose', handleId: handle.id });
-			live.delete(handle.id);
-			listeners.delete(handle.id);
-			pending.delete(handle.id);
-		},
-
-		adUnitIds() {
-			return calls
-				.filter(
-					(call): call is Extract<FakeEngineCall, { kind: 'createFullScreen' }> =>
-						call.kind === 'createFullScreen',
-				)
-				.map(call => call.adUnitId);
-		},
-
-		liveHandles() {
-			return Array.from(live);
-		},
-
-		emit(handleId, event) {
-			for (const listener of Array.from(listeners.get(handleId) ?? [])) {
-				listener(event);
-			}
-		},
-
-		completeLoad(handleId) {
-			this.emit(handleId, { type: 'loaded' });
-		},
-
-		emitReward(handleId, reward = { type: 'coins', amount: 10 }) {
-			this.emit(handleId, { type: 'rewarded', reward });
-		},
-
-		listenerCount() {
-			let total = 0;
-			for (const set of listeners.values()) {
-				total += set.size;
-			}
-			return total;
-		},
-
-		reset() {
-			calls.length = 0;
-		},
-	};
-}
+/**
+ * Deterministic in-memory ads engine for tests (SC-012).
+ *
+ * This is a real implementation of the same `AdsEngine` port the AdMob adapter
+ * implements, not a parallel mock — so a contract change breaks it at compile
+ * time and it cannot drift. Nothing here touches a native module or a network.
+ *
+ * It exists to make the package's guarantees provable. The recorded call log is
+ * what SC-002 asserts against ("zero production identifiers reached the
+ * adapter") and what SC-003 asserts against ("zero calls before consent").
+ * Callback emission is fully caller-driven, which is what lets a test run the
+ * reward-before-dismiss and dismiss-before-reward orderings and demand the same
+ * outcome from both (SC-007).
+ *
+ * Exported from `@chipmobilesdk/rn-ads/testing`, never from the main entrypoint,
+ * so test doubles cannot reach a production bundle.
+ */
+
+import type { FullScreenFormat, Reward, Unsubscribe } from '../config/types';
+import type { Scheduler } from '../core/timers';
+import type {
+	AdsEngine,
+	ConsentPort,
+	EngineAdEvent,
+	EngineAdHandle,
+	EngineConsentInfo,
+	EngineConsentOptions,
+	EnginePrivacy,
+	EngineRequestOptions,
+} from '../engine/port';
+
+/**
+ * A clock a test can move by hand.
+ *
+ * Retry backoff, app-open expiry, the undecided-state warning, and the
+ * ad-originated-return windows are all time-dependent, and all four must be
+ * assertable exactly rather than approximately. Advancing a clock makes "two
+ * retries, 2s then 4s" a precise assertion; sleeping would make it a flaky one.
+ *
+ * Callbacks fire in due order, and a callback scheduled *during* an advance is
+ * honored within the same advance if its deadline has also passed — matching how
+ * real timers behave when work chains.
+ */
+export interface TestClock {
+	now(): number;
+	advance(ms: number): void;
+	readonly scheduler: Scheduler;
+	pending(): number;
+}
+
+export function createTestClock(startMs = 1_000_000): TestClock {
+	let current = startMs;
+	let sequence = 0;
+	const timers = new Map<number, { at: number; callback: () => void }>();
+
+	const scheduler: Scheduler = {
+		setTimeout(callback, ms) {
+			sequence += 1;
+			timers.set(sequence, { at: current + ms, callback });
+			return sequence;
+		},
+		clearTimeout(handle) {
+			timers.delete(handle as number);
+		},
+	};
+
+	return {
+		now: () => current,
+		advance(ms) {
+			const target = current + ms;
+			// Loop rather than iterate once: a fired callback may schedule another
+			// timer that is also due before `target`, which is exactly what a retry
+			// chain does.
+			for (;;) {
+				let nextId: number | null = null;
+				let nextAt = Number.POSITIVE_INFINITY;
+				for (const [id, timer] of timers) {
+					if (timer.at <= target && timer.at < nextAt) {
+						nextAt = timer.at;
+						nextId = id;
+					}
+				}
+				if (nextId === null) {
+					break;
+				}
+				const timer = timers.get(nextId)!;
+				timers.delete(nextId);
+				current = timer.at;
+				timer.callback();
+			}
+			current = target;
+		},
+		scheduler,
+		pending: () => timers.size,
+	};
+}
+
+export type FakeConsentCall =
+	| { readonly kind: 'requestInfoUpdate'; readonly options: EngineConsentOptions }
+	| { readonly kind: 'showFormIfRequired' }
+	| { readonly kind: 'showPrivacyOptionsForm' }
+	| { readonly kind: 'getInfo' }
+	| { readonly kind: 'reset' };
+
+/**
+ * A privacy options form the test is holding open (0.4.0).
+ *
+ * Settle it whenever the test chooses, which is what lets `busy`, a second
+ * call, a consent update, and `dispose()` all be exercised *while* the form is
+ * on screen — in any order, rather than only the one a resolved promise allows.
+ */
+export interface HeldPrivacyOptionsForm {
+	/**
+	 * The user closes the form. `info` is what the provider reports afterwards,
+	 * merged over the current information; omit it for a user who changed nothing.
+	 */
+	close(info?: Partial<EngineConsentInfo>): void;
+	/** The form fails while open. */
+	fail(cause?: unknown): void;
+}
+
+export type FakeEngineCall =
+	| { readonly kind: 'initialize'; readonly privacy: EnginePrivacy }
+	| {
+			readonly kind: 'createFullScreen';
+			readonly format: FullScreenFormat;
+			readonly adUnitId: string;
+			readonly handleId: string;
+			/** Per-request privacy as the package sent it (FR-017's personalization half). */
+			readonly request?: EngineRequestOptions;
+	  }
+	| { readonly kind: 'show'; readonly handleId: string }
+	| { readonly kind: 'dispose'; readonly handleId: string };
+
+export interface FakeEngineOptions {
+	/** Simulates an unsupported platform or a missing bridge (FR-025). */
+	readonly available?: boolean;
+	/** Rejects `initialize`, for the failed-initialization path (FR-024). */
+	readonly failInitialize?: unknown;
+	/**
+	 * Withholds the `loaded` callback so a load runs to its timeout. This is how
+	 * FR-032's timeout behavior is tested without waiting on a real network.
+	 */
+	readonly neverCallBack?: boolean;
+	/** Rejects `show`, for the display-failure path (FR-044). */
+	readonly failShow?: unknown;
+	/** Initial consent information. Defaults to the not-required, allowed case. */
+	readonly consentInfo?: Partial<EngineConsentInfo>;
+	/** Drives time for retry, expiry, and the undecided warning. */
+	readonly clock?: TestClock;
+}
+
+const DEFAULT_CONSENT: EngineConsentInfo = {
+	status: 'not_required',
+	canRequestAds: true,
+	isFormAvailable: false,
+	privacyOptions: 'not_required',
+};
+
+export interface FakeAdsEngine extends AdsEngine {
+	/** Every call the package made, in order. */
+	readonly calls: readonly FakeEngineCall[];
+	/** Ad unit ids passed to `createFullScreen`, in order — the SC-002 assertion. */
+	adUnitIds(): readonly string[];
+	/** Handle ids currently alive; non-empty after dispose means a leak. */
+	liveHandles(): readonly string[];
+	/** Emits a provider callback for one handle. The caller controls ordering. */
+	emit(handleId: string, event: EngineAdEvent): void;
+	/** Convenience for the common `loaded` case. */
+	completeLoad(handleId: string): void;
+	/** Emits a reward with a normalized payload. */
+	emitReward(handleId: string, reward?: Reward): void;
+	/** How many listeners are attached; must reach zero after cleanup (SC-008). */
+	listenerCount(): number;
+	/** Drops every recorded call, for tests that assert on a later window only. */
+	reset(): void;
+
+	/** The clock driving this engine's timers. Wire it into `createAds`. */
+	readonly clock: TestClock;
+	/** Moves the clock and fires anything due. */
+	advance(ms: number): void;
+
+	/** Every consent call the package made, in order (FR-113's assertion surface). */
+	readonly consentCalls: readonly FakeConsentCall[];
+	/** Sets what the consent platform will report from now on. */
+	setConsentInfo(info: Partial<EngineConsentInfo>): void;
+	/** Makes `requestInfoUpdate` reject — the flow must yield `error`, never granted. */
+	failConsentRequest(cause?: unknown): void;
+	/** Makes `showFormIfRequired` reject — dismissal is not consent (FR-106). */
+	failConsentForm(cause?: unknown): void;
+
+	/**
+	 * What the privacy options form reports when the user closes it, merged over
+	 * the current information. Unset, the form closes with nothing changed — the
+	 * same as a user who opens it and backs out.
+	 */
+	setPrivacyOptionsFormResult(info: Partial<EngineConsentInfo>): void;
+	/** Makes `showPrivacyOptionsForm` reject — a failure is never consent (FR-106). */
+	failPrivacyOptionsForm(cause?: unknown): void;
+	/** Holds the next privacy options form open until the test settles it. */
+	holdPrivacyOptionsForm(): HeldPrivacyOptionsForm;
+	/** Makes `getInfo` reject, for the case where even the re-read after a failed form fails. */
+	failConsentInfoRead(cause?: unknown): void;
+}
+
+/**
+ * Runs `task` on the next microtask, which is when a provider's callbacks would
+ * arrive. Written out because React Native's type declarations omit
+ * `queueMicrotask`, although Hermes has it.
+ */
+function nextMicrotask(task: () => void): void {
+	Promise.resolve().then(task);
+}
+
+export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEngine {
+	const calls: FakeEngineCall[] = [];
+	const consentCalls: FakeConsentCall[] = [];
+	const clock = options.clock ?? createTestClock();
+	let consentInfo: EngineConsentInfo = { ...DEFAULT_CONSENT, ...options.consentInfo };
+	let consentRequestFailure: unknown;
+	let consentFormFailure: unknown;
+	let privacyFormFailure: unknown;
+	let privacyFormResult: Partial<EngineConsentInfo> = {};
+	let consentReadFailure: unknown;
+	/** Set by `holdPrivacyOptionsForm`; consumed by the next form. */
+	let heldForm: Promise<Partial<EngineConsentInfo>> | null = null;
+
+	const consent: ConsentPort = {
+		async requestInfoUpdate(consentOptions) {
+			consentCalls.push({ kind: 'requestInfoUpdate', options: consentOptions });
+			if (consentRequestFailure !== undefined) {
+				throw consentRequestFailure;
+			}
+			return consentInfo;
+		},
+		async showFormIfRequired() {
+			consentCalls.push({ kind: 'showFormIfRequired' });
+			if (consentFormFailure !== undefined) {
+				throw consentFormFailure;
+			}
+			// A presented form that the user completes moves the status on. The
+			// fake only does this when a form was actually required, mirroring the
+			// provider: showing nothing cannot change an answer.
+			// A region that required a form is one that requires a way back into
+			// it, which is what the provider reports once consent is obtained.
+			if (consentInfo.status === 'required' && consentInfo.isFormAvailable) {
+				consentInfo = {
+					status: 'obtained',
+					canRequestAds: true,
+					isFormAvailable: false,
+					privacyOptions: 'required',
+				};
+			}
+			return consentInfo;
+		},
+		async showPrivacyOptionsForm() {
+			consentCalls.push({ kind: 'showPrivacyOptionsForm' });
+			const held = heldForm;
+			heldForm = null;
+			if (held) {
+				// Rejects if the test calls `fail`, which is exactly the provider's
+				// failure path; resolves with what the user left behind otherwise.
+				consentInfo = { ...consentInfo, ...(await held) };
+				return consentInfo;
+			}
+			if (privacyFormFailure !== undefined) {
+				throw privacyFormFailure;
+			}
+			consentInfo = { ...consentInfo, ...privacyFormResult };
+			return consentInfo;
+		},
+		async getInfo() {
+			consentCalls.push({ kind: 'getInfo' });
+			if (consentReadFailure !== undefined) {
+				throw consentReadFailure;
+			}
+			return consentInfo;
+		},
+		reset() {
+			consentCalls.push({ kind: 'reset' });
+			consentInfo = {
+				status: 'unknown',
+				canRequestAds: false,
+				isFormAvailable: true,
+				privacyOptions: 'unknown',
+			};
+		},
+	};
+	const listeners = new Map<string, Set<(event: EngineAdEvent) => void>>();
+	/** Callbacks queued before anyone subscribed; see `subscribe`. */
+	const pending = new Map<string, EngineAdEvent>();
+	const live = new Set<string>();
+	let counter = 0;
+
+	function record(call: FakeEngineCall): void {
+		calls.push(call);
+	}
+
+	return {
+		calls,
+		consentCalls,
+		consent,
+		clock,
+
+		advance(ms) {
+			clock.advance(ms);
+		},
+
+		setConsentInfo(info) {
+			consentInfo = { ...consentInfo, ...info };
+		},
+
+		failConsentRequest(cause = new Error('consent request failed')) {
+			consentRequestFailure = cause;
+		},
+
+		failConsentForm(cause = new Error('consent form failed')) {
+			consentFormFailure = cause;
+		},
+
+		setPrivacyOptionsFormResult(info) {
+			privacyFormResult = info;
+		},
+
+		failPrivacyOptionsForm(cause = new Error('privacy options form failed')) {
+			privacyFormFailure = cause;
+		},
+
+		holdPrivacyOptionsForm() {
+			let settle!: {
+				resolve: (info: Partial<EngineConsentInfo>) => void;
+				reject: (cause: unknown) => void;
+			};
+			const promise = new Promise<Partial<EngineConsentInfo>>((resolve, reject) => {
+				settle = { resolve, reject };
+			});
+			heldForm = promise;
+			return {
+				close(info = {}) {
+					settle.resolve(info);
+				},
+				fail(cause = new Error('privacy options form failed')) {
+					settle.reject(cause);
+				},
+			};
+		},
+
+		failConsentInfoRead(cause = new Error('consent information read failed')) {
+			consentReadFailure = cause;
+		},
+
+		isAvailable() {
+			return options.available !== false;
+		},
+
+		async initialize(privacy) {
+			record({ kind: 'initialize', privacy });
+			if (options.failInitialize !== undefined) {
+				throw options.failInitialize;
+			}
+		},
+
+		async createFullScreen(format, adUnitId, request) {
+			counter += 1;
+			const id = `fake-${counter}`;
+			record({ kind: 'createFullScreen', format, adUnitId, handleId: id, request });
+			live.add(id);
+			// A real provider delivers `loaded` to a listener attached after the
+			// ad object exists, so the callback is queued here and flushed when
+			// the caller subscribes. Emitting eagerly would race the caller's own
+			// subscribe and the event would be dropped — which is a property of
+			// this fake, not of the package, and would make the load look hung.
+			if (!options.neverCallBack) {
+				pending.set(id, { type: 'loaded' });
+			}
+			return { id } satisfies EngineAdHandle;
+		},
+
+		async show(handle) {
+			record({ kind: 'show', handleId: handle.id });
+			if (options.failShow !== undefined) {
+				throw options.failShow;
+			}
+			if (!options.neverCallBack) {
+				// `show` is called with a listener already attached, so this one
+				// can go out directly on the next microtask.
+				nextMicrotask(() => {
+					for (const listener of Array.from(listeners.get(handle.id) ?? [])) {
+						listener({ type: 'opened' });
+					}
+				});
+			}
+		},
+
+		subscribe(handle, listener): Unsubscribe {
+			let set = listeners.get(handle.id);
+			if (!set) {
+				set = new Set();
+				listeners.set(handle.id, set);
+			}
+			set.add(listener);
+			// Flush whatever the provider would have delivered between creating
+			// the ad and this subscription.
+			const queued = pending.get(handle.id);
+			if (queued) {
+				pending.delete(handle.id);
+				nextMicrotask(() => {
+					for (const target of Array.from(listeners.get(handle.id) ?? [])) {
+						target(queued);
+					}
+				});
+			}
+			let active = true;
+			return () => {
+				if (!active) {
+					return;
+				}
+				active = false;
+				set?.delete(listener);
+				if (set && set.size === 0) {
+					listeners.delete(handle.id);
+				}
+			};
+		},
+
+		dispose(handle) {
+			record({ kind: 'dispose', handleId: handle.id });
+			live.delete(handle.id);
+			listeners.delete(handle.id);
+			pending.delete(handle.id);
+		},
+
+		adUnitIds() {
+			return calls
+				.filter(
+					(call): call is Extract<FakeEngineCall, { kind: 'createFullScreen' }> =>
+						call.kind === 'createFullScreen',
+				)
+				.map(call => call.adUnitId);
+		},
+
+		liveHandles() {
+			return Array.from(live);
+		},
+
+		emit(handleId, event) {
+			for (const listener of Array.from(listeners.get(handleId) ?? [])) {
+				listener(event);
+			}
+		},
+
+		completeLoad(handleId) {
+			this.emit(handleId, { type: 'loaded' });
+		},
+
+		emitReward(handleId, reward = { type: 'coins', amount: 10 }) {
+			this.emit(handleId, { type: 'rewarded', reward });
+		},
+
+		listenerCount() {
+			let total = 0;
+			for (const set of listeners.values()) {
+				total += set.size;
+			}
+			return total;
+		},
+
+		reset() {
+			calls.length = 0;
+		},
+	};
+}
+
+export { adsEngineChecks, runAdsEngineConformance } from './conformance';
+export type { AdsEngineHarness, AdsEngineSubject } from './conformance';