@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/testing/conformance/index.ts

@@ -1,248 +1,258 @@
-/**
- * The shared conformance suite.
- *
- * The executable definition of what an engine adapter must do. Run against the
- * real engine and against the fake, it is what backs the claim that testing
- * with fakes proves something about production — if the two ever diverge, this
- * is where it shows up rather than on a user's device.
- *
- * Written as a plain async function rather than a Jest suite so it can be
- * driven from the demo app on a real device as well as from continuous
- * integration.
- */
-
-import type { NotificationEngineAdapter } from '../../engine/adapter';
-import type { ResolvedTone } from '../../contract/channel';
-
-const TONE: ResolvedTone = {
-	toneId: 'conformance',
-	version: 1,
-	android: {
-		channelId: 'conformance.v1',
-		importance: 'default',
-		vibration: false,
-		badge: false,
-		bypassDnd: false,
-			name: 'Fixture tone',
-			loopSound: false,
-			alarmCategory: false,
-		},
-	ios: { categoryId: 'conformance', interruptionLevel: 'active', badge: false, repeatRefused: false },
-};
-
-export interface ConformanceCheck {
-	readonly name: string;
-	readonly passed: boolean;
-	readonly detail?: string;
-}
-
-export interface ConformanceReport {
-	readonly adapter: string;
-	readonly checks: readonly ConformanceCheck[];
-	readonly passed: number;
-	readonly failed: number;
-}
-
-export interface ConformanceOptions {
-	/** Injected so the suite never depends on wall-clock time. */
-	readonly now?: () => number;
-	/** Identifier prefix, so a device run cannot collide with real notifications. */
-	readonly prefix?: string;
-}
-
-export async function runConformanceSuite(
-	adapter: NotificationEngineAdapter,
-	options: ConformanceOptions = {},
-): Promise<ConformanceReport> {
-	const now = options.now ?? (() => Date.now());
-	const prefix = options.prefix ?? 'conformance';
-	const checks: ConformanceCheck[] = [];
-
-	const check = async (name: string, run: () => Promise<boolean | string>): Promise<void> => {
-		try {
-			const outcome = await run();
-			checks.push(
-				outcome === true
-					? { name, passed: true }
-					: { name, passed: false, detail: typeof outcome === 'string' ? outcome : 'returned false' },
-			);
-		} catch (error) {
-			checks.push({
-				name,
-				passed: false,
-				detail: error instanceof Error ? error.message : String(error),
-			});
-		}
-	};
-
-	const id = (suffix: string) => `${prefix}:${suffix}`;
-	const at = now() + 3_600_000;
-
-	const schedule = (suffix: string, overrides: Record<string, unknown> = {}) =>
-		adapter.schedule({
-			request: {
-				id: id(suffix),
-				content: { title: `Conformance ${suffix}`, body: 'Suite entry' },
-				tone: 'conformance',
-				moment: { at },
-				...overrides,
-			},
-			resolvedAt: at,
-			tone: TONE,
-			approximate: false,
-		});
-
-	// Start clean so a previous run cannot mask a failure.
-	await adapter.cancelAll();
-
-	await check('reports its capabilities', async () => {
-		const capabilities = await adapter.getCapabilities();
-		return (
-			capabilities.pendingCeiling > 0 ||
-			`pendingCeiling must be positive, got ${capabilities.pendingCeiling}`
-		);
-	});
-
-	await check('schedules and reads back an entry', async () => {
-		await schedule('a');
-		const pending = await adapter.getPending();
-		return pending.some(entry => entry.id === id('a')) || 'scheduled entry was not returned';
-	});
-
-	await check('returns enough detail to diff, not merely to count', async () => {
-		const [entry] = (await adapter.getPending()).filter(e => e.id === id('a'));
-		if (entry === undefined) return 'entry missing';
-
-		return (
-			(entry.content.title.length > 0 && entry.resolvedAt > 0 && entry.anchoring !== undefined) ||
-			'entry lacked content, instant, or anchoring mode'
-		);
-	});
-
-	await check('replaces rather than duplicates on the same identifier', async () => {
-		await schedule('a', { content: { title: 'Replaced', body: 'Newer' } });
-		const matching = (await adapter.getPending()).filter(entry => entry.id === id('a'));
-		return matching.length === 1 || `expected exactly 1 entry, found ${matching.length}`;
-	});
-
-	await check('round-trips a routing payload unchanged', async () => {
-		await schedule('routing', { routing: { screen: 'task', nested: { deep: true } } });
-		const entry = (await adapter.getPending()).find(e => e.id === id('routing'));
-		return (
-			JSON.stringify(entry?.routing) === JSON.stringify({ screen: 'task', nested: { deep: true } }) ||
-			`routing payload changed: ${JSON.stringify(entry?.routing)}`
-		);
-	});
-
-	await check('preserves the anchoring mode it was given', async () => {
-		await schedule('absolute', { moment: { at, anchoring: 'absolute' } });
-		const entry = (await adapter.getPending()).find(e => e.id === id('absolute'));
-		return entry?.anchoring === 'absolute' || `expected absolute, got ${entry?.anchoring}`;
-	});
-
-	await check('cancels one entry without touching the others', async () => {
-		const before = (await adapter.getPending()).length;
-		await adapter.cancel(id('a'));
-		const after = await adapter.getPending();
-
-		return (
-			(after.length === before - 1 && !after.some(entry => entry.id === id('a'))) ||
-			'cancel removed the wrong number of entries'
-		);
-	});
-
-	await check('cancelling something absent is harmless', async () => {
-		await adapter.cancel(id('never-existed'));
-		return true;
-	});
-
-	await check('reports permission state without throwing', async () => {
-		const state = await adapter.getPermission('display');
-		return (
-			['notAsked', 'granted', 'denied', 'permanentlyDenied', 'provisional', 'notRequired'].includes(
-				state,
-			) || `unexpected permission state: ${state}`
-		);
-	});
-
-	await check('reports background restrictions, admitting unknown', async () => {
-		const report = await adapter.getRestrictions();
-		return (
-			['unrestricted', 'restricted', 'unknown'].includes(report.batteryOptimization) ||
-			`unexpected restriction status: ${report.batteryOptimization}`
-		);
-	});
-
-	await check('returns pending entries in ascending delivery order', async () => {
-		const pending = await adapter.getPending();
-		const instants = pending.map(entry => entry.resolvedAt);
-		const sorted = [...instants].sort((x, y) => x - y);
-		return JSON.stringify(instants) === JSON.stringify(sorted) || 'entries were not time-ordered';
-	});
-
-	await check('cancelAll leaves nothing behind', async () => {
-		await adapter.cancelAll();
-		const pending = await adapter.getPending();
-		return pending.length === 0 || `${pending.length} entries survived cancelAll`;
-	});
-
-	// --- Repeat expiry -------------------------------------------------------
-	// A substituted engine must be checked on these, not trusted: every one of
-	// them is a way to end up with a device that will not stop ringing, or with
-	// a consumer cancelling an artifact it was never meant to see.
-
-	await check('answers whether it can repeat an alert, rather than guessing', async () => {
-		const capabilities = await adapter.getCapabilities();
-		return (
-			typeof capabilities.supportsRepeatingAlert === 'boolean' ||
-			'supportsRepeatingAlert was not a boolean'
-		);
-	});
-
-	await check('reports a repeating alert it cannot honour', async () => {
-		const capabilities = await adapter.getCapabilities();
-		if (capabilities.supportsRepeatingAlert) return true;
-
-		// A partially emulated repeat is worse than an honest refusal: the
-		// consumer believes the alarm is bounded when nothing bounds it.
-		const repeating: ResolvedTone = {
-			...TONE,
-			android: { ...TONE.android, loopSound: true, repeatForMs: 900_000 },
-			ios: { ...TONE.ios, repeatRefused: true },
-		};
-		return repeating.ios.repeatRefused || 'refusal was not recorded on the resolved tone';
-	});
-
-	await check('keeps stop markers out of the consumer-visible pending set', async () => {
-		const stops = await adapter.listRepeatStops();
-		const pending = await adapter.getPending();
-		const leaked = pending.filter(entry => stops.some(stop => stop.markerId === entry.id));
-		return (
-			leaked.length === 0 ||
-			`${leaked.length} package-owned marker(s) were reported as consumer notifications`
-		);
-	});
-
-	await check('silencing a notification that is gone is an answer, not a failure', async () => {
-		// The ordinary case after the user has handled it. An engine that throws
-		// here turns the commonest path into an error.
-		const silenced = await adapter.silenceDelivered(id('never-displayed'));
-		return silenced === false || 'reported silencing a notification it was not displaying';
-	});
-
-	await check('says whether a background delivery handler is registered', async () => {
-		return (
-			typeof adapter.hasBackgroundDeliveryHandler() === 'boolean' ||
-			'hasBackgroundDeliveryHandler was not a boolean'
-		);
-	});
-
-	const passed = checks.filter(entry => entry.passed).length;
-
-	return {
-		adapter: adapter.name,
-		checks,
-		passed,
-		failed: checks.length - passed,
-	};
-}
+/**
+ * The shared conformance suite.
+ *
+ * The executable definition of what an engine adapter must do. Run against the
+ * real engine and against the fake, it is what backs the claim that testing
+ * with fakes proves something about production — if the two ever diverge, this
+ * is where it shows up rather than on a user's device.
+ *
+ * Written as a plain async function rather than a Jest suite so it can be
+ * driven from the demo app on a real device as well as from continuous
+ * integration.
+ */
+
+import type { NotificationEngineAdapter } from '../../engine/adapter';
+import type { ResolvedTone } from '../../contract/channel';
+
+const TONE: ResolvedTone = {
+	toneId: 'conformance',
+	version: 1,
+	android: {
+		channelId: 'conformance.v1',
+		importance: 'default',
+		vibration: false,
+		badge: false,
+		bypassDnd: false,
+		name: 'Fixture tone',
+		loopSound: false,
+		alarmCategory: false,
+	},
+	ios: {
+		categoryId: 'conformance',
+		interruptionLevel: 'active',
+		badge: false,
+		repeatRefused: false,
+	},
+};
+
+export interface ConformanceCheck {
+	readonly name: string;
+	readonly passed: boolean;
+	readonly detail?: string;
+}
+
+export interface ConformanceReport {
+	readonly adapter: string;
+	readonly checks: readonly ConformanceCheck[];
+	readonly passed: number;
+	readonly failed: number;
+}
+
+export interface ConformanceOptions {
+	/** Injected so the suite never depends on wall-clock time. */
+	readonly now?: () => number;
+	/** Identifier prefix, so a device run cannot collide with real notifications. */
+	readonly prefix?: string;
+}
+
+export async function runConformanceSuite(
+	adapter: NotificationEngineAdapter,
+	options: ConformanceOptions = {},
+): Promise<ConformanceReport> {
+	const now = options.now ?? (() => Date.now());
+	const prefix = options.prefix ?? 'conformance';
+	const checks: ConformanceCheck[] = [];
+
+	const check = async (name: string, run: () => Promise<boolean | string>): Promise<void> => {
+		try {
+			const outcome = await run();
+			checks.push(
+				outcome === true
+					? { name, passed: true }
+					: {
+							name,
+							passed: false,
+							detail: typeof outcome === 'string' ? outcome : 'returned false',
+						},
+			);
+		} catch (error) {
+			checks.push({
+				name,
+				passed: false,
+				detail: error instanceof Error ? error.message : String(error),
+			});
+		}
+	};
+
+	const id = (suffix: string) => `${prefix}:${suffix}`;
+	const at = now() + 3_600_000;
+
+	const schedule = (suffix: string, overrides: Record<string, unknown> = {}) =>
+		adapter.schedule({
+			request: {
+				id: id(suffix),
+				content: { title: `Conformance ${suffix}`, body: 'Suite entry' },
+				tone: 'conformance',
+				moment: { at },
+				...overrides,
+			},
+			resolvedAt: at,
+			tone: TONE,
+			approximate: false,
+		});
+
+	// Start clean so a previous run cannot mask a failure.
+	await adapter.cancelAll();
+
+	await check('reports its capabilities', async () => {
+		const capabilities = await adapter.getCapabilities();
+		return (
+			capabilities.pendingCeiling > 0 ||
+			`pendingCeiling must be positive, got ${capabilities.pendingCeiling}`
+		);
+	});
+
+	await check('schedules and reads back an entry', async () => {
+		await schedule('a');
+		const pending = await adapter.getPending();
+		return pending.some(entry => entry.id === id('a')) || 'scheduled entry was not returned';
+	});
+
+	await check('returns enough detail to diff, not merely to count', async () => {
+		const [entry] = (await adapter.getPending()).filter(e => e.id === id('a'));
+		if (entry === undefined) return 'entry missing';
+
+		return (
+			(entry.content.title.length > 0 && entry.resolvedAt > 0 && entry.anchoring !== undefined) ||
+			'entry lacked content, instant, or anchoring mode'
+		);
+	});
+
+	await check('replaces rather than duplicates on the same identifier', async () => {
+		await schedule('a', { content: { title: 'Replaced', body: 'Newer' } });
+		const matching = (await adapter.getPending()).filter(entry => entry.id === id('a'));
+		return matching.length === 1 || `expected exactly 1 entry, found ${matching.length}`;
+	});
+
+	await check('round-trips a routing payload unchanged', async () => {
+		await schedule('routing', { routing: { screen: 'task', nested: { deep: true } } });
+		const entry = (await adapter.getPending()).find(e => e.id === id('routing'));
+		return (
+			JSON.stringify(entry?.routing) ===
+				JSON.stringify({ screen: 'task', nested: { deep: true } }) ||
+			`routing payload changed: ${JSON.stringify(entry?.routing)}`
+		);
+	});
+
+	await check('preserves the anchoring mode it was given', async () => {
+		await schedule('absolute', { moment: { at, anchoring: 'absolute' } });
+		const entry = (await adapter.getPending()).find(e => e.id === id('absolute'));
+		return entry?.anchoring === 'absolute' || `expected absolute, got ${entry?.anchoring}`;
+	});
+
+	await check('cancels one entry without touching the others', async () => {
+		const before = (await adapter.getPending()).length;
+		await adapter.cancel(id('a'));
+		const after = await adapter.getPending();
+
+		return (
+			(after.length === before - 1 && !after.some(entry => entry.id === id('a'))) ||
+			'cancel removed the wrong number of entries'
+		);
+	});
+
+	await check('cancelling something absent is harmless', async () => {
+		await adapter.cancel(id('never-existed'));
+		return true;
+	});
+
+	await check('reports permission state without throwing', async () => {
+		const state = await adapter.getPermission('display');
+		return (
+			['notAsked', 'granted', 'denied', 'permanentlyDenied', 'provisional', 'notRequired'].includes(
+				state,
+			) || `unexpected permission state: ${state}`
+		);
+	});
+
+	await check('reports background restrictions, admitting unknown', async () => {
+		const report = await adapter.getRestrictions();
+		return (
+			['unrestricted', 'restricted', 'unknown'].includes(report.batteryOptimization) ||
+			`unexpected restriction status: ${report.batteryOptimization}`
+		);
+	});
+
+	await check('returns pending entries in ascending delivery order', async () => {
+		const pending = await adapter.getPending();
+		const instants = pending.map(entry => entry.resolvedAt);
+		const sorted = [...instants].sort((x, y) => x - y);
+		return JSON.stringify(instants) === JSON.stringify(sorted) || 'entries were not time-ordered';
+	});
+
+	await check('cancelAll leaves nothing behind', async () => {
+		await adapter.cancelAll();
+		const pending = await adapter.getPending();
+		return pending.length === 0 || `${pending.length} entries survived cancelAll`;
+	});
+
+	// --- Repeat expiry -------------------------------------------------------
+	// A substituted engine must be checked on these, not trusted: every one of
+	// them is a way to end up with a device that will not stop ringing, or with
+	// a consumer cancelling an artifact it was never meant to see.
+
+	await check('answers whether it can repeat an alert, rather than guessing', async () => {
+		const capabilities = await adapter.getCapabilities();
+		return (
+			typeof capabilities.supportsRepeatingAlert === 'boolean' ||
+			'supportsRepeatingAlert was not a boolean'
+		);
+	});
+
+	await check('reports a repeating alert it cannot honour', async () => {
+		const capabilities = await adapter.getCapabilities();
+		if (capabilities.supportsRepeatingAlert) return true;
+
+		// A partially emulated repeat is worse than an honest refusal: the
+		// consumer believes the alarm is bounded when nothing bounds it.
+		const repeating: ResolvedTone = {
+			...TONE,
+			android: { ...TONE.android, loopSound: true, repeatForMs: 900_000 },
+			ios: { ...TONE.ios, repeatRefused: true },
+		};
+		return repeating.ios.repeatRefused || 'refusal was not recorded on the resolved tone';
+	});
+
+	await check('keeps stop markers out of the consumer-visible pending set', async () => {
+		const stops = await adapter.listRepeatStops();
+		const pending = await adapter.getPending();
+		const leaked = pending.filter(entry => stops.some(stop => stop.markerId === entry.id));
+		return (
+			leaked.length === 0 ||
+			`${leaked.length} package-owned marker(s) were reported as consumer notifications`
+		);
+	});
+
+	await check('silencing a notification that is gone is an answer, not a failure', async () => {
+		// The ordinary case after the user has handled it. An engine that throws
+		// here turns the commonest path into an error.
+		const silenced = await adapter.silenceDelivered(id('never-displayed'));
+		return silenced === false || 'reported silencing a notification it was not displaying';
+	});
+
+	await check('says whether a background delivery handler is registered', async () => {
+		return (
+			typeof adapter.hasBackgroundDeliveryHandler() === 'boolean' ||
+			'hasBackgroundDeliveryHandler was not a boolean'
+		);
+	});
+
+	const passed = checks.filter(entry => entry.passed).length;
+
+	return {
+		adapter: adapter.name,
+		checks,
+		passed,
+		failed: checks.length - passed,
+	};
+}