@chipmobilesdk/rn-notification 0.1.0

package/src/testing/fake-engine.ts

@@ -0,0 +1,284 @@
+/**
+ * In-memory engine for tests.
+ *
+ * Exists so every decision path is provable with no device, no emulator, and
+ * no live provider. Its controls simulate the conditions that are otherwise
+ * only reachable on hardware: virtual time, time-zone travel, permission
+ * transitions, process death, boot-restoration gaps, and platform truncation.
+ */
+
+import type {
+	NotificationEngineAdapter,
+	EngineCapabilities,
+	EngineScheduleRequest,
+} from '../engine/adapter';
+import type { PendingEntry } from '../contract/notification';
+import type { PermissionKind, PermissionState, RestrictionReport } from '../contract/permission';
+import type { ResolvedTone, ChannelGroup } from '../contract/channel';
+import type { InteractionEvent, Unsubscribe } from '../contract/interaction';
+
+export interface FakeEngineOptions {
+	readonly pendingCeiling?: number;
+	readonly supportsExactAlarms?: boolean;
+	readonly supportsDoNotDisturbBypass?: boolean;
+	readonly backgroundWindowMs?: number;
+	readonly initialPermissions?: Partial<Record<PermissionKind, PermissionState>>;
+	readonly timeZone?: string;
+	readonly now?: number;
+}
+
+/** Every platform operation the engine was asked to perform, in order. */
+export interface RecordedOperation {
+	readonly kind: 'schedule' | 'cancel' | 'cancelAll' | 'declareTone' | 'retireTone';
+	readonly id?: string;
+	readonly at: number;
+}
+
+export interface FakeControls {
+	/** Operations recorded since the last reset. The idempotence assertion reads this. */
+	readonly operations: readonly RecordedOperation[];
+	clearOperations(): void;
+
+	/** Virtual clock, so tests never sleep. */
+	now(): number;
+	advanceTime(ms: number): void;
+	setTime(epochMs: number): void;
+
+	/** Simulates the user travelling. */
+	timeZone(): string;
+	setTimeZone(zone: string): void;
+
+	setPermission(kind: PermissionKind, state: PermissionState): void;
+	setRestrictions(report: Partial<RestrictionReport>): void;
+
+	/**
+	 * Drops entries the platform would have silently discarded past its ceiling,
+	 * so truncation behavior is testable without an iOS device.
+	 */
+	applyPlatformCeiling(): readonly string[];
+
+	/**
+	 * Simulates the process dying: in-memory listeners are lost while scheduled
+	 * notifications survive, which is exactly what happens on a real device.
+	 */
+	simulateProcessDeath(): void;
+
+	/** Simulates a manufacturer losing notifications across a reboot. */
+	simulateBootGap(ids: readonly string[]): void;
+
+	/** Queues an interaction that arrived before any handler existed. */
+	emitInteraction(event: InteractionEvent): void;
+	queueInitialInteraction(event: InteractionEvent): void;
+}
+
+export type FakeEngine = NotificationEngineAdapter & FakeControls;
+
+export function createFakeEngine(options: FakeEngineOptions = {}): FakeEngine {
+	const scheduled = new Map<string, PendingEntry>();
+	const channels = new Set<string>();
+	let operations: RecordedOperation[] = [];
+	let listeners: ((event: InteractionEvent) => void)[] = [];
+	let initialInteraction: InteractionEvent | undefined;
+
+	let currentTime = options.now ?? Date.UTC(2026, 0, 1, 12, 0, 0);
+	let currentZone = options.timeZone ?? 'UTC';
+
+	const permissions: Record<PermissionKind, PermissionState> = {
+		display: options.initialPermissions?.display ?? 'notAsked',
+		exactAlarm: options.initialPermissions?.exactAlarm ?? 'notAsked',
+	};
+
+	let restrictions: RestrictionReport = {
+		batteryOptimization: 'unrestricted',
+		autoStart: 'unrestricted',
+		readAt: currentTime,
+	};
+
+	const capabilities: EngineCapabilities = {
+		pendingCeiling: options.pendingCeiling ?? 64,
+		supportsExactAlarms: options.supportsExactAlarms ?? true,
+		supportsChannels: true,
+		supportsTextInputActions: true,
+		supportsDoNotDisturbBypass: options.supportsDoNotDisturbBypass ?? true,
+		backgroundWindowMs: options.backgroundWindowMs ?? 30_000,
+	};
+
+	const record = (kind: RecordedOperation['kind'], id?: string): void => {
+		operations.push({ kind, id, at: currentTime });
+	};
+
+	const toPendingEntry = (request: EngineScheduleRequest): PendingEntry => ({
+		id: request.request.id,
+		resolvedAt: request.resolvedAt,
+		anchoring: request.request.moment.anchoring ?? 'wallClock',
+		anchoringGeneration:
+			(request.request.moment.anchoring ?? 'wallClock') === 'wallClock' ? currentZone : undefined,
+		content: request.request.content,
+		tone: request.request.tone,
+		routing: request.request.routing,
+		actions: request.request.actions,
+		ownerTag: request.request.ownerTag,
+		groupTag: request.request.groupTag,
+		seriesId: request.seriesId,
+		mayBeDelayed: request.approximate,
+		pushCreated: request.pushCreated ?? false,
+	});
+
+	return {
+		name: 'fake',
+
+		async getCapabilities() {
+			return capabilities;
+		},
+
+		async schedule(request) {
+			record('schedule', request.request.id);
+			scheduled.set(request.request.id, toPendingEntry(request));
+		},
+
+		async cancel(id) {
+			record('cancel', id);
+			scheduled.delete(id);
+		},
+
+		async cancelMany(ids) {
+			for (const id of ids) {
+				record('cancel', id);
+				scheduled.delete(id);
+			}
+		},
+
+		async cancelAll() {
+			record('cancelAll');
+			scheduled.clear();
+		},
+
+		async getPending() {
+			return [...scheduled.values()].sort((a, b) => a.resolvedAt - b.resolvedAt);
+		},
+
+		async declareTone(tone: ResolvedTone) {
+			record('declareTone', tone.android.channelId);
+			if (channels.has(tone.android.channelId)) {
+				// Android silently ignores re-declaration. The fake does too, on purpose.
+				return false;
+			}
+			channels.add(tone.android.channelId);
+			return true;
+		},
+
+		async retireTone(channelId: string) {
+			record('retireTone', channelId);
+			return channels.delete(channelId);
+		},
+
+		async declareGroups(_groups: readonly ChannelGroup[]) {
+			// Groups are presentational; the fake accepts them without recording.
+		},
+
+		async listDeclaredChannels() {
+			return [...channels];
+		},
+
+		async getPermission(kind) {
+			return permissions[kind];
+		},
+
+		async requestPermission(kind) {
+			if (permissions[kind] === 'notAsked') {
+				permissions[kind] = 'granted';
+			}
+			return permissions[kind];
+		},
+
+		async openSettings(_kind) {
+			// No-op: the fake cannot open a settings screen, and pretending it did would be a lie.
+		},
+
+		async getRestrictions() {
+			return { ...restrictions, readAt: currentTime };
+		},
+
+		subscribeToInteractions(handler): Unsubscribe {
+			listeners.push(handler);
+			return () => {
+				listeners = listeners.filter(l => l !== handler);
+			};
+		},
+
+		async takeInitialInteraction() {
+			const event = initialInteraction;
+			initialInteraction = undefined;
+			return event;
+		},
+
+		// --- FakeControls ------------------------------------------------------
+
+		get operations() {
+			return operations;
+		},
+
+		clearOperations() {
+			operations = [];
+		},
+
+		now() {
+			return currentTime;
+		},
+
+		advanceTime(ms) {
+			currentTime += ms;
+		},
+
+		setTime(epochMs) {
+			currentTime = epochMs;
+		},
+
+		timeZone() {
+			return currentZone;
+		},
+
+		setTimeZone(zone) {
+			currentZone = zone;
+		},
+
+		setPermission(kind, state) {
+			permissions[kind] = state;
+		},
+
+		setRestrictions(report) {
+			restrictions = { ...restrictions, ...report };
+		},
+
+		applyPlatformCeiling() {
+			const ordered = [...scheduled.values()].sort((a, b) => a.resolvedAt - b.resolvedAt);
+			const dropped = ordered.slice(capabilities.pendingCeiling);
+			for (const entry of dropped) {
+				scheduled.delete(entry.id);
+			}
+			return dropped.map(entry => entry.id);
+		},
+
+		simulateProcessDeath() {
+			// Scheduled notifications live in the OS and survive; listeners do not.
+			listeners = [];
+			operations = [];
+		},
+
+		simulateBootGap(ids) {
+			for (const id of ids) {
+				scheduled.delete(id);
+			}
+		},
+
+		emitInteraction(event) {
+			for (const listener of listeners) {
+				listener(event);
+			}
+		},
+
+		queueInitialInteraction(event) {
+			initialInteraction = event;
+		},
+	};
+}

