@chipmobilesdk/rn-ads 0.1.0

package/src/testing/index.ts

@@ -0,0 +1,206 @@
+/**
+ * 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 {
+	AdsEngine,
+	EngineAdEvent,
+	EngineAdHandle,
+	EnginePrivacy,
+} from '../engine/port';
+
+export type FakeEngineCall =
+	| { readonly kind: 'initialize'; readonly privacy: EnginePrivacy }
+	| {
+			readonly kind: 'createFullScreen';
+			readonly format: FullScreenFormat;
+			readonly adUnitId: string;
+			readonly handleId: string;
+	  }
+	| { 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;
+}
+
+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;
+}
+
+export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEngine {
+	const calls: FakeEngineCall[] = [];
+	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,
+
+		isAvailable() {
+			return options.available !== false;
+		},
+
+		async initialize(privacy) {
+			record({ kind: 'initialize', privacy });
+			if (options.failInitialize !== undefined) {
+				throw options.failInitialize;
+			}
+		},
+
+		async createFullScreen(format, adUnitId) {
+			counter += 1;
+			const id = `fake-${counter}`;
+			record({ kind: 'createFullScreen', format, adUnitId, handleId: id });
+			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;
+		},
+	};
+}