package/src/testing/fake-provider.ts

@@ -0,0 +1,129 @@
+/**
+ * In-memory push provider for tests.
+ *
+ * Exists so the entire push surface — token lifecycle, receipt in every app
+ * state, malformed payloads, redelivery, and provider unavailability — is
+ * provable with no live provider and no device.
+ *
+ * It is also the second adapter that proves the swap costs a consumer nothing:
+ * running the full push suite against this instead of the real provider must
+ * pass with zero changes to consuming code.
+ */
+
+import type {
+	PushAvailability,
+	PushProviderAdapter,
+} from '../push/provider-adapter';
+import type { Unsubscribe } from '../contract/interaction';
+
+export interface FakeProviderOptions {
+	readonly name?: string;
+	readonly availability?: PushAvailability;
+	readonly initialToken?: string;
+	/** When true, `getToken` resolves only after `releaseToken()` is called. */
+	readonly withholdToken?: boolean;
+	readonly invalidationSucceeds?: boolean;
+}
+
+export interface FakeProviderControls {
+	/** Delivers a raw payload as the provider would. */
+	deliver(raw: unknown): void;
+	/** Queues the payload that launched the app. */
+	queueInitial(raw: unknown): void;
+	/** Simulates the platform rotating the registration token. */
+	rotateToken(token: string): void;
+	/** Resolves a withheld token, so "waits for availability" is testable. */
+	releaseToken(token: string): void;
+	setAvailability(availability: PushAvailability): void;
+	readonly invalidated: boolean;
+}
+
+export type FakeProvider = PushProviderAdapter & FakeProviderControls;
+
+export function createFakeProvider(options: FakeProviderOptions = {}): FakeProvider {
+	let availability: PushAvailability = options.availability ?? 'available';
+	let token = options.withholdToken === true ? undefined : (options.initialToken ?? 'fake-token-1');
+	let invalidated = false;
+	let messageHandlers: ((raw: unknown) => void)[] = [];
+	let tokenHandlers: ((token: string) => void)[] = [];
+	let initial: unknown | undefined;
+	let waiters: ((token: string) => void)[] = [];
+
+	return {
+		name: options.name ?? 'fake-provider',
+
+		async getAvailability() {
+			return availability;
+		},
+
+		async getToken() {
+			if (token !== undefined) return token;
+			// Waits rather than returning a placeholder — an empty string presented
+			// as a token is worse than not answering yet.
+			return new Promise<string>(resolve => {
+				waiters.push(resolve);
+			});
+		},
+
+		onTokenChange(handler): Unsubscribe {
+			tokenHandlers.push(handler);
+			return () => {
+				tokenHandlers = tokenHandlers.filter(h => h !== handler);
+			};
+		},
+
+		async invalidateToken() {
+			invalidated = true;
+			token = undefined;
+			return options.invalidationSucceeds ?? true;
+		},
+
+		subscribeToMessages(handler): Unsubscribe {
+			messageHandlers.push(handler);
+			return () => {
+				messageHandlers = messageHandlers.filter(h => h !== handler);
+			};
+		},
+
+		async takeInitialMessage() {
+			const raw = initial;
+			initial = undefined;
+			return raw;
+		},
+
+		// --- FakeProviderControls ---------------------------------------------
+
+		deliver(raw) {
+			for (const handler of messageHandlers) {
+				handler(raw);
+			}
+		},
+
+		queueInitial(raw) {
+			initial = raw;
+		},
+
+		rotateToken(next) {
+			token = next;
+			for (const handler of tokenHandlers) {
+				handler(next);
+			}
+		},
+
+		releaseToken(next) {
+			token = next;
+			for (const resolve of waiters) {
+				resolve(next);
+			}
+			waiters = [];
+		},
+
+		setAvailability(next) {
+			availability = next;
+		},
+
+		get invalidated() {
+			return invalidated;
+		},
+	};
+}

package/src/testing/faults.ts

@@ -0,0 +1,72 @@
+/**
+ * Fault injection.
+ *
+ * Every documented failure condition must be reachable on demand, or the claim
+ * that each has its own distinct diagnostic is untestable. This is what the
+ * demo app's fault panel and the conformance suite both drive.
+ */
+
+import { ALL_DIAGNOSTIC_CODES, type DiagnosticCode } from '../contract/errors';
+
+export type FaultKind = DiagnosticCode;
+
+export interface FaultRecord {
+	readonly code: DiagnosticCode;
+	readonly at: number;
+}
+
+export interface Disposable {
+	dispose(): void;
+}
+
+export interface FaultInjectorOptions {
+	readonly now?: () => number;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+/**
+ * Triggers a named condition and records that it fired.
+ *
+ * Deliberately a thin mechanism: it proves each identifier is reachable and
+ * distinct, which is the property under test. Making the *real* condition occur
+ * is each module's own test's job.
+ */
+export function createFaultInjector(options: FaultInjectorOptions = {}) {
+	const now = options.now ?? (() => Date.now());
+	const emit = options.emit ?? (() => {});
+	const fired: FaultRecord[] = [];
+
+	return {
+		/** Every condition a consumer can reach from the fault panel. */
+		available: ALL_DIAGNOSTIC_CODES,
+
+		inject(kind: FaultKind): Disposable {
+			const record: FaultRecord = { code: kind, at: now() };
+			fired.push(record);
+			emit(kind, `Injected fault: ${kind}`, { injected: true });
+
+			return {
+				dispose() {
+					const index = fired.indexOf(record);
+					if (index >= 0) fired.splice(index, 1);
+				},
+			};
+		},
+
+		get fired(): readonly FaultRecord[] {
+			return fired;
+		},
+
+		/** Which documented conditions have not yet been exercised. */
+		unexercised(): readonly DiagnosticCode[] {
+			const seen = new Set(fired.map(record => record.code));
+			return ALL_DIAGNOSTIC_CODES.filter(code => !seen.has(code));
+		},
+
+		reset(): void {
+			fired.length = 0;
+		},
+	};
+}
+
+export type FaultInjector = ReturnType<typeof createFaultInjector>;

package/src/testing/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Test-only surface: `@chipmobilesdk/rn-notification/testing`
+ *
+ * Kept behind its own subpath so fakes and fault injection never reach a
+ * production bundle. Everything here exists so that scheduling, reconciliation,
+ * permission transitions, tone mapping, and interaction routing are provable
+ * with no device, no emulator, and no live provider.
+ */
+
+export { createFakeEngine } from './fake-engine';
+export { createFakeProvider } from './fake-provider';
+export { createFaultInjector } from './faults';
+export { runConformanceSuite } from './conformance';
+export type { ConformanceReport, ConformanceCheck, ConformanceOptions } from './conformance';
+export type { FaultInjector, FaultKind, FaultRecord, Disposable } from './faults';
+export type { FakeProvider, FakeProviderOptions, FakeProviderControls } from './fake-provider';
+export type {
+	FakeEngine,
+	FakeEngineOptions,
+	FakeControls,
+	RecordedOperation,
+} from './fake-engine';
+
+/** In-memory state store, for testing state behavior without a native module. */
+export { createMemoryStore } from '../state/store';
+export type { StateStore } from '../state/store';